Payment Terminal

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.

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 required 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

See the guide on Merchant Integration Error Handling for information on preventing and handling network issues.