Banks

Lookup table for NG bank codes. Returns the (cbn_code, nip_code, name, slug, kind) tuples Swappr knows about, filtered to banks you can actually pay to.

Bank codes are accepted in two forms on payouts (locked 2026-05-15):

cbn_code — 3-digit CBN canonical code (e.g. 058 for GTBank). Shorter, more portable, matches CBN circulars + NIBSS reference tables + most provider dashboards. Recommended.
nip_code — 6-digit NIBSS NIP code (e.g. 000013 for GTBank). Useful if your internal systems already speak NIBSS NIP.

Both forms are accepted on recipient.bank_code for single payouts (POST /v1/payouts) and recipient_bank_code per row on bulk batches (POST /v1/batches). Swappr canonicalizes to 3-digit CBN internally before dispatch, so your payout works against every provider in the routing cascade regardless of which form you sent.

GETList banks

GET/v1/banks?currency=NGN

Returns the curated list of NG banks you can pay to, with both code forms for each. Heavily cached (5-minute TTL on Swappr’s side; safe to cache locally for hours).

Query parameters

currencystringRequired

Must be NGN (only currency with a public bank list today).

Response fields

Field	Type	Notes
`code`	string	Back-compat alias for `cbn_code`. Falls back to `nip_code` when the bank’s `cbn_code` is null (typical for MFBs / fintechs / mobile money).
`cbn_code`	string \| null	3-digit CBN canonical code. Null for banks that aren’t in CBN’s commercial-bank list (MFBs, fintechs, mobile money — most have only `nip_code`).
`nip_code`	string \| null	6-digit NIBSS NIP code. Most banks have this; a small number of legacy DMB rows have only `cbn_code`.
`name`	string	Canonical display name.
`slug`	string	Stable lowercase identifier — useful for icons + autocomplete.
`kind`	string	One of `dmb` / `mfb` / `mobile_money` / `psb` / `merchant_bank` / `fintech`.

Bank kinds

Kind	Description
`dmb`	Deposit Money Bank — the major commercial banks
`mfb`	Microfinance Bank
`mobile_money`	Mobile money operator (e.g. OPay, PalmPay)
`psb`	Payment Service Bank
`merchant_bank`	Merchant bank
`fintech`	Fintech / neobank

Notes

Only banks marked is_exposed_to_merchants in our DB appear here. We curate the list — by default, ~80-90 of 906 NIBSS-registered banks are exposed.
Most banks have BOTH cbn_code and nip_code populated. A handful (Moniepoint MFB, Kuda, OPay, PalmPay, etc.) only have nip_code — pass that on recipient.bank_code and it will work.
slug is a stable lowercase identifier useful for icons + autocomplete.

How bank codes flow downstream

Swappr canonicalizes every inbound bank_code to the 3-digit CBN form before dispatching to the underlying payment rail. So:

Whether you send 058 or 000013 on recipient.bank_code, the dispatcher resolves both to the same canonical bank.
Different rails natively accept different formats — that’s not your problem. The canonicalizer handles translation per rail.
If the bank_code you sent doesn’t match any Bank row’s cbn_code or nip_code, you get unknown_bank_code (422) at request time. You never see a downstream failure from a format mismatch.

Send whichever form is easier for your stack. The result is identical.

Errors

Code	HTTP	Cause
`unsupported_currency`	400	Anything other than `NGN`
`unknown_bank_code`	422 (returned by `/v1/payouts` + `/v1/batches`, not this endpoint)	A `bank_code` value was sent on a payout that doesn’t match any Bank row’s `cbn_code` or `nip_code`.

Request

curl 'https://api.swappr.me/api/v1/banks?currency=NGN' \
  -H "Authorization: Bearer sk_live_..."

// Fetch once at app start, cache in memory
type Bank = { code: string; cbn_code: string | null; nip_code: string | null; name: string; slug: string; kind: string };
let bankList: Bank[] | null = null;
let bankListExpiresAt = 0;
 
async function getBanks(): Promise<Bank[]> {
  if (bankList && Date.now() < bankListExpiresAt) return bankList;
 
  const res = await fetch('https://api.swappr.me/api/v1/banks?currency=NGN', {
    headers: { 'Authorization': `Bearer ${process.env.SWAPPR_API_KEY}` },
  });
  const data = await res.json();
 
  bankList = data.data;
  bankListExpiresAt = Date.now() + 60 * 60 * 1000; // 1h
  return bankList;
}

import os, time, requests
from typing import Optional
 
# Fetch once at app start, cache in memory.
_bank_list: Optional[list] = None
_bank_list_expires_at: float = 0
 
def get_banks() -> list:
    global _bank_list, _bank_list_expires_at
    if _bank_list and time.time() < _bank_list_expires_at:
        return _bank_list
 
    res = requests.get(
        'https://api.swappr.me/api/v1/banks',
        params={'currency': 'NGN'},
        headers={'Authorization': f"Bearer {os.environ['SWAPPR_API_KEY']}"},
    )
    res.raise_for_status()
 
    _bank_list = res.json()['data']
    _bank_list_expires_at = time.time() + 60 * 60  # 1h
    return _bank_list

Response

{
  "object": "list",
  "data": [
    {
      "code": "044",
      "cbn_code": "044",
      "nip_code": "000014",
      "name": "Access Bank",
      "slug": "access-bank",
      "kind": "dmb"
    },
    {
      "code": "058",
      "cbn_code": "058",
      "nip_code": "000013",
      "name": "Guaranty Trust Bank",
      "slug": "gtbank",
      "kind": "dmb"
    },
    {
      "code": "090405",
      "cbn_code": null,
      "nip_code": "090405",
      "name": "Moniepoint MFB",
      "slug": "moniepoint-mfb",
      "kind": "mfb"
    }
    // ...
  ]
}

200 OK

Reports Currencies