Payments API

Initiate payins, retrieve transaction status, and model collection flows safely.

Introduction

Use the Payments API to collect funds from customers and track the transaction lifecycle through initiation, provider processing, and final resolution.

Initiate Payments

Create payins with amount, currency, payer phone number, and merchant metadata.

Track Status

Re-check the latest payment state with the returned track_id.

Reconcile Events

Combine status polling with webhook handling for strong operational visibility.

Required Headers

Authenticated Payment Request

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Endpoints

GET /api/v1/payments

POST /api/v1/payments

GET /api/v1/payments/status/{track_id}

Create a Payment

Endpoint

POST /api/v1/payments

Main Request Fields

Parameter	Type	Required	Description
`amount`	`number`	Yes	Payment amount
`currency`	`string`	Yes	ISO currency code
`payer_phone`	`string`	Yes	Customer mobile number with country code (e.g., `+237694010263`). Cameroon by default.
`operator_code`	`string`	No	Explicit operator code when not auto-detected
`external_id`	`string`	No	Merchant-side reference
`metadata`	`object`	No	Additional merchant metadata
`metadata.description`	`string`	No	Payment description shown in transaction logs
`metadata.customer_name`	`string`	No	Customer display name

Example Request

Create a Payment

curl -X POST "{{BASE_URL}}/api/v1/payments" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XAF",
    "payer_phone": "+237677001122",
    "external_id": "order_10001",
    "metadata": {
      "description": "Invoice INV-10001"
    }
  }'

If operator_code is not provided, the API may derive it from the phone number when possible.

Example Response

Payment Response

{
  "data": {
    "id": "01HR...",
    "company_id": "01HQ...",
    "application_id": "01HP...",
    "type": "PAYIN",
    "track_id": "TRX_01HR...",
    "amount": 1000,
    "currency": "XAF",
    "status": "PENDING",
    "operator_code": "MTN_CM",
    "provider_code": "PEEX",
    "payer_phone": "+237677001122",
    "metadata": {
      "description": "Invoice INV-10001"
    },
    "created_at": "2026-04-01T10:00:00Z",
    "completed_at": null
  }
}

Check Payment Status

Endpoint

GET /api/v1/payments/status/{track_id}

Fetch Payment Status

curl -X GET "{{BASE_URL}}/api/v1/payments/status/TRX_01HR..." \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE"

Status payloads usually include:

provider_reference

provider_status

updated_at

track_id

status

List Payments

Endpoint

GET /api/v1/payments

Use this endpoint for reconciliation, transaction history, support tooling, or operational reporting.

Common Statuses

Status	Meaning
`PENDING`	Waiting for customer action or provider feedback
`PROCESSING`	The request is being handled by upstream systems
`SUCCESS`	The payment completed successfully
`FAILED`	The payment failed or was rejected

Production rule

Polling is useful for debugging and recovery, but webhook delivery should be your primary source of truth in production payment flows.

Notes

duplicate initiation attempts may surface as already-known transactions

KYC or limit checks can block payment creation

always correlate external_id, track_id, and your internal order identifier

Initiate Payments

Track Status

Reconcile Events

On this page