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.

Any code this endpoint publishes for a bank is accepted on payouts: the code is validated against this bank list, not a length rule. Each bank carries up to two codes:

cbn_code: the bank’s CBN / NIBSS canonical code (e.g. 058 for GTBank, 50515 for Moniepoint). Shorter for the legacy DMBs, matches CBN circulars + most provider dashboards. Recommended.
nip_code: the bank’s NIBSS NIP code (e.g. 000013 for GTBank). Useful if your internal systems already speak NIBSS NIP.

Real codes come in several widths (3-, 5- and 6-digit), so don’t validate by length: look the bank up here and send whichever code it publishes. Either column is accepted on recipient.bank_code for single payouts (POST /v1/payouts) and recipient_bank_code per row on bulk batches (POST /v1/batches); a code no bank carries returns 422 unknown_bank_code. Swappr canonicalizes to the 3-digit CBN form internally before dispatch, so your payout works against every provider in the routing cascade regardless of which code 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	CBN / NIBSS canonical code (3-digit for legacy DMBs like `058`, 5-digit for many MFBs like `50515`). Null for banks with only a `nip_code`.
`nip_code`	string \| null	NIBSS NIP code (typically 6-digit, e.g. `000013`). 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.
Retired codes of banks that merged into another bank (for example Diamond Bank’s 063, now part of Access Bank) are still accepted and resolve to the successor bank. Always prefer the codes GET /v1/banks publishes.

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 Mobile money operators