Disbursements Transfer

​Information

​Request Details

​Headers Structure

​Body Structure

​Body Example

{
    "account_id": "01K8N5ZNJH8MPGAK9QM080CXW8",
    "reference_number" : "5176770190020260101114",
    "bank_account_number": "8330432404",
    "amount": 10000,
    "bank_code": "014",
    "notes": "payroll bulan ini"
}

​Response Details

​Response Structure

​Response Example

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "transaction_id": "101222025122910292195055674",
        "reference_number": "11111111118",
        "transaction_status": {
            "code": "00",
            "desc": "Success"
        },
        "post_timestamp": "1766978961000",
        "processed_timestamp": "1766978962000",
        "bank": {
            "code": "002",
            "name": "BRI",
            "account_name": "Dummy Test Account Internal",
            "account_number": "11111111118"
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "12504.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "10004.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "829988"
        },
        "notes": "test transfer"
    }
}

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "transaction_id": "101222025122910321260732119",
        "reference_number": "33311111111",
        "transaction_status": {
            "code": "03",
            "desc": "Pending"
        },
        "post_timestamp": "1766979132000",
        "processed_timestamp": "",
        "bank": {
            "code": "002",
            "name": "BRI",
            "account_name": "",
            "account_number": "33311111111"
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "12506.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "10006.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "0"
        },
        "notes": "test transfer"
    }
}

{
    "response_code": "SP001",
    "response_message": "Transaction Failure",
    "data": {
        "transaction_id": "121222025122617513896515436",
        "reference_number": "333",
        "transaction_status": {
            "code": "06",
            "desc": "Failed"
        },
        "post_timestamp": "1766746298000",
        "processed_timestamp": "",
        "bank": {
            "code": "002",
            "name": "BRI",
            "account_name": "",
            "account_number": "091701064838533"
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "12501.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "10001.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "0"
        },
        "notes": "test transfer",
        "failed_reason": "Transaction Failure : Invalid beneficiary account: Account inactive",
        "failed_code": "SP001"
    }
}

{
    "response_code": "SP004",
    "response_message": "Duplicate Reference Number",
    "data": {
        "account_id": "01K5G4FZZ18DMK0M5QTR8Y9QY9",
        "reference_number": "331",
        "amount": 61000,
        "notes": "test transfer",
        "bank_code": "BRINIDJA",
        "bank_account_number": "091701064838533",
        "message": "Transaction with this reference number already exists"
    }
}

{
    "response_code": "SP018",
    "response_message": "Validation error",
    "data": {
        "account_id": "01K8J8GBTB88H9Z6DVMY1XMJP8",
        "reference_number": "331",
        "amount": 61000,
        "notes": "test transfer",
        "bank_code": null,
        "bank_account_number": "091701064838533",
        "message": "Validation error 'bank_code': 'The bank code field is required.'"
    }
}

{
    "response_code": "SP003",
    "response_message": "Insufficient Balance",
    "data": {
        "transaction_id": "291222025122617393593025327",
        "reference_number": "331",
        "transaction_status": {
            "code": "06",
            "desc": "Failed"
        },
        "post_timestamp": "1766745575000",
        "processed_timestamp": "",
        "bank": {
            "code": "002",
            "name": "BRI",
            "account_name": "",
            "account_number": "091701064838533"
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "63500.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "61000.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "0"
        },
        "notes": "test transfer"
    }
}

{
    "response_code": "SP019",
    "response_message": "General Error",
    "data": {
        "account_id": "01K5G4FZZ18DMK0M5QTR8Y9QY9",
        "reference_number": "331",
        "amount": 61000,
        "notes": "test transfer",
        "bank_code": "BRINIDJA",
        "bank_account_number": "091701064838533",
        "message": "internal server error"
    }
}

{
    "status": 401,
    "success": false,
    "error": {
        "code": 401,
        "message": "Unauthorized merchant, please sign in"
    }
}

{
    "status": 401,
    "success": false,
    "error": {
        "code": 4019900,
        "message": "Unauthorized. Invalid X-SIGNATURE"
    }
}

​List of Bank Swift Codes Supported

​Related Documentation

For detailed information about response codes and transaction statuses, refer to:

• Response Code Reference - Complete list of API response codes
• Transaction Status Reference - Complete list of transaction status codes

​How to Generate Request Signature

Every transaction request must include an X-Signature header that will be validated by SingaPay. If the signature is invalid, the request will be rejected.

​Signature Algorithm

The signature uses HMAC-SHA512 algorithm with the following steps:

​Step 1: Normalize the Request Body

Sort all JSON object keys recursively in alphabetical order, then encode using:

• JSON_UNESCAPED_UNICODE - Don’t escape unicode characters
• JSON_UNESCAPED_SLASHES - Don’t escape forward slashes

Example:

// Original body (key order doesn't matter)
{
  "notes": "bayar cicilan",
  "amount": 50000,
  "bank_swift_code": "BRINIDJA",
  "reference_number": "123456789123",
  "bank_account_number": "521398319083210"
}

// Normalized (keys sorted alphabetically)
{"amount":50000,"bank_account_number":"521398319083210","bank_swift_code":"BRINIDJA","notes":"bayar cicilan","reference_number":"123456789123"}

​Step 2: Hash the Normalized Body

Hash the normalized JSON string using SHA-256:

hashedBody = SHA256(normalizedBody)

Example:

hashedBody = "a1b2c3d4e5f6789..."

​Step 3: Build the String to Sign

Combine the following components with colon (:) separator:

stringToSign = METHOD:ENDPOINT:ACCESS_TOKEN:HASHED_BODY:TIMESTAMP

Where:

• METHOD = HTTP method (e.g., POST)
• ENDPOINT = Request URI path (e.g., /api/v1.0/disbursements/{account_id}/transfer)
• ACCESS_TOKEN = Bearer token from Authorization header (without “Bearer ” prefix)
• HASHED_BODY = SHA-256 hash from Step 2
• TIMESTAMP = Unix timestamp in seconds (from X-Timestamp header)

Example:

POST:/api/v1.0/disbursements/abc123/transfer:eyJ0eXAiOiJKV1QiLCJhbGc...:a1b2c3d4e5f6789...:1714618220

​Step 4: Generate HMAC-SHA512 Signature

Generate the signature using HMAC-SHA512 with your client_secret as the key:

signature = HMAC_SHA512(stringToSign, client_secret)

The output is a hexadecimal string (not base64).

​Code Examples

​PHP Example

<?php
function generateSignature($method, $endpoint, $accessToken, $body, $timestamp, $clientSecret) {
    // Step 1: Normalize body
    $bodyArray = json_decode($body, true);
    ksort($bodyArray);
    array_walk_recursive($bodyArray, function(&$item) {
        if (is_array($item)) ksort($item);
    });
    $normalizedBody = json_encode($bodyArray, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

    // Step 2: Hash normalized body
    $hashedBody = hash('sha256', $normalizedBody);

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

    // Step 4: Generate HMAC-SHA512 signature
    $signature = hash_hmac('sha512', $stringToSign, $clientSecret);

    return $signature;
}

// Usage
$signature = generateSignature(
    'POST',
    '/api/v1.0/disbursements/abc123/transfer',
    'eyJ0eXAiOiJKV1QiLCJhbGc...',
    '{"amount":50000,"bank_account_number":"521398319083210","bank_swift_code":"BRINIDJA","notes":"bayar cicilan","reference_number":"123456789123"}',
    '1714618220',
    'your_client_secret_here'
);
?>

​JavaScript/Node.js Example

const crypto = require('crypto');

function sortObjectKeys(obj) {
    if (typeof obj !== 'object' || obj === null) return obj;
    if (Array.isArray(obj)) return obj.map(sortObjectKeys);

    return Object.keys(obj)
        .sort()
        .reduce((sorted, key) => {
            sorted[key] = sortObjectKeys(obj[key]);
            return sorted;
        }, {});
}

function generateSignature(method, endpoint, accessToken, body, timestamp, clientSecret) {
    // Step 1: Normalize body
    const bodyObject = JSON.parse(body);
    const sortedBody = sortObjectKeys(bodyObject);
    const normalizedBody = JSON.stringify(sortedBody);

    // Step 2: Hash normalized body
    const hashedBody = crypto
        .createHash('sha256')
        .update(normalizedBody)
        .digest('hex');

    // Step 3: Build string to sign
    const stringToSign = `${method}:${endpoint}:${accessToken}:${hashedBody}:${timestamp}`;

    // Step 4: Generate HMAC-SHA512 signature
    const signature = crypto
        .createHmac('sha512', clientSecret)
        .update(stringToSign)
        .digest('hex');

    return signature;
}

// Usage
const signature = generateSignature(
    'POST',
    '/api/v1.0/disbursements/abc123/transfer',
    'eyJ0eXAiOiJKV1QiLCJhbGc...',
    '{"amount":50000,"bank_account_number":"521398319083210","bank_swift_code":"BRINIDJA","notes":"bayar cicilan","reference_number":"123456789123"}',
    '1714618220',
    'your_client_secret_here'
);

​Python Example

import hashlib
import hmac
import json

def sort_dict_recursive(obj):
    if isinstance(obj, dict):
        return {k: sort_dict_recursive(v) for k, v in sorted(obj.items())}
    elif isinstance(obj, list):
        return [sort_dict_recursive(item) for item in obj]
    return obj

def generate_signature(method, endpoint, access_token, body, timestamp, client_secret):
    # Step 1: Normalize body
    body_dict = json.loads(body)
    sorted_body = sort_dict_recursive(body_dict)
    normalized_body = json.dumps(sorted_body, ensure_ascii=False, separators=(',', ':'))

    # Step 2: Hash normalized body
    hashed_body = hashlib.sha256(normalized_body.encode()).hexdigest()

    # Step 3: Build string to sign
    string_to_sign = f"{method}:{endpoint}:{access_token}:{hashed_body}:{timestamp}"

    # Step 4: Generate HMAC-SHA512 signature
    signature = hmac.new(
        client_secret.encode(),
        string_to_sign.encode(),
        hashlib.sha512
    ).hexdigest()

    return signature

# Usage
signature = generate_signature(
    'POST',
    '/api/v1.0/disbursements/abc123/transfer',
    'eyJ0eXAiOiJKV1QiLCJhbGc...',
    '{"amount":50000,"bank_account_number":"521398319083210","bank_swift_code":"BRINIDJA","notes":"bayar cicilan","reference_number":"123456789123"}',
    '1714618220',
    'your_client_secret_here'
)

​Important Notes

1. Timestamp Format: Must be Unix timestamp in seconds (not milliseconds, not ISO 8601)
2. Access Token: Extract from Authorization header without “Bearer ” prefix
3. Endpoint: Must include the full path starting with /api/v1.0/... and include the {account_id} parameter
4. JSON Normalization: Keys must be sorted recursively for nested objects
5. Hash Output: Use hexadecimal encoding (not base64)
6. Client Secret: Use your client_secret from merchant credentials, NOT your client_id or api_key

​Security Validation

SingaPay will:

1. Verify the X-PARTNER-ID matches an existing API key
2. Retrieve the corresponding client_secret from the credentials table
3. Regenerate the signature using the same algorithm
4. Use constant-time comparison (hash_equals) to prevent timing attacks
5. Reject the request if signatures don’t match