Requesting Payment

Centrapay’s payment protocol requires a merchant integration to connect with the patron in order to create a Payment Request  API ; and poll it for payment confirmation.

Additionally, merchant integrations can opt into protocol extensions when creating a Payment Request in order to unlock acceptance of a wider set of payment options.

Connecting With Patrons

The Payment Request  API  object is a core part of Centrapay’s payment protocol. It represents the intention of a merchant to receive payment, defines the amount to be paid, and the acceptable Asset Types  API  for payment.

In order to create a Payment Request  API , a merchant integration must connect with the patron. Centrapay supports two different options to connect with patrons. We recommend that merchant integrations implement both options to support the complete set of apps within Centrapay’s ecosystem.

  1. QR Code Flow for Merchants
  2. Barcode Flow for Merchants

Required Fields

We require compliant integrations to provide the following optional fields when creating a Payment Request.

externalRefThe merchant’s identifier for the transaction. Typically this is also printed on the paper receipt and required for Initiating Refunds.
terminalIdThe logical identifier of the terminal. Useful for auditing and debugging.
deviceIdThe hardware identifier of the terminal. Useful for auditing and debugging.
patronNotPresentThis flag indicates whether a patron is physically present at the point of sale. Setting this flag can change the liability for some asset types.
conditionsEnabledThe flag which indicates Payment Conditions are supported.
partialAllowedThe flag which indicates Partial Payment is supported.
basketAmountThe total amount of the transaction including non Centrapay payment methods.

Short Codes

Payment Requests have a short code that is human- and OCR-friendly. Short codes are recycled every two years. When combined with the date or merchant id, short codes can unambiguously identify the correct Payment Request.

A short code can be displayed to a user instead of the Payment Request ID; e.g. on paper printouts.

Short codes can be used for Initiating Refunds.

Polling for Payment Confirmation

After connecting with the patron, the POS must poll the Payment Request status  API  every second until the status has changed.

Loading Diagram...

Payment Request StatusIntegrator Behavior
newCheck for Payment Conditions then poll again for status change.
paidShow Confirmation. Stop polling.
expiredShow payment timed-out message. Stop polling.
cancelledShow cancellation reason. Stop polling.

Protocol Extensions

Our payment protocol supports several optional extensions. Please review the extensions below and determine which ones you need for your integration.

Handling Payment Errors

Merchant integrations should follow our guidelines in Merchant Integration Error Handling when inconsistencies such as network issues or race conditions occur.