Error Handling

Below are our guidelines for dealing with inconsistencies in Payment Request statuses due to network issues, race conditions, or asset specific behaviours.

Respect Payment Status

Use the Payment Request status as the source of truth when determining if a Payment Request is paid or expired. For example, if cancelling a Payment Request fails with a REQUEST_PAID error then the terminal should respond accordingly; either by showing the transaction as paid or initiating a void instead.

Void Unknown Status

If the status of a transaction cannot be determined to be successful after retrying, then the Payment Request should be voided. Voiding a Payment Request will cancel the request and trigger any refunds if necessary.

Display Error Reasons

Centrapay has a limited set of error messages to simplify integration for our third-party partners. Due to this, the same error message can be returned for different reasons. Centrapay provides additional details in the reason field to enhance error messages and assist with debugging. Integrators may choose to display the reason to provide more information to the user, however, it is recommended thatreason is not used to drive application logic.

{
  "statusCode": 403,
  "message": "ERROR_MESSAGE",
  "error": "Forbidden",
  "reason": "A more detailed description of the reason for the error"
}

Configure POS Timeout

Payment Requests have a configurable timeout which defaults to 2 minutes. Integrators should make sure that the payment terminal times out 5-10 seconds after the Payment Request.

For example, if the Point of Sale (POS) has a 90-second payment timeout then the Payment Request could be created with an 85-second timeout to prevent the payment terminal from expiring at the same time as the Payment Request is paid.

Retry Unknown Errors

When faced with an unknown error while checking the status of a Payment Request, POS integrations should retry at least once before voiding the transaction.

Resolving Persistent Errors

For issues that cannot be resolved, please reach out to Centrapay Support at integrations@centrapay.com .