Building the X-Signature Header

Some endpoints require a request signature for authentication, sent as the X-Signature header. There are two different signature schemes, used in two different situations. Both use HMAC-SHA512, but the string being signed is different — read the section relevant to the endpoint you’re calling.

This page covers signatures you generate for outbound requests to the SingaPay API. To validate signatures SingaPay sends you on inbound webhook callbacks, see Security and Signature Validation.

Scheme	Used for	Signed with
Access Token Signature	Obtaining a Bearer access token (`POST /api/v1.1/access-token/b2b`)	Your `client_secret`
Request Signature	Authenticating individual requests to money-out endpoints (Disbursement, Account Transfer, E-Wallet Top Up, etc.)	Your `client_secret`

1. Access Token Signature

Used only when calling POST /api/v1.1/access-token/b2b to obtain a Bearer token.

Formula

payload     = "{client_id}_{client_secret}_{YYYYMMDD}"
X-Signature = HMAC-SHA512(payload, client_secret)   // lowercase hex digest

YYYYMMDD is the current server date (UTC+7 / Asia/Jakarta), e.g. 20260727. The signature is only valid for that calendar day.

Required headers

Header	Description
`X-PARTNER-ID`	Your merchant API key
`X-CLIENT-ID`	Your `client_id`
`X-Signature`	Signature computed as above

Request body

{
  "grant_type": "client_credentials"
}

Examples

$clientId     = 'your_client_id';
$clientSecret = 'your_client_secret';
$currentDate  = date('Ymd'); // e.g. 20260727

$payload   = "{$clientId}_{$clientSecret}_{$currentDate}";
$signature = hash_hmac('sha512', $payload, $clientSecret);

// Headers:
// X-PARTNER-ID: your_api_key
// X-CLIENT-ID: your_client_id
// X-Signature: <$signature>

const crypto = require('crypto');

const clientId = 'your_client_id';
const clientSecret = 'your_client_secret';
const currentDate = new Date().toISOString().slice(0, 10).replace(/-/g, ''); // YYYYMMDD (Asia/Jakarta date)

const payload = `${clientId}_${clientSecret}_${currentDate}`;
const signature = crypto.createHmac('sha512', clientSecret).update(payload).digest('hex');

import hmac
import hashlib
from datetime import datetime

client_id = 'your_client_id'
client_secret = 'your_client_secret'
current_date = datetime.now().strftime('%Y%m%d')  # Asia/Jakarta date

payload = f'{client_id}_{client_secret}_{current_date}'
signature = hmac.new(client_secret.encode(), payload.encode(), hashlib.sha512).hexdigest()

Use the returned access_token as Authorization: Bearer <access_token> on subsequent requests.

2. Request Signature

Used for money-out endpoints that require per-request signing, e.g.:

POST /api/v2.0/disbursement/transfer
POST /api/v2.0/ewallet/trigger-topup
Account Transfer endpoints

Normalize the request body

Sort all object keys recursively and alphabetically.

Hash the normalized body

Hash the normalized JSON with SHA-256 to get hashed_body (hex digest).

Build the string to sign

string_to_sign = "{METHOD}:{ENDPOINT}:{ACCESS_TOKEN}:{hashed_body}:{TIMESTAMP}"

Sign it

X-Signature = HMAC-SHA512(string_to_sign, client_secret)   // lowercase hex digest

Where:

METHOD — HTTP method in uppercase, e.g. POST.
ENDPOINT — the request path including query string, e.g. /api/v2.0/disbursement/transfer. Do not include the domain.
ACCESS_TOKEN — the Bearer token obtained from the access-token endpoint (without the Bearer prefix).
TIMESTAMP — current Unix timestamp in seconds (not milliseconds), sent as a string.

Required headers

Header	Description
`X-PARTNER-ID`	Your merchant API key
`Authorization`	`Bearer <access_token>`
`X-Timestamp`	Unix timestamp (seconds) used in the signature
`X-Signature`	Signature computed as above

Regenerate the signature for every request — the timestamp and body are always part of the signed string, so a signature cannot be reused across requests or replayed after it expires.

Examples

$method      = 'POST';
$endpoint    = '/api/v2.0/disbursement/transfer'; // path + query string, no domain
$accessToken = 'your_bearer_token';
$secretKey   = 'your_client_secret';
$timestamp   = (string) time();

// 1. Normalize body (recursive key sort)
function sortRecursive(array &$arr): void {
    ksort($arr, SORT_STRING);
    foreach ($arr as &$value) {
        if (is_array($value)) {
            sortRecursive($value);
        }
    }
}

$body = [
    'account_number' => '1234567890',
    'amount' => 100000,
    'bank_code' => 'BCA',
];
sortRecursive($body);
$normalizedJson = json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// 2. Hash body
$hashedBody = hash('sha256', $normalizedJson);

// 3. Build string to sign
$stringToSign = "{$method}:{$endpoint}:{$accessToken}:{$hashedBody}:{$timestamp}";

// 4. Sign
$signature = hash_hmac('sha512', $stringToSign, $secretKey);

// Headers:
// X-PARTNER-ID: your_api_key
// Authorization: Bearer your_bearer_token
// X-Timestamp: <$timestamp>
// X-Signature: <$signature>

const crypto = require('crypto');

function sortKeysRecursive(obj) {
  if (Array.isArray(obj)) return obj.map(sortKeysRecursive);
  if (obj !== null && typeof obj === 'object') {
    return Object.keys(obj).sort().reduce((acc, key) => {
      acc[key] = sortKeysRecursive(obj[key]);
      return acc;
    }, {});
  }
  return obj;
}

const method = 'POST';
const endpoint = '/api/v2.0/disbursement/transfer';
const accessToken = 'your_bearer_token';
const secretKey = 'your_client_secret';
const timestamp = Math.floor(Date.now() / 1000).toString();

const body = { account_number: '1234567890', amount: 100000, bank_code: 'BCA' };
const normalizedJson = JSON.stringify(sortKeysRecursive(body));

const hashedBody = crypto.createHash('sha256').update(normalizedJson).digest('hex');
const stringToSign = `${method}:${endpoint}:${accessToken}:${hashedBody}:${timestamp}`;
const signature = crypto.createHmac('sha512', secretKey).update(stringToSign).digest('hex');

import hashlib
import hmac
import json
import time

def sort_keys_recursive(obj):
    if isinstance(obj, list):
        return [sort_keys_recursive(v) for v in obj]
    if isinstance(obj, dict):
        return {k: sort_keys_recursive(obj[k]) for k in sorted(obj.keys())}
    return obj

method = 'POST'
endpoint = '/api/v2.0/disbursement/transfer'
access_token = 'your_bearer_token'
secret_key = 'your_client_secret'
timestamp = str(int(time.time()))

body = {'account_number': '1234567890', 'amount': 100000, 'bank_code': 'BCA'}
normalized_json = json.dumps(sort_keys_recursive(body), separators=(',', ':'), ensure_ascii=False)

hashed_body = hashlib.sha256(normalized_json.encode()).hexdigest()
string_to_sign = f'{method}:{endpoint}:{access_token}:{hashed_body}:{timestamp}'
signature = hmac.new(secret_key.encode(), string_to_sign.encode(), hashlib.sha512).hexdigest()

Common mistakes

Symptom	Likely cause
Signature always invalid	`ENDPOINT` doesn’t match the exact request path (including query string) sent to the server
Signature valid on retry but not first try	Body was modified/reformatted between signing and sending (e.g. number vs. string, key order, extra whitespace)
Signature works for GET but not POST/PUT	`METHOD` not uppercase, or body normalization skipped for empty body
Intermittent 401	Timestamp too old — requests are only accepted within a limited time window from `X-Timestamp`; generate a fresh signature right before sending
Works locally, fails in production	Client secret or client ID mismatch, or numeric fields serialized differently (e.g. `100000` vs `"100000.00"`) across environments

Best practices

Never log or expose your client_secret in client-side code, logs, or version control.
Always use HTTPS.
Generate the signature immediately before sending the request — don’t reuse an old signature/timestamp pair.

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

1. Access Token Signature

Formula

Required headers

Request body

Examples

2. Request Signature

Required headers

Examples

Common mistakes

​1. Access Token Signature

​Formula

​Required headers

​Request body

​Examples

​2. Request Signature

​Required headers

​Examples

​Common mistakes

1. Access Token Signature

Formula

Required headers

Request body

Examples

2. Request Signature

Required headers

Examples

Common mistakes