E-Wallet Top Up Webhook

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

string

required

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

string

required

Human-readable response message. Example: Successfully

string

required

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

object

required

Response payload object.

Show data fields

string

required

System-generated transaction ID. Example: "EW1512220251105174015668"

string

required

Your unique merchant reference number. Example: "REF123456789"

string

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

object

required

Transaction status object. See Appendix 02 — Transaction Status.

Show transaction_status fields

string

required

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

string

required

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

string

required

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

string

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

object

required

E-wallet beneficiary information.

Show ewallet fields

string

required

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

string

required

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

string

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

object

required

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

Show gross_amount fields

string

required

ISO 4217 currency code. Example: "IDR"

string

required

Gross amount value. Example: "50000.00"

object

required

Admin fee charged for this transaction.

Show fee fields

string

required

ISO 4217 currency code.

string

required

Fee amount. Example: "2500.00"

object

required

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

Show net_amount fields

string

required

ISO 4217 currency code.

string

required

Net amount value. Example: "47500.00"

object

required

Your merchant account balance after the transaction.

Show balance_after fields

string

ISO 4217 currency code. Empty string if unavailable.

string

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

string

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

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"
        }
    }
}

{
    "response_code": "SP001",
    "response_message": "Transaction Failure",
    "event": "ewallet-topup",
    "data": {
        "transaction_id": "EW121222025122617513896515436",
        "reference_number": "REF-EWALLET-002",
        "notes": "topup DANA pelanggan",
        "transaction_status": {
            "code": "06",
            "desc": "Failed"
        },
        "post_timestamp": "1766978900000",
        "processed_timestamp": "",
        "ewallet": {
            "code": "DANA",
            "customer_number": "08198765432",
            "customer_name": null
        },
        "gross_amount": {
            "currency": "IDR",
            "value": "100000.00"
        },
        "fee": {
            "currency": "IDR",
            "value": "2500.00"
        },
        "net_amount": {
            "currency": "IDR",
            "value": "97500.00"
        },
        "balance_after": {
            "currency": "IDR",
            "value": "850000"
        },
        "failed_code": "CONNECTION_ERROR",
        "failed_reason": "Connection timeout to vendor"
    }
}

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

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

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

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