Guides

Requesting Payment

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.

    sequenceDiagram
	autonumber

	participant Patron
	participant POS
	participant Centrapay

	Patron->>POS: Connect with Patron
	loop Poll every second until status changes
		POS->>Centrapay: Get Payment Request Status
	end

	note over POS: ✅ Display Confirmation

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.