Centrapay’s payment protocol requires a merchant integration to connect with the patron in order to create a Payment Request; 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 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 for payment.
In order to create a Payment Request, 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.
Required Fields
We require compliant integrations to provide the following optional fields when creating a Payment Request.
| Name | Description |
|---|---|
externalRef | The merchant’s identifier for the transaction. Typically this is also printed on the paper receipt and required for Initiating Refunds. |
terminalId | The logical identifier of the terminal. Useful for auditing and debugging. |
deviceId | The hardware identifier of the terminal. Useful for auditing and debugging. |
patronNotPresent | This flag indicates whether a patron is physically present at the point of sale. Setting this flag can change the liability for some asset types. |
conditionsEnabled | The flag which indicates Payment Conditions are supported. |
partialAllowed | The flag which indicates Partial Payment is supported. |
basketAmount | The 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 every second until the status has changed.
Loading Diagram...
| Payment Request Status | Integrator Behavior |
|---|---|
| new | Check for Payment Conditions then poll again for status change. |
| paid | Show Confirmation. Stop polling. |
| expired | Show payment timed-out message. Stop polling. |
| cancelled | Show 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.