Disbursement Webhook - Singapay Documentation

Money Out Operation — This webhook fires when funds are transferred from your SingaPay account to a beneficiary’s bank account.

Information

Method	Path	Format	Authentication
POST	`https://your-webhook-url/callback`	json	HMAC SHA512 Signature

SingaPay sends a POST request to your configured disbursement_notif_url when a disbursement transaction is successfully processed or fails.

This webhook may share a callback URL with other event types. See Shared webhook endpoints for routing by event value.

Request Details

Headers

Field	Value	Type	Mandatory	Description
`Content-Type`	`application/json`	Alphabetic	Yes	Specifies JSON format for the request body
`User-Agent`	`SingaPaymentGateway/1.0`	Alphabetic	Yes	Identifies the source of the webhook
`Accept`	`application/json`	Alphabetic	Yes	Expected response format
`X-PARTNER-ID`	—	Alphanumeric	Yes	Your API Key from the merchant dashboard
`X-Signature`	—	Alphanumeric	Yes	HMAC SHA512 signature (128 chars) for request verification
`X-Timestamp`	—	Numeric	Yes	Unix timestamp in seconds when the request was sent
`Authorization`	`Bearer <access_token>`	Alphanumeric	Yes	JWT bearer token; also used as component in the signature

All signature-related headers (X-Signature, X-Timestamp, Authorization) are always included when your merchant account has API credentials configured. Extract the access token from the Authorization header and use it as-is in the string to sign. See How to Validate Signature below.

Body Parameters

response_code

string

required

Response code. See Appendix 01 — Response Codes. Example: SP000

response_message

string

required

Human-readable response message. Example: Successfully

event

string

required

Transaction type identifier. Always "disbursement" for bank transfer. Use this to distinguish from "ewallet-topup" and "qris-issuer" on the shared URL.

data

object

required

Response payload object.

Show data fields

transaction_id

string

required

System-generated transaction ID. Example: "1512220251105174015668"

reference_number

string

required

Your unique merchant reference number. Example: "123456789123"

transaction_status

object

required

Transaction status object. See Appendix 02 — Transaction Status.

Show transaction_status fields

code

string

required

Status code. E.g. "00", "01", "06"

desc

string

required

Status description. E.g. "Success", "Initiated", "Failed"

post_timestamp

string

required

Transaction creation time in Unix milliseconds. Example: "1762339215000"

processed_timestamp

string

Processing completion time in Unix milliseconds. Empty string if the transaction failed.

bank

object

required

Beneficiary bank information.

Show bank fields

code

string

required

Bank Swift or number code. E.g. "002", "BRINIDJA"

name

string

required

Bank name. E.g. "BRI", "BNI", "DANAMON"

account_name

string

Beneficiary account holder name. null if the account inquiry failed.

account_number

string

required

Beneficiary bank account number. Example: "521398319083210"

gross_amount

object

required

Total amount including fees.

Show gross_amount fields

currency

string

required

ISO 4217 currency code. Example: "IDR"

value

string

required

Amount value. Example: "50000"

fee

object

required

Transfer fee details.

Show fee fields

currency

string

required

ISO 4217 currency code.

value

string

required

Fee amount. Example: "3000"

net_amount

object

required

Amount received by the beneficiary (gross_amount − fee).

Show net_amount fields

currency

string

required

ISO 4217 currency code.

value

string

required

Net amount value. Example: "47000"

balance_after

object

required

Your account balance after the transaction. Both fields are null for failed transactions.

Show balance_after fields

currency

string

ISO 4217 currency code. null if failed.

value

string

Balance value. null if failed. Example: "777000"

notes

string

Transaction notes from the original request. Example: "bayar pajak"

failed_code

string

Error code. Only present when the transaction status is failed. Example: "SP003"

failed_reason

string

Human-readable error message. Only present when the transaction status is failed. Example: "INSUFFICIENT BALANCE"

Payload Examples

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "event": "disbursement",
    "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"
    }
}

Security and responses

Return HTTP 200 promptly after validating the request. For retry behavior, see Webhook retry mechanism. Verify every webhook using Security and signature validation. Use your configured callback path when building StringToSign. Handle duplicate deliveries idempotently using stable identifiers from the payload (for example transaction_id or reff_no).

Disbursement-Specific Notes

Idempotency

Each reference_number can only be used once per account. If you retry with the same reference_number, you’ll receive the existing transaction status rather than creating a duplicate transfer.

Detecting Duplicate Webhooks

$referenceNumber = $payload['data']['reference_number'];

// Check if already processed
$existingTransaction = findTransactionByReference($referenceNumber);
if ($existingTransaction) {
    // Already processed — return 200 without re-processing
    http_response_code(200);
    exit;
}

processNewDisbursement($payload);

Timestamp Formats

Disbursement webhooks use two different timestamp formats. Don’t mix them up.

Field	Format	Example	Notes
`X-Timestamp` header	Unix seconds	`1695711945`	Used for signature validation
`post_timestamp` (body)	Unix milliseconds	`1762339215000`	Divide by 1000 to convert
`processed_timestamp` (body)	Unix milliseconds	`1762339215672`	Empty string if transaction failed

Converting millisecond timestamps

// Convert to DateTime
$postTimestamp = $payload['data']['post_timestamp']; // "1762339215000"
$date = new DateTime();
$date->setTimestamp((int)($postTimestamp / 1000));

// Or with Carbon (Laravel)
$date = \Carbon\Carbon::createFromTimestampMs($postTimestamp);

Balance Reconciliation

The balance_after field shows your account balance after each transaction. For failed transactions, both currency and value are null — no balance change occurred.

Balance Consistency Check

if ($payload['data']['transaction_status']['code'] === '00') {
    $balanceAfter = (float)$payload['data']['balance_after']['value'];
    $grossAmount  = (float)$payload['data']['gross_amount']['value'];

    $expectedBalance = $previousBalance - $grossAmount;
    if (abs($balanceAfter - $expectedBalance) > 0.01) {
        // Balance mismatch — log for investigation
        logBalanceDiscrepancy($transactionId, $expectedBalance, $balanceAfter);
    }
}

Appendix

01: Response Codes

Code	Message	Description	Action
`SP000`	Successfully	Success	Check inquiry status
`SP001`	Transaction Failure	Failed transaction	Check inquiry status
`SP002`	General Failure	Internal server error	Check inquiry status
`SP003`	Insufficient Balance	Account balance too low	Check inquiry status
`SP004`	Duplicate Reference Number	Reference already used	—
`SP005`	Timeout	Gateway timeout	Check inquiry status
`SP006`	Exceed Beneficiary Limit	Beneficiary amount limit reached	Check inquiry status
`SP007`	Exceed Account Limit	Account transaction limit reached	Contact IT Support
`SP008`	Invalid Reference Number	Reference does not exist	—
`SP009`	Transaction Not Found	Transaction not found	—
`SP010`	Beneficiary Account Not Found	Account not found	—
`SP011`	Beneficiary Vendor Not Active	Vendor not active	—
`SP012`	Bad Request	Bad request	—
`SP013`	Unauthorized	Unauthorized	—
`SP014`	Not Found	Not found	—
`SP015`	Forbidden	Forbidden	—
`SP016`	Signature Invalid	Signature invalid	—
`SP017`	Unauthorized IP	IP not authorized	Contact IT Support
`SP018`	Validation Error	Payload validation error	—
`SP019`	General Error	General error	Contact IT Support
`SP020`	Merchant Account Not Found	Merchant account not found	—

02: Transaction Status

Code	Status	Notes
`00`	Success	Transaction completed successfully
`01`	Initiated	Payment call not yet received; retry is possible
`02`	Paying	Pending/Suspect — retry status check in a few minutes; awaiting final callback
`03`	Pending	Pending/Suspect — retry status check in a few minutes; awaiting final callback
`04`	Refunded	Reversal transaction
`05`	Canceled	Create a new transaction
`06`	Failed	Transaction failed
`07`	Not Found	Create a new transaction

​Information

​Request Details

​Headers

​Body Parameters

​Payload Examples

​Security and responses

​Disbursement-Specific Notes

​Idempotency

​Timestamp Formats

​Balance Reconciliation

​Appendix

​01: Response Codes

​02: Transaction Status

Information

Request Details

Headers

Body Parameters

Payload Examples

Security and responses

Disbursement-Specific Notes

Idempotency

Timestamp Formats

Balance Reconciliation

Appendix

01: Response Codes

02: Transaction Status