Guides

Sales Channel Integration Overview

A sales channel integration connects your payment experience — whether a physical terminal, point of sale system, or online checkout — to Centrapay's payment platform. Once integrated, your merchants can accept payment via any Centrapay-enabled app or asset.

How it Works

At a high level, every Centrapay payment follows the same pattern: a merchant integration creates a Payment Request , a patron pays it using their Centrapay app or asset, and the merchant integration receives confirmation.

    sequenceDiagram
  participant Patron
  participant Integration as Merchant Integration
  participant Centrapay

  Integration->>Centrapay: Create Payment Request
  Centrapay-->>Integration: Payment Request (status: new)
  Note over Integration,Patron: Connect with Patron (QR code or barcode)
  Patron->>Centrapay: Pay Payment Request
  loop Poll every second
    Integration->>Centrapay: Get Payment Request
    Centrapay-->>Integration: Payment Request (status: new)
  end
  Centrapay-->>Integration: Payment Request (status: paid)
  Note over Integration: Show confirmation ✅

Core Building Blocks

Concept	Description
Payment Request	Represents the merchant's intention to receive payment. You create one per transaction and poll it for status changes.
Merchant Config	Defines the set of payment methods available to a merchant. You reference a `merchantConfigId` when creating Payment Requests.
Asset Types	The payment instruments patrons can use (e.g. digital wallets, tokens, closed-loop cards). The Merchant Config controls which asset types are accepted.
API Key	Authenticates your integration against Centrapay APIs. The `merchant terminal` role is used for in-person integrations.

Integration Types

Choose the integration type that matches your channel:

Type	Best For
Payment Terminal	Hardware terminals managed by an integrator on behalf of multiple merchants. API calls are centralised in a backend.
Point of Sale	POS software integrated directly into a merchant's existing system. A single `merchant terminal` API key authenticates the POS.
E-commerce	Online checkouts using redirect or popup payment flows. Centrapay provides an SDK for in-page integration.

All three integration types share the same underlying payment protocol. The difference is in how you connect with the patron and how API keys are managed.

Connecting with Patrons

Centrapay supports two ways for a merchant integration to connect with a patron:

QR Code Flow — your integration creates a Payment Request and displays a QR code. The patron scans it using their app. Best when you have a customer-facing display.
Barcode Flow — the patron displays a barcode on their device and your integration scans it to create a Payment Request. Best when you have a barcode scanner but no customer-facing display.

We recommend implementing both flows to support the widest range of patron apps and assets.

Getting Started

Contact integrations@centrapay.com to be issued an Integrator Account and API key.
Centrapay will provide you with a merchantId and merchantConfigId to use when creating Payment Requests in the test environment.
Choose your integration type and follow the relevant guide to implement the core payment flow.
Review the protocol extensions and add any that your integration requires.
Once your integration is complete, Centrapay will provide a certification checklist before you go live.