Response Codes

All Singapay API responses include a response_code field that indicates whether your API request was received and processed correctly by the server.

Response codes are not transaction statuses. A response_code tells you the result of the request itself — whether the server accepted it, rejected it due to validation, or encountered an error. It does not tell you whether the underlying payment succeeded, is pending, or failed. To track the actual payment outcome, use the transaction_status object in the response body or wait for the webhook callback. See Transaction Status for the full lifecycle.

For example, a disbursement request may return response_code: "SP000" (request accepted successfully) while the payment itself is still "Initiated" — the money has not moved yet. Conversely, a webhook may arrive with response_code: "SP001" to notify you that a previously accepted transaction has now failed at the provider.

Response format

{
  "response_code": "SP000",
  "response_message": "Successfully",
  "data": { ... }
}

{
  "response_code": "SP000",
  "response_message": "Successfully",
  "event": "disbursement",
  "data": { ... }
}

Response code dictionary

Each code below describes a request-level outcome — not the state of the payment or transfer.

Success

Code	Message	Description
`SP000`	Successfully	The request was accepted and processed. For transactional endpoints, this means the request was submitted — not that the payment is complete. Check `transaction_status` for the payment outcome.

Transaction request errors

Code	Message	Description	Recommended action
`SP001`	Transaction Failure	The transaction failed during processing.	Call the inquiry-status endpoint to confirm the final state.
`SP002`	General Failure	An internal server error occurred.	Retry after a short delay; call inquiry-status if the issue persists.
`SP003`	Insufficient Balance	The account does not have enough balance to complete the transaction.	Top up the account and retry.
`SP004`	Duplicate Reference Number	A transaction with this `reference_number` already exists.	Use a unique reference number for each new transaction.
`SP005`	Timeout	The upstream provider did not respond in time.	Call the inquiry-status endpoint — the transaction may still settle.
`SP006`	Exceed Beneficiary Limit	The beneficiary has reached their daily or per-transaction limit.	Retry with a lower amount or try again the next business day.
`SP007`	Exceed Account Limit	Your account has reached its transaction limit.	Contact Singapay support to review your limits.

Lookup errors

Code	Message	Description	Recommended action
`SP008`	Invalid Reference Number	The reference number does not match any transaction.	Verify the reference number and retry.
`SP009`	Transaction Not Found	No transaction exists for the given ID.	Confirm the `transaction_id` is correct.
`SP010`	Beneficiary Account Not Found	The destination bank account could not be found.	Verify the account number and bank code.
`SP011`	Beneficiary Vendor Not Active	The payment vendor/channel is currently unavailable.	Try an alternative channel or retry later.
`SP020`	Merchant Account Not Found	The specified merchant account does not exist.	Verify the `account_id` in the request.

Authentication & authorization errors

Code	Message	Description	Recommended action
`SP013`	Unauthorized	Invalid or expired access token.	Request a new token via Access Token v1.1.
`SP015`	Forbidden	The token is valid but lacks permission for this action.	Verify account permissions in the merchant dashboard.
`SP016`	Signature Invalid	The `X-Signature` header could not be verified.	Review Security and signature validation.
`SP017`	Unauthorized IP	The request originated from a non-whitelisted IP.	Add your server IP in the merchant dashboard, or contact support.

Request errors

Code	Message	Description	Recommended action
`SP012`	Bad Request	The request body is malformed or missing required fields.	Check the request against the endpoint schema.
`SP014`	Not Found	The requested resource or endpoint does not exist.	Verify the URL path and resource ID.
`SP018`	Validation Error	One or more fields failed validation.	Check the `data.errors` object for field-level details.
`SP019`	General Error	An unclassified server-side error occurred.	Contact Singapay support with the `transaction_id` and timestamp.

HTTP status code mapping

Singapay REST API endpoints also return standard HTTP status codes. Here is how they map to common scenarios:

HTTP Status	Meaning	Typical cause
`200`	OK	Request succeeded.
`400`	Bad Request	Malformed body, missing fields, or transaction failure (v2 endpoints).
`401`	Unauthorized	Invalid JWT, expired token, partner mismatch, or revoked credentials.
`403`	Forbidden	IP not whitelisted, account access denied, or merchant frozen.
`404`	Not Found	Resource (account, transaction, VA) does not exist.
`422`	Unprocessable Entity	Validation error — usually a missing `X-PARTNER-ID` header or invalid field values.
`500`	Internal Server Error	Unexpected server error. Retry or contact support.

v2 endpoints (Card, E-Wallet Native v2, Disbursement v2, QRIS Issuer) return both an HTTP status code and an SP response code in the body. Always check the response_code field for the definitive result.

Handling response codes

Check the response code

Parse response_code from the JSON body. SP000 means the request was accepted — proceed to check the transaction_status for the actual payment outcome.

Handle known errors

Match against the tables above. Errors like SP003 (insufficient balance) or SP004 (duplicate reference) have clear resolutions.

Handle known request errors

Match against the tables above. Errors like SP003 (insufficient balance) or SP004 (duplicate reference) have clear resolutions.

Don't confuse request success with payment success

SP000 confirms the server accepted your request. The payment may still be Initiated, Paying, or Pending. Always read the transaction_status object or wait for the webhook callback to determine the final payment outcome. See Transaction Status for the full lifecycle.

Use inquiry-status for uncertain outcomes

For SP001, SP002, and SP005, the transaction may still be in progress. Call the relevant inquiry-status endpoint before retrying.

Contact support for persistent errors

If SP007, SP017, or SP019 persists, contact Singapay support with the full request and response payloads.

Never retry a transaction blindly after a failure. Always call the inquiry-status endpoint first to confirm the final state. Retrying without checking can result in duplicate transfers.

Getting Started

Security

Accept Money

Send Money

Transaction Records

Money Accounts

Webhook

Response format

Response code dictionary

Success

Transaction request errors

Lookup errors

Authentication & authorization errors

Request errors

HTTP status code mapping

Handling response codes

​Response format

​Response code dictionary

​Success

​Transaction request errors

​Lookup errors

​Authentication & authorization errors

​Request errors

​HTTP status code mapping

​Handling response codes

Response format

Response code dictionary

Success

Transaction request errors

Lookup errors

Authentication & authorization errors

Request errors

HTTP status code mapping

Handling response codes