Local payout corridors

​

Overview

• Supported corridors table (below)
• Payout quote

​

Supported corridors

​

Recipient shapes per rail

• Saved recipient (3 calls): create a recipient with POST /v1/business/payouts/recipients, then reference it by recipientId on every payout. Best when you pay the same payee repeatedly. The create call is idempotent on the destination — sending the same rail and account details returns the existing recipient rather than a duplicate — so it is safe to call before every payout.
• Inline recipient (2 calls): pass a recipient (or destination) object directly on POST /v1/business/payouts — no pre-created recipient needed. Best at high destination cardinality, where a saved recipient per payout is address-book noise.

​

Get the network / bank list first

• bankCode for LOCAL_BANK
• networkId for LOCAL_MOMO

​

Local bank (LOCAL_BANK)

{
  "label": "Payroll — Jane Doe",
  "rail": "LOCAL_BANK",
  "details": {
    "country": "NG",
    "accountNumber": "0123456789",
    "accountName": "Jane Doe",
    "bankCode": "058",
    "bankName": "GTBank"
  }
}

​

Local mobile money (LOCAL_MOMO)

{
  "label": "Field agent — Payee",
  "rail": "LOCAL_MOMO",
  "details": {
    "country": "CM",
    "phoneNumber": "+237612345678",
    "accountName": "Payee Name",
    "networkId": "network_opaque_id",
    "networkName": "Network Name"
  }
}

​

Cross-currency quote → confirm flow

1. POST /v1/business/payouts/quote returns a signed quoteToken (valid for 60 seconds).
2. POST /v1/business/payouts confirms the payout by passing quoteToken back, along with exactly one of a saved recipientId, an inline recipient object, or an inline destination.

​

Quote and confirm (Node + Python)

import { Axra } from '@useaxra/node';

const axra = new Axra(process.env.AXRA_SECRET_KEY!);

// 1) Quote (locks FX + fee for 60s)
const quote = await axra.payouts.quote({
  rail: 'LOCAL_BANK',
  country: 'NG',
  currency: 'NGN',
  srcAmount: '100.00',
});

// 2) Confirm (references locked quote by token)
const payout = await axra.payouts.create({
  rail: 'LOCAL_BANK',
  quoteToken: quote.quoteToken,
  recipientId: 'rec_01H...',
  idempotencyKey: 'payout-ng-2026-06-02-0001',
});

console.log(payout.id, payout.status);

import os
from axra import Axra

client = Axra(os.environ["AXRA_SECRET_KEY"])

# 1) Quote (locks FX + fee for 60s)
quote = client.payouts.quote(
    rail="LOCAL_BANK",
    country="NG",
    currency="NGN",
    src_amount="100.00",
)

# 2) Confirm (references locked quote by token)
payout = client.payouts.create(
    rail="LOCAL_BANK",
    quote_token=quote.quote_token,
    recipient_id="rec_01H...",
    idempotency_key="payout-ng-2026-06-02-0001",
)

print(payout.id, payout.status)

​

Single-call payout with an inline recipient

const quote = await axra.payouts.quote({
  rail: 'LOCAL_BANK',
  country: 'NG',
  currency: 'NGN',
  srcAmount: '100.00',
});

const payout = await axra.payouts.create({
  rail: 'LOCAL_BANK',
  quoteToken: quote.quoteToken,
  recipient: {
    country: 'NG',
    accountNumber: '0123456789',
    accountName: 'Jane Doe',
    bankCode: '058',
    bankName: 'Example Bank',
  },
  idempotencyKey: 'payout-ng-2026-06-02-0001',
});

quote = client.payouts.quote(
    rail="LOCAL_BANK",
    country="NG",
    currency="NGN",
    src_amount="100.00",
)

payout = client.payouts.create(
    rail="LOCAL_BANK",
    quote_token=quote.quote_token,
    recipient={
        "country": "NG",
        "account_number": "0123456789",
        "account_name": "Jane Doe",
        "bank_code": "058",
        "bank_name": "Example Bank",
    },
    idempotency_key="payout-ng-2026-06-02-0001",
)

​

Quote-token error codes

• INVALID_QUOTE_TOKEN: Token is malformed or signature validation failed.
• QUOTE_EXPIRED: Token is older than the 60-second TTL.
• QUOTE_BUSINESS_MISMATCH: Token was issued for a different business workspace.
• INSUFFICIENT_PAYOUT_LIQUIDITY: Liquidity is temporarily unavailable to settle the corridor.
• TREASURY_FROZEN: Payouts are temporarily disabled for treasury safety checks.
• PAYOUT_CORRIDOR_NOT_ENABLED: Your business is not enabled for this corridor.

​

Recipient error codes

• RECIPIENT_REQUIRED: Neither recipientId nor an inline recipient / destination was provided.
• RECIPIENT_AMBIGUOUS: More than one of recipientId, recipient, destination was provided. Send exactly one.
• RECIPIENT_RAIL_MISMATCH: The inline recipient.rail does not match the payout rail.
• RECIPIENT_NOT_FOUND: No recipient with that recipientId in this business workspace, or its rail differs from the payout rail.
• QUOTE_RECIPIENT_COUNTRY_MISMATCH: The destination country does not match the country the quote was issued for.
• 403 Recipient failed sanctions screening: Returned on the dashboard (JWT) channel only, for a recipient that matched a sanctions/PEP list. x-api-key requests are not screened by Axra and never receive this.

​

NG bank-name resolve (Nigeria only)

{
  "country": "NG",
  "accountNumber": "0123456789",
  "networkId": "058"
}

{
  "accountNumber": "0123456789",
  "accountName": "JANE DOE",
  "accountBank": "GTBank"
}

​

Idempotency

• Reusing the same key returns the original payout record for that key.
• Use a new key for every user-initiated payout attempt to avoid accidental deduping.

​

2FA threshold

​

Settlement webhooks

• payout.initiated — payout accepted and ledger-debited (status CREATED).
• payout.submitted — dispatched to the payout provider (status SUBMITTED).
• payout.settled — funds delivered to the recipient (status SETTLED).
• payout.failed — dispatch or settlement failed; the debit is reversed (status FAILED).
• payout.cancelled — a CREATED payout was cancelled before dispatch (status CANCELLED).
• payout.review — payout held for compliance/admin review (status PENDING_REVIEW).

​

Fee model

​

Confirm payout (raw API)

{
  "rail": "LOCAL_BANK",
  "quoteToken": "<from quote>",
  "recipientId": "<saved recipient id>",
  "idempotencyKey": "merchant-supplied-unique-key"
}

{
  "rail": "LOCAL_BANK",
  "quoteToken": "<from quote>",
  "recipient": {
    "label": "Jane Doe",
    "rail": "LOCAL_BANK",
    "details": {
      "country": "NG",
      "accountNumber": "0123456789",
      "accountName": "Jane Doe",
      "bankCode": "058",
      "bankName": "Example Bank"
    }
  },
  "idempotencyKey": "merchant-supplied-unique-key"
}