Follow this guide for error handling for both the Partner API and the payment service provider.

The following types of error handling must be implemented:

• Content errors
• Server errors
• Webhook errors (mandatory)

The Partner API expects the correct error response when there is an error in the request.

Content error handling

400 bad request

If the content sent to the payment service provider by the Partner API or vice versa does not adhere to the parameter requirements documented in the API reference, a validation error response should be returned.

This should be returned for any missing required parameters, incorrectly formatted data, or parameters that are not specified in the API reference documentation.

The Partner Library has been implemented to assist with validation and error responses. We highly recommend that payment service providers use this library when integrating with the Partner API.

📘

Note

The Partner Library is only available in Python.

{
    "result": {
        "code": "200.300.404",
        "parameterErrors": [
            {
                "value": "null",
                "name": "authenticationValue",
                "message": "Partner API requires authenticationValue"
            }
        ]
    },
    "resultDetails": {},
    "timestamp": "2021-04-23T07:41:25.519947Z"
}

401 unauthorized

This error should be sent to the payment service provider if the custom authentication requirements are not met. The Partner API can also send back this response if the JSON Web Token sent by the payment service provider during an inbound request is invalid.

The Partner API also returns this response if any of the API calls are not properly authenticated.

{
    "result": {
        "code": "800.100.152",
    },
    "timestamp": "2021-04-23T07:41:25.519947Z"
}

404 not found

Any resource requested that does not exist should return a 404 error response, including refund requests sent to a payment service provider that does not offer refunds.

Server error handling

Server errors are the result of a problem with the Partner API or a payment service provider. These errors should return relevant status in the 5XX range.

Webhook error handling: mandatory retry mechanism

When a payment service provider sends the Partner API a webhook for a transaction status update, if the webhook has been processed successfully by the Partner API, it responds back with a 200 OK HTTP status code. If not successfully processed, the Partner API responds with a non-200 HTTP status code.

If the Partner API sends an unsuccessful response to the payment service provider, the payment service provider is expected to retry sending the webhook to the Partner API until a successful response is received.

The payment service provider must implement an exponential backoff retry as follows:

• 1 minute
• 2 minutes
• 4 minutes
• 8 minutes
• 15 minutes
• 30 minutes
• 1 hour
• Every day until 7 days have passed since the first attempt