Local rails — server-to-server

Enable local rails for the currencies you want to accept in your Axra dashboard before calling this endpoint.

Create a collection

POST /business/collections Create a collection and return deposit instructions for the customer. Amounts are in major local currency units (for example, 10000 NGN). customer.name and customer.email are optional. Both are stored on the collection record for your own reconciliation and shown in your Axra dashboard; they are not forwarded to the underlying payment provider. customer.phone is required for mobile money — it is forwarded to the provider so the deposit prompt reaches the right number. customer.networkId is optional but strongly recommended on mobile money. It names the payer’s operator — MTN, Orange, Wave — and comes from networks[] on GET /business/local-rails/channels. On a corridor with more than one operator the payer is on exactly one of them, and a collection sent to the wrong one fails. If you omit networkId we infer the operator from customer.phone, which is correct for the overwhelming majority of numbers but cannot detect a ported number — one that has moved between operators and kept its original prefix. If your checkout already asks the payer which wallet they use, send it and we will use your answer instead of guessing. If you send a networkId that isn’t currently routable for the corridor we reject the collection with a 400 and the code NETWORK_NOT_ROUTABLE, rather than quietly routing the payer to a different operator. An explicit networkId is treated as a fact about the payer, not as a hint.

Reading `channel` on the response

Every collection response carries a channel object with two ids that are not interchangeable:

channel.networkId — the operator network we routed this collection to. This is the value customer.networkId echoes back, and the one to quote when asking us about routing.
channel.channelId — the underlying provider’s own internal channel id. It is null whenever the provider gave us none, which is common on bank and hosted-page collections. Treat it as opaque: it is not an operator, and it is never a substitute for networkId.

Bank transfer (NGN)

curl -X POST https://api.useaxra.com/api/v1/business/collections \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ngn",
    "country": "NG",
    "customer": {
      "name": "Adaobi Okeke",
      "email": "adaobi@example.com"
    },
    "channel": { "rail": "bank" }
  }'

Response

{
  "id": "lcoll_01HVXYZ123456",
  "object": "collection",
  "status": "pending",
  "amount": 10000,
  "currency": "ngn",
  "country": "NG",
  "expiresAt": "2026-05-11T12:34:56Z",
  "channel": {
    "rail": "bank",
    "provider": "PAGA",
    "channelId": null,
    "networkId": "9f3c81d2-4a6e-4b0f-9d17-2c5e8a71b430"
  },
  "instructions": {
    "kind": "bank_transfer",
    "bankName": "Indulge MFB",
    "accountNumber": "9906154084",
    "accountName": "AXRA / Your Business",
    "reference": null
  },
  "metadata": null,
  "businessPaymentId": "bp_01HVXYZ123456",
  "createdAt": "2026-05-11T12:24:56Z"
}

Mobile money (KES — M-PESA)

customer.phone is required for MoMo collections. KE resolves to a single operator, so customer.networkId is unnecessary here. On a multi-operator corridor — Cameroon (MTN / Orange), for example — send it. See Choosing the right mobile-money operator.

curl -X POST https://api.useaxra.com/api/v1/business/collections \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "kes",
    "country": "KE",
    "customer": {
      "name": "James Kamau",
      "email": "james@example.com",
      "phone": "+254712345678"
    },
    "channel": { "rail": "momo" }
  }'

Response

{
  "id": "lcoll_01HVXYZ789012",
  "object": "collection",
  "status": "pending",
  "amount": 5000,
  "currency": "kes",
  "country": "KE",
  "expiresAt": "2026-05-11T12:44:56Z",
  "channel": {
    "rail": "momo",
    "provider": "M-PESA",
    "channelId": "a1f6b93c-70d4-4e28-8c5b-19e07f4ad662",
    "networkId": "2b7e4f11-8c3a-4d59-b0e6-71a9c2d35f84"
  },
  "instructions": {
    "kind": "momo_prompt",
    "phone": "+254712345678",
    "prompt": "Approve the payment prompt from your mobile money provider."
  },
  "metadata": null,
  "businessPaymentId": "bp_01HVXYZ789012",
  "createdAt": "2026-05-11T12:34:56Z"
}

Link-confirmed mobile money (XOF — Wave)

Do not assume rail: "momo" means kind: "momo_prompt". Some mobile-money providers confirm on a hosted page instead of an on-device push. In Côte d’Ivoire and Senegal, Wave returns kind: "hosted_page" on a momo rail, and the payment cannot complete unless you send the customer to instructions.url. Always branch on instructions.kind, never on channel.rail.

After paying, the customer is returned to the URL you set once in Settings → Payer return URL, or via PUT /v1/business/config (returnUrl). It must be https on your verified business website domain. If you leave it empty, customers see Axra’s payment confirmation page.

Per-request successUrl on collections is deprecated and ignored. Set the return URL on the business, not on each collection.

Response

{
  "id": "lcoll_01HVXYZ901234",
  "object": "collection",
  "status": "pending",
  "amount": 10000,
  "currency": "xof",
  "country": "CI",
  "expiresAt": "2026-05-11T13:34:56Z",
  "channel": {
    "rail": "momo",
    "provider": "Wave",
    "channelId": "c7d90e14-5b62-4af8-93c1-08e2d4f7ba36",
    "networkId": "4e28d5b7-9a13-4c60-8f2d-6b31ca07e945"
  },
  "instructions": {
    "kind": "hosted_page",
    "url": "https://pay.wave.com/...",
    "provider": "Wave"
  },
  "metadata": null,
  "businessPaymentId": "bp_01HVXYZ901234",
  "createdAt": "2026-05-11T12:34:56Z"
}

Handle both shapes with one branch:

switch (collection.instructions.kind) {
  case 'hosted_page':
    // Wave (XOF momo), Ozow (ZAR eft) — the customer MUST open this URL.
    // Do not branch on `provider` either: it names the operator the payer
    // pays (e.g. "Wave") — a display label, not a flow discriminator. Only
    // `kind` tells you whether there is a URL the customer must open.
    return redirect(collection.instructions.url);
  case 'momo_prompt':
    // M-PESA, MTN — the customer approves on their handset; nothing to open.
    return showAwaitingApproval(collection.instructions.prompt);
  case 'bank_transfer':
    return showBankDetails(collection.instructions);
}

Instant EFT (ZAR — Ozow)

For hosted-page rails, redirect the customer to instructions.url. After they pay, they return to your configured payer return URL (or Axra’s confirmation page if none is set). Per-request successUrl is deprecated and ignored.

curl -X POST https://api.useaxra.com/api/v1/business/collections \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "zar",
    "country": "ZA",
    "customer": {
      "name": "Thabo Mokoena",
      "email": "thabo@example.com"
    },
    "channel": { "rail": "eft" }
  }'

Response

{
  "id": "lcoll_01HVXYZ345678",
  "object": "collection",
  "status": "pending",
  "amount": 2500,
  "currency": "zar",
  "country": "ZA",
  "expiresAt": "2026-05-11T12:49:56Z",
  "channel": {
    "rail": "eft",
    "provider": "Ozow",
    "channelId": null,
    "networkId": "6a4b2c08-3f91-4d7e-85ac-b21e9d0f47c3"
  },
  "instructions": {
    "kind": "hosted_page",
    "url": "https://pay.ozow.com/...",
    "provider": "Ozow"
  },
  "metadata": null,
  "businessPaymentId": "bp_01HVXYZ345678",
  "createdAt": "2026-05-11T12:39:56Z"
}

Handle the completion webhook

Fulfill orders when Axra delivers collection.completed, not when you return deposit instructions to the customer.

Subscribe to collection.completed on your webhook endpoint (or include it in the endpoint event list).
Verify X-Axra-Signature against the raw request body using your webhook secret. See Webhooks.
Read data.object — the payload mirrors GET /business/collections/{id}.
Mark the order paid and release goods or services only after status is completed.

app.post('/webhooks/axra', (req, res) => {
  const signature = req.headers['x-axra-signature'];
  if (!verifyWebhookSignature(req.rawBody, signature, process.env.AXRA_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;
  if (event === 'collection.completed' && data.object.status === 'completed') {
    fulfillOrder(data.object.metadata?.orderId, data.object.id);
  }

  res.status(200).send('OK');
});

Channel discovery

List channels before creating a collection when your UI needs to show available rails dynamically, or to discover the per-channel minimum and maximum amounts.

curl "https://api.useaxra.com/api/v1/business/local-rails/channels?country=NG&currency=ngn&amount=10000" \
  -H "x-api-key: YOUR_API_KEY"

Each channel in the response includes min and max in the local currency’s major units. min: 0 means no lower bound; max: 0 means no upper bound. Filter or sort on these in your UI so customers don’t see rails their amount doesn’t qualify for.

{
  "channels": [
    { "rail": "bank", "provider": "Paystack", "providerHint": "PAYSTACK", "min": 100, "max": 0 },
    { "rail": "momo", "provider": "MTN Uganda", "providerHint": "MTN_UGANDA", "min": 15000, "max": 0 }
  ],
  "networks": [
    { "networkId": "6168c869-0243-4f32-807a-ddd55b131e3e", "name": "MTN", "rail": "momo" },
    { "networkId": "830042b7-61a3-483a-8a19-5052b77f1516", "name": "Orange", "rail": "momo" }
  ],
  "limits": { "minAmount": 100, "maxAmount": 0 }
}

Choosing the right mobile-money operator

networks[] lists the mobile-money operators available on the corridor. A channel is not an operator — a channel is how we route, an operator is the wallet the payer actually holds money in. Where networks[] returns more than one entry, the payer is on exactly one of them, and a collection sent to the wrong operator fails at the provider. Two ways to handle it:

Ask the payer (recommended). Show the operator names from networks[], and pass the chosen networkId as customer.networkId on create. This is the only approach that is correct for a ported number, where the phone prefix no longer indicates the operator.
Let us infer it. Omit customer.networkId and we derive the operator from customer.phone. Correct for the overwhelming majority of numbers, but blind to porting.

rail on a networks[] entry is optional and is omitted when the provider does not tell us which rail the network runs on. A missing rail does not mean the network is unusable — it means we will not guess. Until 2026-09-10 every entry was reported as momo, which advertised bank networks as mobile-money operators; treat an absent rail as “unknown”, not as “not mobile money”. Operator availability changes without notice — read networks[] per corridor rather than hard-coding IDs.

Mobile money on a multi-operator corridor (XAF — Cameroon)

Cameroon carries both MTN and Orange. Read networks[] from GET /business/local-rails/channels, let the payer pick, and pass the chosen networkId:

curl -X POST https://api.useaxra.com/api/v1/business/collections \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "xaf",
    "country": "CM",
    "customer": {
      "name": "Bruno Jonas",
      "phone": "+237672487542",
      "networkId": "6168c869-0243-4f32-807a-ddd55b131e3e"
    },
    "channel": { "rail": "momo" }
  }'

Omit networkId and we infer MTN from the 672 prefix. Send it and we use your value — which is the only way to be right when the payer has ported their number between operators.

Minimums and maximums

Local-rail channels have provider-side minimum (and sometimes maximum) amounts. If you call POST /business/collections with an amount that doesn’t fit any channel for the requested rail and country/currency, you get a 400 with the actual minimum surfaced:

{
  "success": false,
  "error": {
    "code": "Amount 5000 UGX does not fit any momo channel for UG (minimum is 15000 UGX). Call GET /v1/business/local-rails/channels?country=UG&currency=ugx&amount=5000 to see what's available.",
    "statusCode": 400
  }
}

These limits are set by our settlement partners per corridor and change without notice — always read them from /business/local-rails/channels rather than hard-coding values in your client.

Idempotency

Pass idempotencyKey on create to dedupe retries within one hour. A duplicate key returns the original collection instead of minting a second virtual account.

Polling

Webhooks are the source of truth. If you must poll, call GET /business/collections/{id} about every five seconds while status is pending or processing. Use GET /business/collections/{id}/refresh to force a provider resync before giving up.

Status reference

Status	Meaning
`pending`	Deposit instructions are active; waiting for customer payment.
`processing`	Inbound funds detected; settlement is in progress.
`completed`	Collection settled; merchant USDC wallet credited.
`failed`	Collection failed (amount mismatch, provider rejection, or other terminal error).
`expired`	Instructions expired before payment arrived.

Error codes

HTTP	Code	When
`400`	`CURRENCY_UNSUPPORTED`	Currency or country is not enabled for your business, or the requested currency is not yet live (for example GHS).
`400`	`CUSTOMER_PHONE_REQUIRED`	`channel.rail` is `momo` but `customer.phone` is missing.
`400`	—	Amount is below the channel minimum or above the maximum for the requested rail. The error message includes the actual min/max. Discover both upfront via `/business/local-rails/channels`.
`400`	—	The requested rail is not available for the given country/currency. The error message lists which rails ARE available.
`404`	—	Collection id does not exist for your business.

API Reference

Full endpoint documentation.

Payer return URL

Set the URL customers return to after paying. Collections successUrl is ignored.

Payments

Treasury

Webhooks

SDKs

Local rails — server-to-server

Create a collection

Reading `channel` on the response

Bank transfer (NGN)

Mobile money (KES — M-PESA)

Link-confirmed mobile money (XOF — Wave)

Instant EFT (ZAR — Ozow)

Handle the completion webhook

Channel discovery

Choosing the right mobile-money operator

Mobile money on a multi-operator corridor (XAF — Cameroon)

Minimums and maximums

Idempotency

Polling

Status reference

Error codes

API Reference

Payer return URL

​Create a collection

​Reading channel on the response

​Bank transfer (NGN)

​Mobile money (KES — M-PESA)

​Link-confirmed mobile money (XOF — Wave)

​Instant EFT (ZAR — Ozow)

​Handle the completion webhook

​Channel discovery

​Choosing the right mobile-money operator

​Mobile money on a multi-operator corridor (XAF — Cameroon)

​Minimums and maximums

​Idempotency

​Polling

​Status reference

​Error codes

API Reference

Payer return URL

Create a collection

Reading `channel` on the response

Bank transfer (NGN)

Mobile money (KES — M-PESA)

Link-confirmed mobile money (XOF — Wave)

Instant EFT (ZAR — Ozow)

Handle the completion webhook

Channel discovery

Choosing the right mobile-money operator

Mobile money on a multi-operator corridor (XAF — Cameroon)

Minimums and maximums

Idempotency

Polling

Status reference

Error codes