Authentication

# 1. Build the string to sign (v3) — five parts joined with "|"
POST|api/v1/transaction/create|1699564800|5f2c9e1a7b3d4c68a1e0b9d2c3f4a5b6|{"ref":"ORDER-1001","amount":100.5,"currency":"USD","websiteUrl":"https://example.com","redirectUrl":"https://example.com/payment/success","cancelUrl":"https://example.com/payment/cancel","description":"Premium subscription - monthly","customerDetails":{"firstName":"John","lastName":"Doe","email":"[email protected]","country":"US","ip":"203.0.113.10","phoneCode":"US","phoneNumber":"5551234567"}}

# 2. Sign it with your SECRET KEY (not the key ID) — lowercase hex, sent as is (no prefix)
#    secret_key used for this example: sk_test_docs_example_secret_0000000000000000000000000000000000000000
X-Signature = HMAC-SHA256(secret_key, string_to_sign)
           = 459983afd8b42d0ea5ece82606a782345b2b07c6caa0de44c38da32edcb71371

POST /api/v1/transaction/create HTTP/1.1
Host: staging-gateway.epayse.com
Content-Type: application/json
X-Api-Key-Id: 01docsexampleapikeyid00000
X-Signature: 459983afd8b42d0ea5ece82606a782345b2b07c6caa0de44c38da32edcb71371
X-Timestamp: 1699564800
X-Nonce: 5f2c9e1a7b3d4c68a1e0b9d2c3f4a5b6
X-Signature-Version: 3

{
  "ref": "ORDER-1001",
  "amount": 100.5,
  "currency": "USD",
  "websiteUrl": "https://example.com",
  "redirectUrl": "https://example.com/payment/success",
  "cancelUrl": "https://example.com/payment/cancel",
  "description": "Premium subscription - monthly",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "country": "US",
    "ip": "203.0.113.10",
    "phoneCode": "US",
    "phoneNumber": "5551234567"
  }
}

curl -X POST "https://staging-gateway.epayse.com/api/v1/transaction/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-Id: 01docsexampleapikeyid00000" \
  -H "X-Signature: 459983afd8b42d0ea5ece82606a782345b2b07c6caa0de44c38da32edcb71371" \
  -H "X-Timestamp: 1699564800" \
  -H "X-Nonce: 5f2c9e1a7b3d4c68a1e0b9d2c3f4a5b6" \
  -H "X-Signature-Version: 3" \
  -d '{"ref":"ORDER-1001","amount":100.5,"currency":"USD","websiteUrl":"https://example.com","redirectUrl":"https://example.com/payment/success","cancelUrl":"https://example.com/payment/cancel","description":"Premium subscription - monthly","customerDetails":{"firstName":"John","lastName":"Doe","email":"[email protected]","country":"US","ip":"203.0.113.10","phoneCode":"US","phoneNumber":"5551234567"}}'

<?php
// Manual request signing in PHP (signature version 3)
$gateway   = 'https://staging-gateway.epayse.com';
$apiKeyId  = 'your_api_key_id';   // the ID shown next to the key in your dashboard
$secretKey = 'sk_test_...';       // shown once when you generate the key

$path      = 'api/v1/transaction/create';   // no leading slash; add ?query if you send one
$body      = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$timestamp = time();
$nonce     = bin2hex(random_bytes(16));   // new value for every request

// METHOD|PATH|TIMESTAMP|NONCE|BODY
$stringToSign = implode('|', ['POST', $path, $timestamp, $nonce, $body]);
$signature    = hash_hmac('sha256', $stringToSign, $secretKey);

$ch = curl_init($gateway . '/' . $path);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key-Id: ' . $apiKeyId,
        'X-Signature: ' . $signature,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Signature-Version: 3',
    ],
]);

echo curl_exec($ch);
curl_close($ch);

// Manual request signing in JavaScript / Node.js (signature version 3)
import crypto from 'crypto';

const GATEWAY = 'https://staging-gateway.epayse.com';
const API_KEY_ID = 'your_api_key_id';      // the ID shown next to the key in your dashboard
const SECRET_KEY = 'sk_test_...';          // shown once when you generate the key

const path = 'api/v1/transaction/create';          // no leading slash; add ?query if you send one
const body = JSON.stringify(payload);       // sign the EXACT string you send
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(16).toString('hex');   // new value for every request

// METHOD|PATH|TIMESTAMP|NONCE|BODY
const stringToSign = ['POST', path, timestamp, nonce, body].join('|');
const signature = crypto.createHmac('sha256', SECRET_KEY).update(stringToSign).digest('hex');

const response = await fetch(`${GATEWAY}/${path}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key-Id': API_KEY_ID,
    'X-Signature': signature,
    'X-Timestamp': String(timestamp),
    'X-Nonce': nonce,
    'X-Signature-Version': '3',
  },
  body,
});
console.log(await response.json());