Merchant Integration Error Handling

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

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  API  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  API  will cancel the request and trigger any refunds if necessary.

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.

Retries should use the appropriate idempotency key where applicable.

Resolving Persistent Errors

For issues that cannot be resolved, please reach out to Centrapay Support at