NGN payouts

Send NGN to any Nigerian bank account, settled over the Nigerian interbank rails (NIP). 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",
  "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

When a provider’s result is unclear

Sometimes we send a payout to a provider and cannot tell whether it went through, for example when the provider times out or answers with a temporary error after receiving the request. If we can’t confirm whether the provider received the payout, it stays queued or processing while we confirm. It is never refunded until we know the money did not move. It then moves to paid, or to reversed with a refund.

While we confirm, you receive no payout_failed event for it, and it can’t be cancelled (cancel returns 400 invalid_status). Once a held queued payout has been waiting at least 30 minutes, you can re-query it: we ask the provider, and it can only move to paid. Any other answer leaves it queued and nothing is refunded. A re-query sooner than 30 minutes returns 400 invalid_status. Don’t send the same payment again under a new reference while it is in this state, or the recipient could be paid twice. Wait for payout_paid or payout_reversed.

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_..."