Link Search Menu Expand Document

Integrating Merchant Terminals

Integrating a merchant terminal with Centrapay APIs requires creating, cancelling, voiding and refunding Payment Requests on behalf of Merchants using a “merchant terminal” API key.


API Keys

To create API keys, you first need to get in touch with Centrapay to be issued an Integrator Account and an “account owner” API key. An “account owner” is a special kind of role that allows you to manage your account.

You can use this key to Create an API Key with the “merchant terminal” role. A “merchant terminal” key has a role that can create, cancel, void and refund Payment Requests on behalf of merchants.

Warning: You are responsible for the safety of your API keys

Merchant Configs

Centrapay Merchant Configs represent an available set of configured payment methods that can be utilized by one or more payment terminals by a Merchant.

Merchants and merchant configs are managed by Centrapay. The only details you need to be able to create payment requests on their behalf are the merchantId and merchantConfigId (aka clientId). Centrapay will send you these details through whatever channel works for you. Please get in touch to let us know.

In the future Centrapay will allow an integrator to on-board their own merchants through APIs using integrator API keys.

Example Flows

See Payment Flows for an overview of the API calls required for different payment flows.

Terminal Interface Guidelines

When configuring a terminal with Centrapay there are a few common touch points that require branded assets. Please use the Centrapay Brand Assets when building the UI for these screens.

Displaying a Button

Touch displays should show a button that loads the QR Code screen when pressed.

Displaying an Icon

Displays that don’t support touch should show an icon above the button used to load the QR Code screen.

Displaying QR Codes

Centrapay QR codes should be displayed with a Centrapay logo in the centre.

Integration Architecture

We strongly recommend Centrapay APIs are invoked from your backend and not directly from your payment terminals. Centralizing the invocation of our APIs from your backend offers the following benefits:

  1. Merchant network administrators will not need to make additional firewall changes.
  2. Your Centrapay API Keys can be managed centrally inside your secured network.
  3. TLS negotiation with Centrapay APIs can be managed independently of terminal hardware and software updates.

Mitigating Network Issues

The following mitigations will be helpful to deal with inconsistencies in Payment Request statuses due to network issues and race conditions:

Respect Payment Request 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 terminal should respond accordingly; either show transaction as paid or initiate a void instead.

Timeout Offset

Payment Requests have a configurable timeout which defaults to 2 minutes. Payment integrators should make sure that the payment terminal times out 5-10 seconds after the payment request. For example, if the payment terminal has a 90 second payment timeout then the Payment Request could be created with an 85 second timeout to prevent the payment terminal expiring at the same time as the payment request is paid.

Retry Before Giving Up

When faced with an unknown error while checking the status of a payment request, terminal integrations should retry at least once before voiding the transaction.

Void When Status Unknown

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. See Void Payment Request.

Polling vs Webhooks

Integrators can optionally take advantage of Payment Request Webhooks to help improve responsiveness to Payment Request status changes. However, integrators must not rely solely on webhooks and must fall back to polling the Get Payment Request endpoint to reliably detect when a Payment Request is paid.