NGN payouts

Send NGN to any Nigerian bank account. Routed over the Nigerian interbank rails (NIP) through a multi-provider cascade — if one provider can’t reach a bank, Swappr automatically tries the next. Recipient names are auto-resolved from the account number, so you only send account_number + bank_code.

New to payouts? Start with the Payouts overview for the common fields, customer attribution, and management endpoints shared across every currency.

Want the exact fee before you send? Preview it with POST /v1/payouts/quote — an advisory, read-only fee + cost breakdown for your account.

The payout object

{
  "object": "payout",
  "id": "ckxxxxxxxxxxxxxxxxxx",
  "reference": "po_xxxxxxxxxxxx",
  "status": "paid",
  "currency": "NGN",
  "amount_minor": "500000",
  "fee_minor": "75",
  "tax_minor": "0",
  "total_debit_minor": "500075",
  "recipient_name": "ADAEZE BLESSING NWAFOR",
  "recipient_account": "0690000032",
  "recipient_bank_code": "044",
  "wallet_id": "ckwallet_xxx",
  "provider": "<provider_slug>",
  "provider_ref": "<provider_ref>",
  "nip_reference": "100004250505000123456789",
  "merchant_reference": "ORDER_001",
  "narration": "Payroll April 2026",
  "customer_id": null,
  "customer_reference": null,
  "batch_id": null,
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-05-05T12:34:50.123Z",
  "queued_at": "2026-05-05T12:34:50.456Z",
  "processing_at": "2026-05-05T12:34:51.789Z",
  "completed_at": "2026-05-05T12:34:56.789Z"
}

Status values

Maker-checker rules

Single payouts that exceed your account’s per-transaction dual-control threshold land in draft status awaiting team approval (approve via the dashboard or your internal tooling that calls our dashboard API).

Live-merchant Owner-only self-approve: on live-approved merchants, only the team member assigned the Owner role can approve their own draft payouts. All other roles drop to maker-checker on live and need a different teammate to approve, even when they hold both payout_create and payout_approve. Sandbox keeps dual-perm self-approve for development velocity. The Owner role is capped at 3 holders per merchant.

Email-OTP gate (dashboard only)

The dashboard’s New Payout and Approve flows can require an email-OTP before submit and/or approve, configured per (merchant, env, currency).

API integrations bypass the OTP gate entirely — POST /v1/payouts authenticates via Bearer token + IP allowlist + Idempotency-Key, which is the right machine-to-machine shape. The OTP is a dashboard-only control for human-clicked actions.

{
  "account_number": "0690000032",
  "bank_code": "044"
}

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "500000",
    "currency": "NGN",
    "recipient": {
      "account_number": "0690000032",
      "bank_code": "044"
    },
    "merchant_reference": "ORDER_001",
    "narration": "Payroll April 2026",
    "customer_id": "cust_cmoji8..."
  }'

import { randomUUID } from 'crypto';
 
const res = await fetch('https://api.swappr.me/api/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount_minor: '500000',
    currency: 'NGN',
    recipient: { account_number: '0690000032', bank_code: '044' },
    merchant_reference: 'ORDER_001',
    narration: 'Payroll April 2026',
  }),
});
 
const payout = await res.json();

import os, uuid, requests
 
res = requests.post(
    'https://api.swappr.me/api/v1/payouts',
    headers={
        'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}",
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'amount_minor': '500000',
        'currency': 'NGN',
        'recipient': {'account_number': '0690000032', 'bank_code': '044'},
        'merchant_reference': 'ORDER_001',
        'narration': 'Payroll April 2026',
    },
)
payout = res.json()

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "500000",
    "currency": "NGN",
    "beneficiary_id": "ben_cmo8x2p9q0...",
    "merchant_reference": "ORDER_002"
  }'

Response

201 Created with the payout object. Status is typically paid in sandbox, or queued / processing in live (transitions to paid when the provider confirms — listen for the payout.paid webhook).

Webhook events

NGN payouts emit payout.processing, then payout.paid or payout.failed (and payout.reversed if a paid payout is later reversed). If you set customer_id / customer_reference, they’re included in the event payload. See Webhooks.

Fund from another currency (cross-currency)

You can fund an NGN payout from a different wallet currency (e.g. pay ₦ from your CAD wallet) in a single call by adding funding_currency to the request. See Cross-currency payouts for the full method, both amount options (destination / source), the fx response block, fee_inclusive, rate-freshness behaviour, and the error table.

Manage payouts

These endpoints are currency-agnostic — they work the same for NGN and every FX currency.

{
  "object": "list",
  "has_more": true,
  "data": [{ "object": "payout", "id": "...", "...": "..." }]
}

curl https://api.swappr.me/api/v1/payouts/po_da06226542dc44a9 \
  -H "Authorization: Bearer sk_test_..."