Errors - xPay

All S2S API errors follow a consistent format to help you handle issues programmatically.

Error Format

All API errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The customer_id provided is invalid",
    "param": "customer_id"
  }
}

error.code

string

A unique code representing the type of error that occurred. This code is used to identify specific issues and facilitate troubleshooting.

error.message

string

A detailed message explaining the error represented by the error code. This description provides additional context to help understand the cause of the error.

error.param

string

The specific parameter or field that caused the error, if applicable. This helps identify which part of your request needs to be corrected.

Common Error Codes

Code	HTTP Status	Description
`authentication_failed`	401	Invalid API credentials
`invalid_request`	400	Invalid request parameters
`resource_not_found`	404	Requested resource doesn’t exist
`rate_limit_exceeded`	429	Too many requests
`server_error`	500	Internal server error

Payment Error Codes

When a payment fails, xPay provides specific error codes to help identify the reason for the failure. Below is a comprehensive list of possible error codes and their meanings. These error codes are currently visible in the exported CSV from the transactions page of your dashboard. In the below table,
[U] : Signifies that the failure reason was a user error
[X] : Signifies that the failure reason was not a user error but a processing error

Error Code	Description
`card_decline`	[X] The payment has been declined by the customer’s bank.
`expired_card`	[U] The card has expired.
`invalid_cvc`	[U] The CVC code is incorrect.
`invalid_address`	[U] The address information code is incorrect.
`insufficient_funds`	[U] The card has insufficient funds.
`incorrect_card_number`	[U] The card number is incorrect.
`threeDS_authentication_failure`	[U] 3D Secure authentication failed.
`timed_out`	[U] The payment process timed out.
`payment_method_decline`	[X] The payment method was declined.
`generic_decline`	[X] The payment was declined.
`issuer_decline`	[X] The payment was declined by the issuer.
`technical_issue`	[X] The transaction could not be processed due to an internal server issue.
`risk_check_failed`	[X] The payment method failed risk checks.
`setup_method_authorisation_failed`	[X] Failed to authorise test payment on the payment method.
`setup_method_indian_cards`	[X] Cards issued in India are not supported for authorisation.
`invalid_amount`	[X] The payment method doesn’t support this amount.
`card_rate_limit_exceeded`	[X] Card rate limit exceeded. Please try again later.
`fraudulent`	[X] The payment is suspected to be fraudulent.
`lost_card`	[X] The payment method has been reported lost/stolen.
`processing_error`	[X] The payment network encountered an error. Please try the payment again.
`transaction_not_allowed`	[X] This type of transaction is not allowed on this payment method.

HTTP Status Codes

xPay uses standard HTTP response codes to indicate the success or failure of an API request:

Code	Reason	Description
`200`	OK	The request was successfully received and processed.
`400`	Bad Request	There’s something wrong about the request. Potentially incorrect parameters, insufficient parameters, or an issue with authentication.
`401`	Unauthorized	You do not have access to the requested resource or your API credentials are incorrect.
`404`	Resource Not Found	You’re likely hitting the wrong endpoint or the resource does not exist.
`429`	Too Many Requests	You have exceeded the rate limit. Please slow down your request rate. See Rate Limits for more details.
`500`	Internal Server Error	Likely a server-side issue on xPay’s side.

S2S Integration

​Error Format

​Common Error Codes

​Payment Error Codes

​HTTP Status Codes

Error Format

Common Error Codes

Payment Error Codes

HTTP Status Codes