Getting Started

Welcome to AfriGate

AfriGate is a payment gateway that enables merchants to accept Mobile Money payments and perform transfers across Africa. Integrate once, reach 16 countries.

Collect Payments

Accept Mobile Money from your customers

Send Transfers

Disburse funds to recipients

Refunds

Refund full or partial payments

Webhooks

Real-time event notifications

Integration Journey

GET /v1/payment-methods Step 1 — first

Fetch the countries/operators available for your account (with real-time availability) and display them to your customer. Never hardcode this list. See Payment Methods.

POST /v1/payments Step 2

Create the payment with the operator + country chosen by the customer and the channel matching the operator's flow. See Payment Flows.

Webhook Step 3

Receive the final result (payment.completed) on your callbackUrl, then confirm via GET /v1/payments/{token}.

Payment Flow

Flow Diagram

Merchant                    AfriGate                    Mobile Money Operator
   |                           |                              |
   |-- POST /v1/payments ----->|                              |
   |<-- { token, status } ----|                              |
   |                           |-- Routing + USSD Push ------>|
   |                           |                              |
   |                           |<-- Callback result ----------|
   |<-- Webhook (callbackUrl) -|                              |
   |                           |                              |
   |-- GET /v1/payments/{token} ->|                           |
   |<-- { status: "success" } ---|                            |

Transfer Flow

Flow Diagram

Merchant                    AfriGate                    Mobile Money Operator
   |                           |                              |
   |-- POST /v1/transfers ---->|                              |
   |<-- { token, status } ----|                              |
   |                           |-- Routing + Send ----------->|
   |                           |                              |
   |                           |<-- Callback result ----------|
   |<-- Webhook (callbackUrl) -|                              |

Authentication

API Keys

Afrigate authentication is based on a key pair: a public key (pk_) and a private key (sk_, sometimes called the "secret"). Both are generated together from your merchant dashboard and must always be sent together in every request.

It's the same principle as the pairs used by other platforms:

Platform	Public key	Private key
Afrigate	`pk_live_...`	`sk_live_...`
AWS	`Access Key ID`	`Secret Access Key`
OAuth 2.0	`client_id`	`client_secret`
Stripe	`pk_live_...`	`sk_live_...`

	Public key (`pk_`)	Private key (`sk_`)
Role	Identifies your merchant account	Proves you are the account owner
Analogy	Username	Password
Sensitive?	No, can be known by third parties	Yes, strictly confidential
Storage	Back-end env variable (acceptable)	Secret manager only
Shown in dashboard?	At any time	Once, at generation

The public key (`pk_`)

What it's for: it's your identifier. When Afrigate receives a request, this value tells it "which merchant are we talking about?".
Format: pk_{env}_{24 random characters}, e.g. pk_live_mZWbtIV-ll-_0tNSSAxXV4fW.
Sensitivity: not sensitive on its own. Knowing only a merchant's public key allows no action — like knowing a username without the password.
Storage: can be stored in plaintext in your back-end code (env variable, config file). Still, don't put it in front-end / mobile code: not because of a compromise risk, but to avoid exposing it needlessly in logs or browser debug tools.

The private key (`sk_`)

What it's for: it's your password. It proves you own the corresponding public key.
Format: sk_{env}_{32 random characters}, e.g. sk_live_bleW2QUnMZ4Z9RPMuNLyAwGJ2egoP7JN.
Sensitivity: strictly confidential. Anyone who obtains the pk_ + sk_ pair can create payments and transfers on your behalf, move your funds, or view your transaction history.
Storage: server-side only, in a secret manager (AWS Secrets Manager, HashiCorp Vault, an uncommitted .env file, CI env variable). Never in front-end, mobile, or a public Git repo.
Retrieval: the private key is shown only once, at creation/rotation. Afrigate does not store it in plaintext (argon2 hash). If you lose it, you must generate a new one via the dashboard.

Combine both in a request

Concatenate the public key and the private key with a : in between, and place the result after Bearer in the Authorization header:

Header

Authorization: Bearer {publicKey}:{privateKey}

Full example:

Header

Authorization: Bearer pk_live_mZWbtIV-ll-_0tNSSAxXV4fW:sk_live_bleW2QUnMZ4Z9RPMuNLyAwGJ2egoP7JN

Pairs per environment

Each environment has its own pair — a sandbox key does not work in production and vice versa.

Environment	Public key	Private key	Usage
Production	`pk_live_...`	`sk_live_...`	Real transactions, real fund movement
Sandbox	`pk_test_...`	`sk_test_...`	Testing, no real fund movement, 50,000-unit sandbox balance included (in your country's currency)

If your private key leaks

Log into the dashboard.
Rotate the compromised key — the old private key is revoked immediately.
Update the new pair in your back-ends.
Review your transaction history over the suspicious window (illegitimate payments or transfers).

Permissions

Permission	Description
`payment:read`	View payments
`payment:write`	Create/cancel payments
`transfer:read`	View transfers
`transfer:write`	Create transfers

Per-key permissions are not yet enforced

These scopes describe the intended model, but the gateway does not currently enforce them. Today any valid API key pair has full access — read and write, payments and transfers. Fine-grained per-key restriction is planned but not yet active, so treat every key as fully privileged and protect the sk_ accordingly.

Injected Headers

After API key validation, the following headers are automatically added:

Header	Description
`X-Merchant-ID`	Your merchant identifier (UUID)
`X-Merchant-Code`	Your merchant code
`X-Key-Type`	`live` or `test`
`X-Request-ID`	Unique request identifier

Environments

Environment	Base URL
Production	`https://prod.afrigate.dev`
Sandbox	`https://sandbox.afrigate.dev`

Sandbox mode

Use the sandbox environment for testing. No real money is moved. Switch to production when you're ready to go live.

Payments

Payment Methods

Step 1 — required before any payment

Always call GET /v1/payment-methods to build the payment screen shown to your customer. Never hardcode the operator/country list: it depends on your enabled countries and on real-time maintenance. Showing an unavailable (or non-enabled) operator means a payment doomed to fail.

This endpoint returns a response specific to your merchant: only your enabled countries and their operators are returned, and each operator carries an isAvailable flag that accounts for ongoing maintenance (operator or gateway). It is the source of truth for showing your customer only what they can actually use. The countries table below is only an indicative overview — GET /v1/payment-methods is authoritative.

GET/v1/payment-methods

Authentication: public key only

Unlike payments/transfers (which require the pk:sk pair), this read-only endpoint authenticates with your public key alone — safe to call from a lightweight back-end.

Headers

Header	Required	Description
`Authorization`	Required	`Bearer {publicKey}` — your `pk_…` alone (no `:sk_`)
`Content-Type`	Optional	`application/json`

  cURL
 curl https://prod.afrigate.dev/v1/payment-methods \
  -H "Authorization: Bearer pk_live_mZWbtIV-ll-_0tNSSAxXV4fW"
 
 Response 200 OK
  JSON
 {
  "data": {
    "countries": [
      {
        "countryCode": "CI",
        "countryName": "Cote d'Ivoire",
        "flag": "https://d37zkt40qskmxk.cloudfront.net/flags/ci.svg",
        "currency": "XOF",
        "paymentMethods": [
          {
            "name": "Wave",
            "category": "mobile_money",
            "logo": "https://d37zkt40qskmxk.cloudfront.net/operators/wave.png",
            "isAvailable": true
          },
          {
            "name": "Orange Money",
            "category": "mobile_money",
            "logo": "https://d37zkt40qskmxk.cloudfront.net/operators/orange.png",
            "isAvailable": true
          },
          {
            "name": "MTN Mobile Money",
            "category": "mobile_money",
            "logo": "https://d37zkt40qskmxk.cloudfront.net/operators/mtn.png",
            "isAvailable": false
          }
        ]
      }
    ]
  }
}
 
 Fields
  Field Description
  countries[] One object per country enabled on your account
 countries[].countryCode ISO 3166-1 alpha-2 country code (uppercase)
 countries[].countryName Country name (may be null)
 countries[].flag Flag URL (may be null)
 countries[].currency ISO 4217 currency of the country (XOF, XAF, …)
 paymentMethods[].name Display name of the operator (e.g. Wave, Orange Money)
 paymentMethods[].category mobile_money, card or fintech_wallet
 paymentMethods[].logo Operator logo URL (may be null)
 paymentMethods[].isAvailable false if the operator (or the gateway serving it) is in active maintenance — hide/grey it out
 
 
  
 isAvailable: false is temporary (maintenance). Don't remove the operator from your UI, just grey it out. The display name is not the code to send in operator — see the operators table for the unified code (wave, orange, momo, …).

Field	Description
`countries[]`	One object per country enabled on your account
`countries[].countryCode`	ISO 3166-1 alpha-2 country code (uppercase)
`countries[].countryName`	Country name (may be `null`)
`countries[].flag`	Flag URL (may be `null`)
`countries[].currency`	ISO 4217 currency of the country (`XOF`, `XAF`, …)
`paymentMethods[].name`	Display name of the operator (e.g. `Wave`, `Orange Money`)
`paymentMethods[].category`	`mobile_money`, `card` or `fintech_wallet`
`paymentMethods[].logo`	Operator logo URL (may be `null`)
`paymentMethods[].isAvailable`	`false` if the operator (or the gateway serving it) is in active maintenance — hide/grey it out

Reference

Countries & Operators

AfriGate is connected in the countries below. For each payment/transfer you send country (ISO 3166-1 alpha-2) + operator (unified code) + currency (the country's currency); AfriGate routes automatically to the right PSP. The up-to-date list specific to your account (enabled countries + real-time availability) is always given by GET /v1/payment-methods.

Country	Code	Currency	Operators
Benin	`BJ`	XOF	Moov, MTN
Botswana	`BW`	BWP	Voucher
Cameroon	`CM`	XAF	MTN, Orange Money
Ivory Coast	`CI`	XOF	Orange Money, Wave, Moov, MTN
Gambia	`GM`	GMD	Wave, Afrimoney, Qmoney
Ghana	`GH`	GHS	MTN, Vodafone, AirtelTigo
Kenya	`KE`	KES	M-Pesa, Airtel
Liberia	`LR`	LRD	MTN, Orange Money, Lonestar
Nigeria	`NG`	NGN	Opay, Palmpay
Uganda	`UG`	UGX	MTN, Airtel
Senegal	`SN`	XOF	Orange Money, Wave, Free Money
Sierra Leone	`SL`	SLE	Afrimoney, Orange Money
Tanzania	`TZ`	TZS	Halopesa, M-Pesa, Tigo, Airtel

The currency sent must be the country's currency — e.g. BWP for Botswana, XOF for Senegal/Ivory Coast/Benin, XAF for Cameroon. The operator name above is the display name; the lowercase code for operator (wave, orange, momo, moov) is in the operators table. Zero-decimal currencies (XOF, XAF, GNF, BIF, RWF, KMF, DJF) take integer amounts only — fees and net amounts are also rounded to the whole unit; other currencies keep 2 decimals.

Per-operator specifics

How the customer authorizes the payment changes per operator. The channel field (and sometimes an extra field) drives this flow — detailed in Payment Flows. Main cases:

Operator / country	Flow	What YOU must do
Wave — SN, GM, CI, SL	Redirect	`channel: "REDIRECT"` → redirect the customer to `redirectUrl` (`https://pay.afrigate.dev/{token}`)
Orange Money — CI	OTP direct	Customer dials `#144*82#`, gives you the code → send it in `otp` with `channel: "OTP"`
Orange Money — SN	Redirect	`channel: "REDIRECT"` (enforced)
Botswana (Voucher)	Voucher	Customer buys a voucher and gives you its PIN → send it in `metadata.voucherPin`
Opay / Palmpay — NG	Redirect	`channel: "REDIRECT"` → redirect to `redirectUrl`
MTN (MoMo), Moov, M-Pesa, Tigo Pesa, Halopesa, Airtel	Push / STK	`channel: "PUSH"` (default) → customer approves the prompt with their PIN

 
    Payments 
 Payments (Collect)
 Initiate a fund collection from a customer's mobile money account to your merchant account.
 Create a Payment
  POST /v1/payments 
 Required Headers
  Header Required Description
  Authorization Required Bearer {keyId}:{secret} — see Authentication
 X-Idempotency-Key Required Unique UUID to prevent duplicates
 Content-Type Required application/json
 
 
 Request Body
   JSON  
 {
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "orange",
  "country": "CI",
  "customer": {
    "phone": "+2250700000000",
    "name": "Jean Kouassi",
    "email": "jean@example.com"
  },
  "successUrl": "https://mysite.com/payment/success",
  "failedUrl": "https://mysite.com/payment/failed",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "ORDER-12345",
  "feeBearer": "merchant",
  "channel": "PUSH",
  "designation": "Online purchase",
  "description": "Order #12345",
  "metadata": {
    "orderId": "12345",
    "customField": "value"
  }
}
 
 Fields
  amount number Required
Amount in the currency's minor unit (minimum 1). For zero-decimal currencies (XOF, XAF, GNF, BIF, RWF, KMF, DJF) the amount must be an integer (no decimals) — send 5000, not 5000.00. Other currencies (GHS, KES, NGN, BWP, TZS, UGX…) use 2 decimals.
 currency string Required
ISO 4217 currency code (e.g. XOF, XAF, GHS)
 paymentMethod string Required
Payment method (e.g. MOBILE_MONEY)
 operator string Required
Unified operator code. See operators table
 country string Required
ISO 3166-1 alpha-2 country code (e.g. CI, SN, GH)
 customer.phone string Required
Customer phone number. Validated per country (dialing code + exact length); international E.164 (+225…, recommended) or national format accepted. Must match the country. See Phone Number Format
 customer.name string Optional
Customer name
 customer.email string Optional
Customer email
 successUrl string Required
Redirect URL after successful payment
 failedUrl string Required
Redirect URL after failure
 callbackUrl string Required
Webhook receiving URL
 merchantTransactionId string Optional
Your internal reference
 feeBearer string Optional
Who pays fees: merchant (default) or customer
 channel string Optional
PUSH (default), OTP, USSD, QRCODE, REDIRECT, DIRECT. See Payment Flows
 otp string Optional
Authorization / OTP code the customer generates with their operator (e.g. Orange Money via USSD). Send it with channel: "OTP" to authorize the payment directly, without a redirect page (max 20 chars). See Payment Flows
 metadata object Optional
Additional data returned in webhooks. Also carries the voucher PIN for Botswana prepaid-voucher payments: metadata.voucherPin — see Payment Flows
 
 Response 201 Created
  JSON
 {
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": 5000,
    "currency": "XOF",
    "feeAmount": 150,
    "netAmount": 4850,
    "status": "initiated",
    "paymentMethod": "MOBILE_MONEY",
    "operator": "orange",
    "country": "CI",
    "redirectUrl": "https://pay.afrigate.dev/a1b2c3...",
    "expiresAt": "2024-01-15T15:30:00.000Z",
    "createdAt": "2024-01-15T15:00:00.000Z"
  }
}
 
  
  Redirect URL
 The redirectUrl field is only present with channel: REDIRECT (redirect operators — Wave, Orange Money SN, Opay, Palmpay). It always equals https://pay.afrigate.dev/{token} (AfriGate-hosted page). Always redirect the customer to this URL: the AfriGate page then forwards them to the operator's page automatically. For other channels (PUSH, OTP, …) this field is absent. See Payment Flows.
 
 
 Get a Payment
 GET/v1/payments/{token}
 Returns the same structure as the creation response.
 List Payments
 GET/v1/payments
  Parameter Type Description
  status string Filter by status
 from string Start date (ISO 8601)
 to string End date (ISO 8601)
 limit number Number of results (default: 20)
 offset number Offset for pagination
 
 
 Cancel a Payment
 POST/v1/payments/{token}/cancel
  JSON
 { "reason": "Customer changed their mind" }
 
  
 Only payments with initiated or pending status can be cancelled.
 
 
 
   Payment Lifecycle
  State Machine
 initiated --> pending --> processing --> success
                                    --> failed
                                    --> expired
         --> cancelled

success --> refunded             (full refund)
        --> partially_refunded   (partial refund)
 
  Status Description Terminal
  initiated Payment created, awaiting processing No
 pending Being routed to the operator No
 processing Operator is processing the transaction No
 success Payment successful Yes
 failed Payment failed Yes
 cancelled Cancelled by the merchant Yes
 expired Timeout exceeded (15 min for REDIRECT flows, 30 min for push/momo flows) Yes
 refunded Fully refunded Yes
 partially_refunded Partially refunded Yes
 
 
 
 
    Payments 
 Operators & Payment Flows
 How the customer authorizes a payment depends on the operator (operator) and country (country). The channel field drives this flow. There are four flows, and sending the wrong channel for an operator can silently fail the transaction at some PSPs.
  
 Golden rule: you never have to choose the PSP (Flutterwave, Wave, Payaza, 54pay…). You only send operator + country; AfriGate routes to the right connector. You only choose the channel per the flows below.
 
 Flow 1 — Redirect (Wave, Orange Money SN, Opay, Palmpay)
 The customer is redirected to a payment page where they authorize the debit with their operator.
  Send channel: "REDIRECT".
 The 201 response contains redirectUrl = https://pay.afrigate.dev/{token} (AfriGate-hosted page). Always redirect the customer to this URL; the AfriGate page then forwards them to the operator. You never handle the raw operator URL.
 Nothing to collect (no OTP), nothing pushed to the phone.
 The final result arrives via the webhook (payment.completed); you can also poll GET /v1/payments/{token}.
 
  Operator operator country Note
  Wave wave SN, CI, GM, SL REDIRECT enforced
 Orange Money Senegal orange SN REDIRECT enforced
 Opay opay NG REDIRECT enforced
 Palmpay palmpay NG REDIRECT enforced
 
 
  
 For all redirect operators, REDIRECT is the only supported and enforced channel. Any other channel is rejected with 400 (Operator '<x>' only supports channel REDIRECT).
 
  JSON — Wave Senegal
 POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "wave",
  "country": "SN",
  "channel": "REDIRECT",
  "customer": { "phone": "+221770000000", "name": "Awa Diop" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "ORDER-12345"
}
 
 Flow 2 — OTP direct (Orange Money CI)
 The customer generates a code with their operator, you collect it on your interface and send it in the otp field with channel: "OTP". The payment is authorized directly, with no redirect.
 Customer steps — Orange Money Ivory Coast:
  The customer dials on their phone: #144*82#.
 They receive a payment code (OTP) by SMS.
 They give you this code on your interface (payment page, app, POS…).
 You call POST /v1/payments with channel: "OTP" and otp: "<code>".
 
  otp field: string, 20 chars max.
 No redirectUrl is returned. The final result arrives via the webhook.
 
  JSON — Orange Money CI
 POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "orange",
  "country": "CI",
  "channel": "OTP",
  "otp": "123456",
  "customer": { "phone": "+2250700000000", "name": "Jean Kouassi" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate"
}
 
  
 If you can't collect the OTP (e.g. a no-interaction flow), Orange CI also accepts channel: "REDIRECT" as a fallback.
 
 Flow 3 — Push / STK (MTN MoMo, Moov, …)
 A validation prompt is pushed to the customer's phone; they approve it with their PIN. Nothing to redirect, nothing to collect.
  Send channel: "PUSH" (the default if channel is omitted).
 The final result arrives via the webhook.
 
  JSON — MTN Mobile Money CI
 POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "momo",
  "country": "CI",
  "channel": "PUSH",
  "customer": { "phone": "+2250500000000", "name": "Ama Kone" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate"
}
 
 Flow 4 — Voucher / prepaid (Botswana)
 The customer buys a voucher (prepaid token) from a point of sale or an app, gets a PIN, and gives it to you. You send this PIN in the metadata object (metadata.voucherPin). There is no redirect and no push: the PIN alone authorizes the debit.
  Botswana (country: "BW", currency BWP): PIN in metadata.voucherPin.
 The final result arrives via the webhook (payment.completed); you can also poll GET /v1/payments/{token}. No redirectUrl is returned.
 
  JSON — Botswana voucher
 POST /v1/payments
{
  "amount": 100,
  "currency": "BWP",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "voucher",
  "country": "BW",
  "customer": { "phone": "+26771000000", "name": "Kgomotso M." },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "metadata": { "voucherPin": "12345678" }
}
 
 Summary
  Operator operator country Flow channel The customer…
  Wave wave SN, CI, GM, SL Redirect REDIRECT (enforced in all countries) is redirected to redirectUrl
 Orange Money orange SN Redirect REDIRECT (enforced) is redirected to redirectUrl
 Opay opay NG Redirect REDIRECT (enforced) is redirected to redirectUrl
 Palmpay palmpay NG Redirect REDIRECT is redirected to redirectUrl
 Orange Money orange CI OTP direct OTP + otp field dials #144*82#, gives you the code
 MTN MoMo momo CI, … Push PUSH (default) approves the prompt with their PIN
 Moov moov CI, BJ Push PUSH (default) approves the prompt with their PIN
 Voucher voucher BW Voucher — (PIN via metadata.voucherPin) buys a voucher, gives you the PIN
 
 
  
 When in doubt, first query GET /v1/payment-methods to learn which operators are active/available, then apply the channel from the table above. The wrong channel can fail the payment without a clear message (except REDIRECT-only operators, which return an explicit 400).
 
 
 
    Disbursement 
 Transfers
 Send funds from your merchant account to a recipient's mobile money account.
 Create a Transfer
 POST/v1/transfers
  JSON
 {
  "amount": 10000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "momo",
  "country": "CI",
  "recipient": {
    "phone": "+2250700000000",
    "name": "Awa Traore",
    "email": "awa@example.com"
  },
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "TRANSFER-789",
  "designation": "Supplier payment",
  "metadata": { "invoiceId": "789" }
}
 
 Fields
  amount number Required
Amount (minimum 1). Zero-decimal currencies (XOF, XAF, GNF, BIF, RWF, KMF, DJF) must be an integer; other currencies use 2 decimals.
 currency string Required
ISO 4217 currency code
 operator string Required
Unified operator code. See operators table
 country string Required
ISO 3166-1 alpha-2 country code
 recipient.phone string Required
Recipient phone number. Validated per country (dialing code + exact length); E.164 (+225…) or national format accepted. Must match the country. See Phone Number Format
 recipient.name string Optional
Recipient name
 callbackUrl string Optional
Webhook URL
 metadata object Optional
Additional data
 
 Transfer Lifecycle
  Status Description Terminal
  initiated Transfer created No
 pending Being routed No
 processing Operator is processing No
 success Funds sent to recipient Yes
 failed Transfer failed Yes
 expired Timeout exceeded (10 min default) Yes
 
 
 
 
   Refunds
 Refund all or part of a successful payment.
 POST/v1/payments/{paymentToken}/refund
  JSON
 {
  "amount": 2500,
  "currency": "XOF",
  "refundType": "partial",
  "reason": "Product returned"
}
 
  amount number Required
Amount to refund
 currency string Required
Currency (must match the payment)
 refundType string Optional
full or partial (auto-detected if omitted)
 reason string Optional
Refund reason (max 500 characters)
 
  
  Refund rules
  Only success payments can be refunded
 Amount cannot exceed remaining refundable amount
 Full refund sets status to refunded
 Partial refund sets status to partially_refunded
 
 
 
 List Refunds
 GET/v1/payments/{paymentToken}/refunds
 
 
   Checkout Session
 The checkout is a payment page hosted by AfriGate. Use it to offer a turnkey payment experience.
 Get Session
 GET/v1/checkout/{token}
 Check Status
 GET/v1/checkout/{token}/status
  Status Description
  pending Waiting for customer action
 processing Payment in progress
 redirect Customer must be redirected (operatorRedirectUrl present)
 success Payment successful (successUrl present)
 failed Payment failed (failedUrl present)
 expired Session expired
 
 
 
 
    Integration 
 Webhooks
 Webhooks notify you in real-time of status changes on your transactions.
 Events
  Event Trigger
  payment.completed Payment reaches a terminal status (success, failed, cancelled, expired) or is refunded (refunded, partially_refunded)
 transfer.completed Transfer reaches a terminal status
 
 
  
 Refunds don't trigger a separate event: they reuse payment.completed with the payment's new status (refunded / partially_refunded).
 
 Payload Format
  JSON
 {
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": "5000",
    "currency": "XOF",
    "status": "success",
    "completedAt": "2024-01-15T15:05:00.000Z"
  },
  "timestamp": "2024-01-15T15:05:01.000Z"
}
 
 Refund Payload
 A refund does not emit its own event: it reuses payment.completed with the payment's new status — refunded (full) or partially_refunded (partial). The token is the payment's token (not the refund's), and the data object carries extra refund fields:
  JSON
 {
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "status": "partially_refunded",
    "refundId": "ref_a1b2c3d4",
    "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "2500",
    "currency": "XOF",
    "refundType": "partial"
  },
  "timestamp": "2024-01-15T16:00:00.000Z"
}
 
 Webhook Headers
  Header Description
  X-Webhook-Request-Id Unique delivery identifier (UUID)
 X-Webhook-Timestamp Timestamp in milliseconds (epoch)
 X-Webhook-Signature HMAC-SHA256 signature
 
 
 Signature Verification
  Node.js
 const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const content = `${timestamp}.${JSON.stringify(payload)}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(content)
    .digest('hex');

  const receivedSig = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

app.post('/webhooks/afrigate', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];

  // Verify timestamp is recent (< 5 minutes)
  const age = Date.now() - parseInt(timestamp);
  if (age > 5 * 60 * 1000) {
    return res.status(400).json({ error: 'Timestamp too old' });
  }

  if (!verifyWebhookSignature(req.body, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}, Status: ${data.status}`);

  res.status(200).json({ received: true });
});
 
  Python
 import hmac, hashlib, time, json

def verify_webhook(payload, signature, timestamp, secret):
    age = int(time.time() * 1000) - int(timestamp)
    if age > 5 * 60 * 1000:
        return False

    content = f"{timestamp}.{json.dumps(payload, separators=(',', ':'))}"
    expected = hmac.new(
        secret.encode(), content.encode(), hashlib.sha256
    ).hexdigest()

    received = signature.replace("sha256=", "")
    return hmac.compare_digest(expected, received)
 
 Retry Policy
 Each webhook is delivered with one initial POST plus up to 5 retries (6 attempts max). The request timeout per attempt is 10 seconds. Retries use exponential backoff (2, 4, 8, 16, 32 seconds):
  Attempt Delay before attempt Cumulative
  1 (initial) Immediate 0s
 2 (retry 1) 2s 2s
 3 (retry 2) 4s 6s
 4 (retry 3) 8s 14s
 5 (retry 4) 16s 30s
 6 (retry 5) 32s 62s
 
 
  
  Not every failure is retried
 Only transient failures are retried: 5xx responses, connection timeouts (status 0), and 408 / 425 / 429. Permanent 4xx responses (400, 401, 403, 404, 422) are not retried — the delivery is marked FAILED immediately. Return 2xx to acknowledge; return a 5xx only if you want AfriGate to retry.
 
 
  
  Best Practices
  Respond 200 OK immediately, process asynchronously
 Use X-Webhook-Request-Id to deduplicate
 Always verify the signature
 Reject webhooks older than 5 minutes
 Confirm status via GET /v1/payments/{token}
 
 
 
 
 
   Idempotency
 To prevent duplicate transactions, include a unique X-Idempotency-Key header.
  Header
 X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
 
  Scenario Behavior
  New key Transaction created normally
 Existing key Original response returned (no duplicate)
 Key TTL 24 hours
 
 
 Required for: POST /v1/payments and POST /v1/transfers
 
 
   Rate Limiting
 Requests are rate-limited per merchant over a fixed 60-second window. The limit differs per environment:
  Environment Limit Window
  Production 2,500 requests 60 seconds
 Sandbox 500 requests 60 seconds
 
 
 Response Headers
  Header Description
  X-RateLimit-Limit Max requests in the window (2500 in production, 500 in sandbox)
 X-RateLimit-Remaining Remaining requests in the current window
 X-RateLimit-Reset Unix timestamp at which the window resets — use this to back off
 
 
  
 There is no HTTP Retry-After header — use X-RateLimit-Reset to decide when to retry. In the 429 body, retry_after is the window length (60 seconds), not a live countdown.
 
 Exceeded 429
  JSON
 {
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": { "limit": 2500, "window": 60, "retry_after": 60 }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2024-01-15T15:00:00.000Z"
  }
}
 
 
 
    Integration 
 Sandbox Testing
 The sandbox environment (https://sandbox.afrigate.dev) accepts test phone numbers that simulate a successful or failed payment without touching the real mobile money operator. No real funds move, and no user action is required.
 Sandbox Starting Balance
 When your merchant account is created, your sandbox wallet is credited with 50,000 units in your country's currency (e.g. 50,000 XOF for an Ivory Coast merchant, 50,000 NGN for a Nigeria merchant) so you can test transfers (disbursements) immediately, without making a prior deposit. This simulated balance is decremented on each successful simulated transfer and has no impact in production.
 Test Numbers by Country
 To trigger a simulated result, use these numbers in customer.phone (payment) or recipient.phone (transfer), with the matching country.
  Country Code Success number Failed number
  Senegal SN +221700000001 +221700000002
 Ivory Coast CI +225700000001 +225700000002
 Benin BJ +229700000001 +229700000002
 Nigeria NG +234700000001 +234700000002
 Ghana GH +233700000001 +233700000002
 Botswana BW +267700000001 +267700000002
 Cameroon CM +237700000001 +237700000002
 Gambia GM +220700000001 +220700000002
 Kenya KE +254700000001 +254700000002
 Liberia LR +231700000001 +231700000002
 Sierra Leone SL +232700000001 +232700000002
 Tanzania TZ +255700000001 +255700000002
 Uganda UG +256700000001 +256700000002
 
 
 Ready-to-use Request (per country)
 For each country: a representative operator, the matching channel, the currency, and the success number for customer.phone. Swap in the failed number (…002) to simulate a failure. The operator can be any available for the country (see GET /v1/payment-methods).
  Country country currency operator (ex.) channel customer.phone (success)
  Senegal SN XOF wave REDIRECT +221700000001
 Ivory Coast CI XOF momo PUSH +225700000001
 Benin BJ XOF moov PUSH +229700000001
 Nigeria NG NGN opay REDIRECT +234700000001
 Ghana GH GHS momo PUSH +233700000001
 Botswana BW BWP voucher PUSH * +267700000001
 Cameroon CM XAF momo PUSH +237700000001
 Gambia GM GMD wave REDIRECT +220700000001
 Kenya KE KES mpesa PUSH +254700000001
 Liberia LR LRD momo PUSH +231700000001
 Sierra Leone SL SLE orange PUSH +232700000001
 Tanzania TZ TZS mpesa PUSH +255700000001
 Uganda UG UGX momo PUSH +256700000001
 
 
  
  In sandbox the simulator only looks at country + customer.phone: it returns success/failed after ~5s regardless of the operator. The channel must still be consistent (REDIRECT operators like wave SN / opay reject another channel with 400).
 * Botswana (voucher): in sandbox no PIN is required (the simulator ignores it). In production, send the PIN in metadata.voucherPin — see Payment Flows.
 
 
  
 The number and the country must match exactly. Any other number is treated as a real call to the sandbox operator.
 
 Example: Successful Payment
  cURL
 curl -X POST https://sandbox.afrigate.dev/v1/payments \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx:sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "paymentMethod": "MOBILE_MONEY",
    "operator": "wave",
    "country": "SN",
    "customer": {
      "phone": "+221700000001",
      "name": "Test Success"
    },
    "successUrl": "https://mysite.com/payment/success",
    "failedUrl": "https://mysite.com/payment/failed",
    "callbackUrl": "https://mysite.com/webhooks/afrigate",
    "merchantTransactionId": "TEST-SUCCESS-001"
  }'
 
 Returns 201 Created, identical to a real payment (status: "pending"). After about 5 seconds, your callbackUrl receives the webhook:
  JSON
 {
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": "5000",
    "currency": "XOF",
    "status": "success",
    "completedAt": "2026-05-03T15:00:05.000Z"
  },
  "timestamp": "2026-05-03T15:00:06.000Z"
}
 
 GET /v1/payments/{token} then returns status: "success".
 Example: Failed Payment
 Same parameters with the country's failed number (+221700000002 for SN). The webhook received after ~5s:
  JSON
 {
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "amount": "5000",
    "currency": "XOF",
    "status": "failed",
    "completedAt": "2026-05-03T15:00:05.000Z"
  },
  "timestamp": "2026-05-03T15:00:06.000Z"
}
 
 Transfers
 Same numbers for recipient.phone. The transfer.completed webhook arrives after ~5s with status: "success" or status: "failed".
 Refunds
 Refunds are synchronous and don't go through an operator: there is no test number and no delay. To test, create a successful payment (success number above), wait for status: "success", then call POST /v1/payments/{token}/refund. The payment moves immediately to refunded (full) or partially_refunded (partial), and a payment.completed webhook is emitted. This works identically for all countries.
 REDIRECT Channel
 With channel: "REDIRECT", the simulator does not generate a redirect URL. The checkout session moves directly from pending to success or failed after ~5s. A front-end polling GET /v1/checkout/{token} will receive:
  JSON
 {
  "token": "pay_xK9mN2pQ",
  "status": "success",
  "successUrl": "https://mysite.com/payment/success"
}
 
  
  Limitations
  Sandbox only. In production these numbers have no special effect.
 No user-side action. No SMS, no payment page. To test the real user experience (Wave, Orange OTP, etc.), use your sandbox PSP credentials with a different number.
 Fixed 5-second delay between init and webhook. Real operators range from a few seconds to several minutes.
 
 
 
 
 
    Reference 
 Error Codes
 Error Format
 AfriGate returns two different error shapes depending on where the error is raised. Check both when parsing errors.
 1. Gateway errors — auth, rate limit, timeout, service unavailable
 Raised by the gateway itself. error is an object with a stable machine code (uppercase), a message, and optional details, wrapped in the standard envelope:
  JSON
 {
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "details": {}
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2024-01-15T15:00:00.000Z"
  }
}
 
 2. Business errors — payments, transfers, refunds
 Raised by the transaction service and proxied through unchanged. This is the NestJS format — no success, no error object, no details, just an HTTP status and a plain-text message:
  JSON
 {
  "statusCode": 400,
  "message": "Merchant not active",
  "error": "Bad Request"
}
 
  
 A stable machine code is only reliable for gateway errors. Business errors carry only an HTTP status and a human-readable message (the two structured codes invalid_phone and blocked_number aside) — branch on the HTTP status, not on parsing the message string.
 
 Gateway Errors
 Uppercase machine codes returned in the error.code field of the gateway envelope above.
  Code HTTP Description
  MISSING_AUTH 401 Missing Authorization header
 INVALID_API_KEY 401 Invalid or expired API key
 IP_NOT_ALLOWED 403 Request IP not in the merchant's allow-list
 PERMISSION_DENIED 403 Key lacks the required permission (defined but not currently enforced)
 RATE_LIMIT_EXCEEDED 429 Rate limit exceeded
 GATEWAY_TIMEOUT 504 Upstream service did not respond in time
 SERVICE_UNAVAILABLE 503 Upstream service temporarily unavailable
 INTERNAL_SERVER_ERROR 500 Unexpected internal error
 
 
  
 The errors below are business errors (see format #2). With the exception of invalid_phone and blocked_number (structured codes), they carry no machine code — only an HTTP status and the exact message text shown below. Branch on the HTTP status; the message string is informational and may change.
 
 Payment Errors - POST /v1/payments
  HTTP Message / code Meaning
  400 Merchant not active Merchant account is not active
 400 blocked_number (structured code) The customer number (customer.phone) is blocked
 400 invalid_phone (structured code) customer.phone is not a valid number for the country (wrong dialing code or length) — see Phone Number Format
 400 Operator '<x>' only supports channel REDIRECT A non-REDIRECT channel was sent for a REDIRECT-only operator (Wave, Orange Money SN, Opay, Palmpay)
 404 Payment not found Payment token not found
 
 
 Cancel Errors - POST /v1/payments/{token}/cancel
  HTTP Message / code Meaning
  404 Payment not found Payment token not found
 400 Wrong merchant The payment doesn't belong to this merchant
 400 Cannot cancel The payment is in a terminal status (success, failed, cancelled, expired)
 
 
 Transfer Errors - POST /v1/transfers
  HTTP Message / code Meaning
  400 Not active Merchant account is not active
 400 blocked_number (structured code) The recipient number (recipient.phone) is blocked
 400 invalid_phone (structured code) recipient.phone is not a valid number for the country (wrong dialing code or length) — see Phone Number Format
 400 Exceeds single limit Amount exceeds the per-transaction limit
 400 Exceeds daily limit Daily cumulative limit exceeded
 400 Exceeds monthly limit Monthly cumulative limit exceeded
 400 Count limit reached Max number of daily transfers reached
 404 Not found Transfer token not found
 
 
 Refund Errors - POST /v1/payments/{token}/refund
  HTTP Message / code Meaning
  404 Payment not found Payment token not found
 400 Wrong merchant The payment doesn't belong to this merchant
 400 Cannot refund payment in status "<x>" Only success (or partially_refunded) payments can be refunded; <x> is the current status
 400 Max refundable: <n> <currency> Amount exceeds the remaining refundable amount (<n>)
 
 
 
 
   Operators by Country
 The operator field is required. Use the unified code (lowercase) for the target country and operator. The combination of operator + country determines the exact provider.
 Ivory Coast CI - XOF
  Code Operator Flow Channel
  wave Wave REDIRECT REDIRECT
 orange Orange Money OTP direct OTP (+ otp) — or REDIRECT
 momo MTN Mobile Money PUSH PUSH
 moov Moov Money REDIRECT REDIRECT (default)
 
 
 Senegal SN - XOF
  Code Operator Flow Channel
  orange Orange Money REDIRECT REDIRECT (enforced)
 wave Wave REDIRECT REDIRECT (enforced)
 free Free Money OTP OTP (+ otp)
 
 
 Nigeria NG - NGN
  Code Operator Flow Channel
  opay Opay REDIRECT REDIRECT (enforced)
 palmpay Palmpay REDIRECT REDIRECT
 
 
 Ghana GH - GHS
  Code Operator Flow Channel
  momo MTN Mobile Money OTP / USSD OTP / REDIRECT
 vodafone Vodafone Cash OTP / USSD OTP / REDIRECT
 airteltigo AirtelTigo OTP / USSD OTP / REDIRECT
 
 
 Botswana BW - BWP
  Code Operator Flow Channel
  voucher Voucher (prepaid) VOUCHER PIN in metadata.voucherPin
 
 
 Kenya KE - KES
  Code Operator Flow Channel
  mpesa (alias safaricom) M-Pesa (Safaricom) PUSH PUSH
 airtel Airtel Money PUSH PUSH
 
 
 Tanzania TZ - TZS
  Code Operator Flow Channel
  mpesa (alias vodacom) M-Pesa (Vodacom) PUSH PUSH
 tigo (alias tigopesa) Tigo Pesa PUSH PUSH
 halopesa (alias halotel) Halopesa PUSH PUSH
 airtel Airtel Money PUSH PUSH
 
 
 Uganda UG - UGX
  Code Operator Flow Channel
  momo (alias mtn) MTN Mobile Money PUSH PUSH
 airtel Airtel Money PUSH PUSH
 
 
  
 Other countries (Benin, Cameroon, Gambia, Liberia, Sierra Leone): see the countries table. Classic Mobile Money operators (MTN momo, Moov moov, Orange orange…) use the Push flow (channel: "PUSH", default); Wave uses Redirect (enforced). The up-to-date list for your account is given by GET /v1/payment-methods.
 
 Unified Code Legend
  Code Operator
  momo (alias mtn) MTN Mobile Money
 orange (alias om) Orange Money
 moov Moov Money
 wave Wave
 free Free Money (Tigo)
 vodafone Vodafone Cash (Ghana)
 airteltigo AirtelTigo (Ghana)
 mpesa (alias safaricom) M-Pesa (Kenya; Tanzania via Vodacom)
 airtel Airtel Money (Kenya, Uganda, Tanzania)
 tigo (alias tigopesa) Tigo Pesa (Tanzania)
 halopesa (alias halotel) Halopesa (Tanzania)
 opay Opay (Nigeria)
 palmpay Palmpay (Nigeria)
 voucher Voucher — prepaid (Botswana)
 
 
  
 The unified code is the same regardless of country. For example, orange means Orange Money in both Ivory Coast and Senegal. It's the operator + country combination that determines the exact operator.
 
 
 
   Payment Channels
  Channel Description
  PUSH Operator pushes a validation prompt to the customer who approves it on their phone (default)
 OTP Customer generates a code with their operator (USSD) and you send it in the otp field → the payment is authorized directly, no redirect page. See Payment Flows
 USSD Customer dials a USSD code manually
 QRCODE Payment via QR code scan
 REDIRECT The creation response contains redirectUrl = https://pay.afrigate.dev/{token}. Always redirect the customer to this AfriGate page; it then forwards them to the operator (Wave, Orange SN, Opay, Palmpay)
 DIRECT Direct debit (per operator agreements)
 
 
 
   Limits & Timeouts
 Expiration Timeouts
  Type Default
  Payment — REDIRECT flows 15 minutes
 Payment — push / momo flows 30 minutes
 Transfer 10 minutes
 
 
 Constraints
  Constraint Value
  Minimum amount 1 currency unit
 Currency length 3 characters
 Country length 2 characters
 Cancel/refund reason 500 characters max
 Idempotency TTL 24 hours
 Webhook attempts 6 max (1 initial + 5 retries)
 Webhook timestamp tolerance 5 minutes
 
 
 
 
    Reference 
 Phone Number Format
 customer.phone (payment) and recipient.phone (transfer) are validated per country on creation: the number must be a valid mobile number for the request's country (dialing code + exact length). You can send the international E.164 format (+225…, recommended) or the national format (01…) — either way the number must belong to the country (a +233 number sent with country: "CI" is rejected). Otherwise: 400 invalid_phone.
 The table below shows the dialing code and the number of national digits (the part after the dialing code) expected per country:
  Country Code Dialing code Digits (national) Example (E.164)
  Benin BJ +229 10 +2290195123456
 Botswana BW +267 8 +26771123456
 Cameroon CM +237 9 +237671234567
 Ivory Coast CI +225 10 +2250123456789
 Gambia GM +220 7 +2203012345
 Ghana GH +233 9 +233231234567
 Kenya KE +254 9 +254712123456
 Liberia LR +231 9 +231770123456
 Nigeria NG +234 10 +2348021234567
 Senegal SN +221 9 +221701234567
 Sierra Leone SL +232 8 +23225123456
 Tanzania TZ +255 9 +255621234567
 Uganda UG +256 9 +256712345678
 
 
  
 Validation relies on each country's official numbering rules (lengths and mobile prefixes) — a number that is too short/long or has the wrong dialing code is refused before any debit or routing, avoiding a silent failure on the operator side.

Status	Description
`pending`	Waiting for customer action
`processing`	Payment in progress
`redirect`	Customer must be redirected (`operatorRedirectUrl` present)
`success`	Payment successful (`successUrl` present)
`failed`	Payment failed (`failedUrl` present)
`expired`	Session expired

Channel	Description
`PUSH`	Operator pushes a validation prompt to the customer who approves it on their phone (default)
`OTP`	Customer generates a code with their operator (USSD) and you send it in the `otp` field → the payment is authorized directly, no redirect page. See Payment Flows
`USSD`	Customer dials a USSD code manually
`QRCODE`	Payment via QR code scan
`REDIRECT`	The creation response contains `redirectUrl` = `https://pay.afrigate.dev/{token}`. Always redirect the customer to this AfriGate page; it then forwards them to the operator (Wave, Orange SN, Opay, Palmpay)
`DIRECT`	Direct debit (per operator agreements)

Header	Required	Description
`Authorization`	Required	`Bearer {keyId}:{secret}` — see Authentication
`X-Idempotency-Key`	Required	Unique UUID to prevent duplicates
`Content-Type`	Required	`application/json`

Parameter	Type	Description
`status`	string	Filter by status
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`limit`	number	Number of results (default: 20)
`offset`	number	Offset for pagination

Status	Description	Terminal
`initiated`	Payment created, awaiting processing	No
`pending`	Being routed to the operator	No
`processing`	Operator is processing the transaction	No
`success`	Payment successful	Yes
`failed`	Payment failed	Yes
`cancelled`	Cancelled by the merchant	Yes
`expired`	Timeout exceeded (15 min for `REDIRECT` flows, 30 min for push/momo flows)	Yes
`refunded`	Fully refunded	Yes
`partially_refunded`	Partially refunded	Yes

Operator	`operator`	`country`	Note
Wave	`wave`	`SN`, `CI`, `GM`, `SL`	REDIRECT enforced
Orange Money Senegal	`orange`	`SN`	REDIRECT enforced
Opay	`opay`	`NG`	REDIRECT enforced
Palmpay	`palmpay`	`NG`	REDIRECT enforced

Status	Description	Terminal
`initiated`	Transfer created	No
`pending`	Being routed	No
`processing`	Operator is processing	No
`success`	Funds sent to recipient	Yes
`failed`	Transfer failed	Yes
`expired`	Timeout exceeded (10 min default)	Yes

Event	Trigger
`payment.completed`	Payment reaches a terminal status (`success`, `failed`, `cancelled`, `expired`) or is refunded (`refunded`, `partially_refunded`)
`transfer.completed`	Transfer reaches a terminal status

Header	Description
`X-Webhook-Request-Id`	Unique delivery identifier (UUID)
`X-Webhook-Timestamp`	Timestamp in milliseconds (epoch)
`X-Webhook-Signature`	HMAC-SHA256 signature

Attempt	Delay before attempt	Cumulative
1 (initial)	Immediate	0s
2 (retry 1)	2s	2s
3 (retry 2)	4s	6s
4 (retry 3)	8s	14s
5 (retry 4)	16s	30s
6 (retry 5)	32s	62s

Scenario	Behavior
New key	Transaction created normally
Existing key	Original response returned (no duplicate)
Key TTL	24 hours

Environment	Limit	Window
Production	2,500 requests	60 seconds
Sandbox	500 requests	60 seconds

Header	Description
`X-RateLimit-Limit`	Max requests in the window (2500 in production, 500 in sandbox)
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp at which the window resets — use this to back off

Country	Code	Success number	Failed number
Senegal	`SN`	`+221700000001`	`+221700000002`
Ivory Coast	`CI`	`+225700000001`	`+225700000002`
Benin	`BJ`	`+229700000001`	`+229700000002`
Nigeria	`NG`	`+234700000001`	`+234700000002`
Ghana	`GH`	`+233700000001`	`+233700000002`
Botswana	`BW`	`+267700000001`	`+267700000002`
Cameroon	`CM`	`+237700000001`	`+237700000002`
Gambia	`GM`	`+220700000001`	`+220700000002`
Kenya	`KE`	`+254700000001`	`+254700000002`
Liberia	`LR`	`+231700000001`	`+231700000002`
Sierra Leone	`SL`	`+232700000001`	`+232700000002`
Tanzania	`TZ`	`+255700000001`	`+255700000002`
Uganda	`UG`	`+256700000001`	`+256700000002`

Country	`country`	`currency`	`operator` (ex.)	`channel`	`customer.phone` (success)
Senegal	`SN`	`XOF`	`wave`	`REDIRECT`	`+221700000001`
Ivory Coast	`CI`	`XOF`	`momo`	`PUSH`	`+225700000001`
Benin	`BJ`	`XOF`	`moov`	`PUSH`	`+229700000001`
Nigeria	`NG`	`NGN`	`opay`	`REDIRECT`	`+234700000001`
Ghana	`GH`	`GHS`	`momo`	`PUSH`	`+233700000001`
Botswana	`BW`	`BWP`	`voucher`	`PUSH` *	`+267700000001`
Cameroon	`CM`	`XAF`	`momo`	`PUSH`	`+237700000001`
Gambia	`GM`	`GMD`	`wave`	`REDIRECT`	`+220700000001`
Kenya	`KE`	`KES`	`mpesa`	`PUSH`	`+254700000001`
Liberia	`LR`	`LRD`	`momo`	`PUSH`	`+231700000001`
Sierra Leone	`SL`	`SLE`	`orange`	`PUSH`	`+232700000001`
Tanzania	`TZ`	`TZS`	`mpesa`	`PUSH`	`+255700000001`
Uganda	`UG`	`UGX`	`momo`	`PUSH`	`+256700000001`

Code	HTTP	Description
`MISSING_AUTH`	401	Missing Authorization header
`INVALID_API_KEY`	401	Invalid or expired API key
`IP_NOT_ALLOWED`	403	Request IP not in the merchant's allow-list
`PERMISSION_DENIED`	403	Key lacks the required permission (defined but not currently enforced)
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`GATEWAY_TIMEOUT`	504	Upstream service did not respond in time
`SERVICE_UNAVAILABLE`	503	Upstream service temporarily unavailable
`INTERNAL_SERVER_ERROR`	500	Unexpected internal error

HTTP	Message / code	Meaning
400	`Merchant not active`	Merchant account is not active
400	`blocked_number` (structured code)	The customer number (`customer.phone`) is blocked
400	`invalid_phone` (structured code)	`customer.phone` is not a valid number for the `country` (wrong dialing code or length) — see Phone Number Format
400	`Operator '<x>' only supports channel REDIRECT`	A non-`REDIRECT` channel was sent for a REDIRECT-only operator (Wave, Orange Money SN, Opay, Palmpay)
404	`Payment not found`	Payment token not found

HTTP	Message / code	Meaning
404	`Payment not found`	Payment token not found
400	`Wrong merchant`	The payment doesn't belong to this merchant
400	`Cannot cancel`	The payment is in a terminal status (`success`, `failed`, `cancelled`, `expired`)

HTTP	Message / code	Meaning
400	`Not active`	Merchant account is not active
400	`blocked_number` (structured code)	The recipient number (`recipient.phone`) is blocked
400	`invalid_phone` (structured code)	`recipient.phone` is not a valid number for the `country` (wrong dialing code or length) — see Phone Number Format
400	`Exceeds single limit`	Amount exceeds the per-transaction limit
400	`Exceeds daily limit`	Daily cumulative limit exceeded
400	`Exceeds monthly limit`	Monthly cumulative limit exceeded
400	`Count limit reached`	Max number of daily transfers reached
404	`Not found`	Transfer token not found

Code	Operator	Flow	Channel
`orange`	Orange Money	REDIRECT	`REDIRECT` (enforced)
`wave`	Wave	REDIRECT	`REDIRECT` (enforced)
`free`	Free Money	OTP	`OTP` (+ `otp`)

Code	Operator	Flow	Channel
`momo`	MTN Mobile Money	OTP / USSD	`OTP` / `REDIRECT`
`vodafone`	Vodafone Cash	OTP / USSD	`OTP` / `REDIRECT`
`airteltigo`	AirtelTigo	OTP / USSD	`OTP` / `REDIRECT`

Code	Operator	Flow	Channel
`mpesa` (alias `safaricom`)	M-Pesa (Safaricom)	PUSH	`PUSH`
`airtel`	Airtel Money	PUSH	`PUSH`

Welcome to AfriGate

Collect Payments

Send Transfers

Refunds

Webhooks

Integration Journey

Payment Flow

Transfer Flow

Authentication

API Keys

The public key (pk_)

The private key (sk_)

Combine both in a request

Pairs per environment

Permissions

Injected Headers

Environments

Payment Methods

Headers

Response 200 OK

Fields

Countries & Operators

Per-operator specifics

Payments (Collect)

Create a Payment

Required Headers

Request Body

Fields

Response 201 Created

Get a Payment

List Payments

Cancel a Payment

Payment Lifecycle

Operators & Payment Flows

Flow 1 — Redirect (Wave, Orange Money SN, Opay, Palmpay)

Flow 2 — OTP direct (Orange Money CI)

Flow 3 — Push / STK (MTN MoMo, Moov, …)

Flow 4 — Voucher / prepaid (Botswana)

Summary

Transfers

Create a Transfer

Fields

Transfer Lifecycle

Refunds

List Refunds

Checkout Session

Get Session

Check Status

Webhooks

Events

Payload Format

Refund Payload

Webhook Headers

Signature Verification

Retry Policy

Idempotency

Rate Limiting

Response Headers

Exceeded 429

Sandbox Testing

Sandbox Starting Balance

Test Numbers by Country

Ready-to-use Request (per country)

Example: Successful Payment

Example: Failed Payment

Transfers

Refunds

REDIRECT Channel

Error Codes

Error Format

1. Gateway errors — auth, rate limit, timeout, service unavailable

2. Business errors — payments, transfers, refunds

Gateway Errors

Payment Errors - POST /v1/payments

Cancel Errors - POST /v1/payments/{token}/cancel

Transfer Errors - POST /v1/transfers

Refund Errors - POST /v1/payments/{token}/refund

Operators by Country

Ivory Coast CI - XOF

Senegal SN - XOF

The public key (`pk_`)

The private key (`sk_`)

Ivory Coast `CI` - XOF

Senegal `SN` - XOF

Nigeria `NG` - NGN

Ghana `GH` - GHS

Botswana `BW` - BWP

Kenya `KE` - KES

Tanzania `TZ` - TZS

Uganda `UG` - UGX

Code	Operator	Flow	Channel
`mpesa` (alias `vodacom`)	M-Pesa (Vodacom)	PUSH	`PUSH`
`tigo` (alias `tigopesa`)	Tigo Pesa	PUSH	`PUSH`
`halopesa` (alias `halotel`)	Halopesa	PUSH	`PUSH`
`airtel`	Airtel Money	PUSH	`PUSH`

Code	Operator	Flow	Channel
`momo` (alias `mtn`)	MTN Mobile Money	PUSH	`PUSH`
`airtel`	Airtel Money	PUSH	`PUSH`

Code	Operator
`momo` (alias `mtn`)	MTN Mobile Money
`orange` (alias `om`)	Orange Money
`moov`	Moov Money
`wave`	Wave
`free`	Free Money (Tigo)
`vodafone`	Vodafone Cash (Ghana)
`airteltigo`	AirtelTigo (Ghana)
`mpesa` (alias `safaricom`)	M-Pesa (Kenya; Tanzania via Vodacom)
`airtel`	Airtel Money (Kenya, Uganda, Tanzania)
`tigo` (alias `tigopesa`)	Tigo Pesa (Tanzania)
`halopesa` (alias `halotel`)	Halopesa (Tanzania)
`opay`	Opay (Nigeria)
`palmpay`	Palmpay (Nigeria)
`voucher`	Voucher — prepaid (Botswana)

Type	Default
Payment — `REDIRECT` flows	15 minutes
Payment — push / momo flows	30 minutes
Transfer	10 minutes

Constraint	Value
Minimum amount	1 currency unit
Currency length	3 characters
Country length	2 characters
Cancel/refund reason	500 characters max
Idempotency TTL	24 hours
Webhook attempts	6 max (1 initial + 5 retries)
Webhook timestamp tolerance	5 minutes

Country	Code	Dialing code	Digits (national)	Example (E.164)
Benin	`BJ`	+229	10	`+2290195123456`
Botswana	`BW`	+267	8	`+26771123456`
Cameroon	`CM`	+237	9	`+237671234567`
Ivory Coast	`CI`	+225	10	`+2250123456789`
Gambia	`GM`	+220	7	`+2203012345`
Ghana	`GH`	+233	9	`+233231234567`
Kenya	`KE`	+254	9	`+254712123456`
Liberia	`LR`	+231	9	`+231770123456`
Nigeria	`NG`	+234	10	`+2348021234567`
Senegal	`SN`	+221	9	`+221701234567`
Sierra Leone	`SL`	+232	8	`+23225123456`
Tanzania	`TZ`	+255	9	`+255621234567`
Uganda	`UG`	+256	9	`+256712345678`