Error Codes
PaynPlus uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx range indicate an error with PaynPlus's servers.
Error Response Format
All API errors return a standard JSON object containing an error code and a human-readable message.
{
"error": {
"type": "invalid_request_error",
"code": "INSUFFICIENT_FUNDS",
"message": "The customer's e-wallet does not have enough balance to complete this transaction.",
"param": "amount"
}
}
"error": {
"type": "invalid_request_error",
"code": "INSUFFICIENT_FUNDS",
"message": "The customer's e-wallet does not have enough balance to complete this transaction.",
"param": "amount"
}
}
HTTP Status Codes
200
OK
Everything worked as expected.
400
Bad Request
The request was unacceptable, often due to missing a required parameter.
401
Unauthorized
No valid API key provided.
500
Server Error
Something went wrong on PaynPlus's end. (These are rare.)
Specific Error Codes
Below is a list of common code values returned within the error object.
| Error Code | Description & Resolution |
|---|---|
| INVALID_API_KEY | You used an invalid API key. Ensure you are not mixing Test and Live keys, and check for whitespace. |
| IP_NOT_WHITELISTED | The request originated from an IP address not allowed in your Merchant Dashboard settings. |
| INSUFFICIENT_FUNDS | The customer's GCash, Maya, or Card does not have enough balance to cover the transaction amount. Prompt the user to use a different payment method. |
| EXPIRED_SESSION | The Checkout session or QR code has expired (default is 24 hours). You need to create a new Payment Intent. |
| USER_CANCELLED | The customer explicitly cancelled the payment on the e-wallet authorization page. |