Error handling & response codes
PayLater returns conventional HTTP status codes and a JSON body describing what went wrong. Most errors carry an error (and sometimes a message) field.
{
"error": "Refund Error",
"message": "Transaction happened less than 10 minutes ago. Please try again later."
}
Authentication errors
| Example | Cause |
|---|
{ "error": "invalid_client", "error_description": "Invalid client or Invalid client credentials" } | Wrong client_id / client_secret. |
{ "error": "unsupported_grant_type", "error_description": "Unsupported grant_type" } | grant_type must be client_credentials. |
Common API errors
| Example | Cause |
|---|
{ "error": "Invalid API Key" } | Missing or invalid bearer token. |
{ "error": "Order ID must be unique" } | Reusing an order_id. |
{ "error": "Order ID is required" } | Required parameter omitted. |
{ "error": "Merchant ID cannot be null" } | Missing outlet/merchant context. |
{ "error": "Amount must be between 300 and 25000" } | amount outside the accepted range. |
{ "message": "Shopper not found" } | Lookup did not match a registered shopper. |
Request to Pay errors
| Reference | HTTP | Meaning |
|---|
RTP-409-DUPLICATE-REFERENCE | 409 | A Request-to-Pay already exists for this merchant order reference. |
RTP-UPSTREAM-ERROR | 404 | Unable to process Request-to-Pay right now. Please try again later. |
Refund errors
| Message | Meaning |
|---|
Transaction Reference is required | order_id omitted. |
Order cannot be refunded as it happened more than 29 days ago. | Outside the 29-day window. |
Order contains transactions other than down payment and cannot be refunded. | Not refundable. |
Transaction happened less than 10 minutes ago. Please try again later. | Must wait at least 10 minutes. |
Invalid Transaction Reference. | Unknown order. |
Invalid Transaction type. | Not a refundable transaction type. |
Payment status codes
| status | Meaning |
|---|
0 | Customer did not proceed |
1 | Pending |
2 | Success |
3 | Failed |
Webhooks over polling
Wherever possible, rely on signed webhooks for state changes instead of polling.