Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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": "ch_01HVNG7BANK" },
  "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. 
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": "ch_01HVKE7MOMO" },
  "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"
}

​
Instant EFT (ZAR — Ozow)

For hosted-page rails, redirect the customer to instructions.url or pass successUrl when creating the collection. 
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" },
    "successUrl": "https://yourapp.com/orders/ord_123/success"
  }'
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": "ch_01HVZA7EFT" },
  "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.
  1. Subscribe to collection.completed on your webhook endpoint (or include it in the endpoint event list).
  2. Verify X-Axra-Signature against the raw request body using your webhook secret. See Webhooks.
  3. Read data.object — the payload mirrors GET /business/collections/{id}.
  4. 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. 
curl "https://api.useaxra.com/api/v1/business/local-rails/channels?country=NG&currency=ngn&amount=10000" \
  -H "x-api-key: YOUR_API_KEY"

​
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

StatusMeaning
pendingDeposit instructions are active; waiting for customer payment.
processingInbound funds detected; settlement is in progress.
completedCollection settled; merchant USDC wallet credited.
failedCollection failed (amount mismatch, provider rejection, or other terminal error).
expiredInstructions expired before payment arrived.

​
Error codes

HTTPCodeWhen
400currency_unsupportedCurrency or country is not enabled for your business, or the requested currency is not yet live (for example GHS).
400customer_phone_requiredchannel.rail is momo but customer.phone is missing.
400—No active local-rail channel matches the amount and rail selection.
404—Collection id does not exist for your business.

API Reference

Full endpoint documentation.