Quick API Reference

Authentication

Merchant-facing endpoints require API key authentication via the `X-API-KEY` header.

X-API-KEY: your_merchant_api_key
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Use a unique `Idempotency-Key` per payment request to avoid duplicate payment creation.

Merchant integration (API key)

For ePOS and server integrations, use your merchant API key in the X-API-KEY header. These four endpoints cover the core flows:

• Create payment — POST /api/v1/payments — Create a new payment and receive a payment id.
• Get QR code — GET /api/v1/payments/{id}/qr — Fetch a PNG QR image for the customer to scan.
• Get transaction status — GET /api/v1/payments/{id} — Poll status for a single payment.
• Get all transactions — GET /api/v1/payments — List all payments for the authenticated merchant (no path parameter; merchant is derived from the API key).

All four require X-API-KEY. Create payment also requires Idempotency-Key and a JSON body with userId, merchantId, amount, and currency.

Create payment

Create a new payment from your ePOS system.

{
  "userId": "7f53da67-0f6a-4d68-b19f-6b61f9c68b11",
  "merchantId": "f95d08bb-e1dc-45a8-8dfd-90b723f8f17d",
  "amount": 125.50,
  "currency": "GBP",
  "metadata": {
    "orderId": "POS-100245",
    "terminalId": "TILL-03"
  }
}

Response includes `id`, `status`, `externalId`, and timestamps required for later polling and reconciliation.

Get payment status

Fetch latest status for a created payment by internal payment id.

{
  "id": "f6e4c012-4f60-4cd2-bf2d-4cc88c2f88ae",
  "merchantId": "f95d08bb-e1dc-45a8-8dfd-90b723f8f17d",
  "amount": 125.50,
  "currency": "GBP",
  "status": "PENDING",
  "externalId": "pay_abc123"
}

Create / retrieve QR code

Returns a PNG image for the payment QR that can be displayed on your terminal screen or customer-facing device.

This endpoint returns `image/png` bytes and rejects invalid terminal states (for example failed, reversed, expired).

Get transactions

List all payments for the authenticated merchant. Send X-API-KEY; the merchant is derived from the key, so no merchantId in the path is required. Returns an array of payment objects.

Paginated transactions for the authenticated merchant (portal/dashboard; uses Bearer JWT rather than API key).

Refund APIs

Create a full or partial refund.

Retrieve all refunds linked to a payment for audit and support flows.