E-Wallet Top Up Webhook - Singapay Documentation

Money Out Operation — This webhook fires when an E-Wallet Top Up transaction is completed (success or failed), transferring funds from your SingaPay account to a customer’s e-wallet.

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 an E-Wallet Top Up transaction is completed (success or failed).

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 "ewallet-topup" for this webhook. Use this to distinguish from "disbursement" 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: "EW1512220251105174015668"

reference_number

string

required

Your unique merchant reference number. Example: "REF123456789"

notes

string

Transaction notes from the original request. Example: "topup OVO pelanggan"

transaction_status

object

required

Transaction status object. See Appendix 02 — Transaction Status.

Show transaction_status fields

code

string

required

Status code. "00" = Success, "06" = Failed

desc

string

required

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

post_timestamp

string

required

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

processed_timestamp

string

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

ewallet

object

required

E-wallet beneficiary information.

Show ewallet fields

code

string

required

E-wallet provider code. E.g. "OVO", "DANA", "GOPAY", "LINKAJA", "SHOPEEPAY"

customer_number

string

required

Customer’s e-wallet phone number or account number. Example: "08123456789"

customer_name

string

Customer’s name on the e-wallet. null if account inquiry is not available.

gross_amount

object

required

Total amount deducted from your merchant balance (net + fee).

Show gross_amount fields

currency

string

required

ISO 4217 currency code. Example: "IDR"

value

string

required

Gross amount value. Example: "50000.00"

fee

object

required

Admin fee charged for this transaction.

Show fee fields

currency

string

required

ISO 4217 currency code.

value

string

required

Fee amount. Example: "2500.00"

net_amount

object

required

Net amount received by the customer (gross_amount − fee).

Show net_amount fields

currency

string

required

ISO 4217 currency code.

value

string

required

Net amount value. Example: "47500.00"

balance_after

object

required

Your merchant account balance after the transaction.

Show balance_after fields

currency

string

ISO 4217 currency code. Empty string if unavailable.

value

string

Balance value. Empty string if unavailable. Example: "750000"

failed_code

string

Error code. Only present when the transaction failed. Example: "CONNECTION_ERROR"

failed_reason

string

Human-readable error description. Only present when the transaction failed. Example: "Connection timeout to vendor"

Payload Examples

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "event": "ewallet-topup",
    "data": {
        "transaction_id": "EW101222025122910292195055674",
        "reference_number": "REF-EWALLET-001",
        "notes": "topup OVO pelanggan",
        "transaction_status": {
            "code": "00",
            "desc": "Success"
        },
        "post_timestamp": "1766978961000",
        "processed_timestamp": "1766978962000",
        "ewallet": {
            "code": "OVO",
            "customer_number": "08123456789",
            "customer_name": "Budi Santoso"
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "50000.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500.00"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "47500.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "750000"
        }
    }
}

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).

E-Wallet Top Up 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 top up.

Detecting Duplicate Webhooks

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

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

processEwalletTopUp($payload);

Timestamp Formats

E-Wallet Top Up 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	`1766978961000`	Divide by 1000 to convert
`processed_timestamp` (body)	Unix milliseconds	`1766978962000`	Empty string if transaction failed

When validating signatures, always use the X-Timestamp header value (in seconds), not the timestamps from the request body (which are in milliseconds).

Converting millisecond timestamps

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

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

Balance Refund on Failure

When an E-Wallet Top Up fails, SingaPay automatically refunds the full gross_amount (net + fee) back to your merchant balance. You do not need to request a manual refund — the balance is restored immediately upon failure detection. The balance_after field reflects the post-refund balance.

Balance Tracking

The balance_after field shows your account balance after the transaction:

For successful transactions: remaining balance after deduction
For failed transactions: balance after automatic refund (balance is restored)
Use this to verify balance consistency with your system
All amounts are in IDR (Indonesian Rupiah)

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

​E-Wallet Top Up specific notes

​Idempotency

​Timestamp Formats

​Balance Refund on Failure

​Balance Tracking

​Appendix

​01: Response Codes

​02: Transaction Status

Information

Request Details

Headers

Body Parameters

Payload Examples

Security and responses

E-Wallet Top Up specific notes

Idempotency

Timestamp Formats

Balance Refund on Failure

Balance Tracking

Appendix

01: Response Codes

02: Transaction Status