> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niobi.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Unified Disbursements
> One endpoint for all disbursement methods across all supported markets. Sends payouts via mobile money, bank transfer, or other supported rails. Each request must carry a freshly generated signature, signatures cannot be reused across requests. See the [Making Payments Guide](/making-payments/basics) and [Payout Methods](/making-payments/methods) for the full field matrix per market.
### Integration Quick Reference
| Requirement | Standard | Rule / Action |
| :-------------------------------------------------------------------------------------- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Settlement Rule**](/making-payments/basics#understanding-payment-steps-payment_step) | `payment_step: 2` only | Funds remain in transit during `payment_step: 1`. Update your ledger and notify recipients only upon receiving [payment\_step: 2](/making-payments/callbacks) with `status: "success"` (`statusCode: "000000"`). |
| [**Signatures**](/authentication/signature-generation) | Fresh per request | Compute a fresh SHA-256 signature for every API call. Signatures cannot be reused. See [Signature Generation](/authentication/signature-generation). |
| [**Wallet Balance**](/api-reference/get-account-balance) | Available balance | Always check [`available_balance`](/api-reference/get-account-balance) (not total balance) before disbursing. See [Payout Best Practices](/making-payments/best-practices). |
| [**Amount Format**](/making-payments/basics#request-parameters) | Whole integers | Pass whole numbers in major currency units (for example, `1000` KES). No decimals allowed. |
| [**Idempotency**](/idempotency) | Unique payout ref | Pass a distinct `payment_reference` / `third_party_reference_1` per payout to prevent duplicate disbursements. See the [Idempotency Guide](/idempotency). |
| [**Delayed Webhook**](/transaction-status) | Query status | If a callback is delayed, query the [Get Transaction Status API](/transaction-status) before re-attempting or failing a transfer. |
| [**Sandbox Testing**](/testing) | Mapped test MSISDNs | Use designated [Sandbox Test Numbers](/testing) mapped to outcomes (success, invalid wallet, timeout) instead of real phone numbers. |
| [**Production Prep**](/go-live-checklist) | Technical checklist | Fund your merchant payout wallet, verify public HTTPS callback URL, and review corridor limits in the [Go-Live Checklist](/go-live-checklist#technical-checklist). |
## List of Supported Countries
| Country Id | Country | Code | Currency | Payment Methods | Status |
| ---------- | ----------------------------------------- | ---- | -------- | --------------------------------------------------- | ------ |
| 1 | [Kenya](/countries/kenya) | 254 | KES | send money, pay bill, till number, pesalink, Airtel | Active |
| 2 | [Benin](/countries/benin) | 229 | XOF | Mtn, Moov | Active |
| 3 | [Cote D'Ivoire](/countries/cote-d-ivoire) | 225 | XOF | Mtn,Orange, Moov, Wave | Active |
| 4 | [Cameroon](/countries/cameroon) | 237 | XAF | Mtn, Orange | Active |
| 5 | [DRC](/countries/drc) | 243 | CDF | Airtel, Orange, Vodacom | Active |
| 8 | [Rwanda](/countries/rwanda) | 250 | RWF | Mtn, Airtel | Active |
| 9 | [Senegal](/countries/senegal) | 221 | XOF | Orange, Free, Wave | Active |
| 10 | [Tanzania](/countries/tanzania) | 255 | TZS | Airtel, Halotel, Tigo, Vodacom | Active |
| 11 | [Uganda](/countries/uganda) | 256 | UGX | Mtn, Airtel | Active |
| 12 | [Zambia](/countries/zambia) | 260 | ZMW | Mtn, Zamtel, Airtel | Active |
| 13 | [Sierra Leone](/countries/sierra-leone) | 232 | SLE | Orange | Active |
| 15 | [South Africa](/countries/south-africa) | 27 | ZAR | bank | Active |
| 16 | [Ghana](/countries/ghana) | 233 | GHS | Mtn, At(AirtelTigo), Vodafone | Active |
| 17 | [Nigeria](/countries/nigeria) | 234 | NGN | bank | Active |
| 19 | [Burkina Faso](/countries/burkina-faso) | 226 | XOF | Orange, Moov | Active |
| 18 | [Mali](/countries/mali) | 223 | XOF | Orange, Moov | Active |
| 20 | [Togo](/countries/togo) | 228 | XOF | moov, tmoney | Active |
**Coming Soon**
| Country | Code | Currency | Payment Methods |
| ----------------------------------- | ---- | -------- | ----------------------- |
| [Ethiopia](/countries/ethiopia) | 251 | ETB | teleBirr, mBirr |
| [Malawi](/countries/malawi) | 265 | MWK | Airtel, tnm |
| [Egypt](/countries/egypt) | 20 | EGP | Vodafone, Orange |
| [Mozambique](/countries/mozambique) | 258 | MZN | Vodacom, Movitel, Tmcel |
### List of Supported Kenyan Banks
| bank\_name | niobi\_bank\_code |
| --------------------------- | ----------------- |
| Kenya Commercial Bank | 1 |
| Standard Chartered | 2 |
| Absa Bank Kenya | 3 |
| Ncba Bank Kenya | 7 |
| Prime Bank | 10 |
| Cooperative Bank | 11 |
| National Bank of Kenya | 12 |
| Citibank N.A Kenya | 16 |
| Middle East Bank Kenya | 18 |
| Bank of Africa Kenya | 19 |
| Credit Bank Limited | 25 |
| CFC Stanbic Kenya | 31 |
| Paramount Bank | 50 |
| Jamii Bora Bank | 51 |
| Guaranty Trust Bank | 53 |
| Guardian Bank | 55 |
| I\&M Bank | 57 |
| Diamond Trust Bank | 63 |
| Sidian Bank | 66 |
| Equity Bank Kenya | 68 |
| Family Bank Limited | 70 |
| Gulf African Bank | 72 |
| First Community Bank | 74 |
| Kenya Women's Finance Trust | 78 |
| Choice Microfinance Bank | 82 |
### List of Supported Nigerian Banks
| bank\_name | bank\_code |
| --------------------------------------------- | ---------- |
| AL-Barakah Microfinance Bank | 090133 |
| 9 Payment Service Bank | 120001 |
| AB Microfinance Bank | 090270 |
| Abbey Mortgage Bank | 070010 |
| Above Only Microfinance Bank | 090260 |
| ABU Microfinance Bank | 090197 |
| Access Bank Nigeria | 044 |
| Access Bank Plc (Diamond) | 063 |
| ACCESS MOBILE | 323 |
| Access Money | 927 |
| Access Yello & Beta | 100052 |
| Accion Microfinance Bank | 090134 |
| Addosser Microfinance Bank | 090160 |
| Adeyemi College Staff Microfinance Bank | 090268 |
| AG Mortgage Bank | 100028 |
| Al-Hayat Microfinance Bank | 090277 |
| Alekun Microfinance Bank | 090259 |
| Alert MFB | 090297 |
| Allworkers Microfinance Bank | 090131 |
| Alpha Kapital Microfinance Bank | 090169 |
| AMJU Unique Microfinance Bank | 090180 |
| AMML Micro-finance Bank | 914 |
| Apeks Microfinance Bank | 090143 |
| Arise MFB | 090282 |
| Aso Savings and Loans | 401 |
| Astrapolaris Microfinance Bank | 090172 |
| Auchi Microfinance Bank | 090264 |
| Baines Credit Microfinance Bank | 090188 |
| Balogun Gambari MFB | 090326 |
| Bayero MICROFINANCE BANK | 090316 |
| BC Kash Microfinance Bank | 090127 |
| BIPC MICROFINANCE BANK | 090336 |
| BOCTrust Micro-finance Bank | 952 |
| Bosak Microfinance Bank | 090176 |
| Bowen Microfinance Bank | 090148 |
| Brent Mortgage Bank | 070015 |
| BRETHREN MICROFINANCE BANK | 090293 |
| BRIDGEWAY MICROFINANCE BANK | 090393 |
| Brightway MFB | 090308 |
| Cellulant | 919 |
| CEMCS Microfinance Bank | 090154 |
| Chams Mobile | 929 |
| Chikum Microfinance Bank | 090141 |
| CIT Microfinance Bank | 090144 |
| Citi Bank | 023 |
| Consumer Microfinance Bank | 090130 |
| Contec Global Infotech Limited (NowNow) | 100032 |
| Coronation Merchant Bank | 559 |
| Covenant Micro-finance Bank | 949 |
| Credit Afrique Microfinance Bank | 090159 |
| Daylight Microfinance Bank | 090167 |
| e-Barcs Microfinance Bank | 090156 |
| Eagle Flight MFB | 090294 |
| Eartholeum | 935 |
| Ecobank | 050 |
| EcoBank Express Account | 922 |
| Ecobank Mobile | 307 |
| Edfin MFB | 090310 |
| Ekondo MFB | 090097 |
| Emeralds Microfinance Bank | 090273 |
| Empire Trust Micro-finance Bank | 913 |
| Enterprise Bank | 084 |
| Esan Microfinance Bank | 090189 |
| Eso-E Microfinance Bank | 090166 |
| eTRANZACT | 920 |
| Evangel MFB | 090304 |
| Evergreen MICROFINANCE BANK | 090332 |
| Eyowo MFB | 090328 |
| FAST Microfinance Bank | 090179 |
| FBN MOBILE | 309 |
| FBN Mortgages Limited | 090107 |
| FBNQuest Merchant Bank | 911 |
| FCMB Easy Account | 100031 |
| FCMB Plc | 214 |
| FCT MFB | 090290 |
| FEDERAL UNIVERSITY DUTSE MICROFINANCE BANK | 090318 |
| FederalPoly NasarawaMFB | 090298 |
| FETS | 915 |
| FFS Microfinance Bank | 090153 |
| Fidelity Bank | 070 |
| Fidelity Mobile | 933 |
| Fidfund Microfinance Bank | 090126 |
| FINATRUST MICROFINANCE BANK | 090111 |
| Firmus MFB | 090366 |
| First Bank of Nigeria | 011 |
| First Generation Mortgage Bank | 070014 |
| First Multiple MFB | 090163 |
| First Option MFB | 090285 |
| First Royal Microfinance Bank | 090164 |
| First Trust Mortgage Bank Plc | 910 |
| FirstMonie Wallet | 928 |
| FlutterWave Technology Solutions Limited | 110002 |
| Fortis Micro-finance Bank | 948 |
| Fortis Mobile | 930 |
| FSDH Merchant Bank | 601 |
| Fullrange Microfinance Bank | 090145 |
| Futo Microfinance Bank | 090158 |
| Gashua Microfinance Bank | 090168 |
| Gateway Mortgage Bank | 070009 |
| Globus Bank | 103 |
| Glory MFB | 090278 |
| GoMoney | 100022 |
| GOODNEWS MICROFINANCE BANK | 090495 |
| Gowans Microfinance Bank | 090122 |
| GreenBank Microfinance Bank | 090178 |
| Greenville Microfinance Bank | 090269 |
| Greenwich Merchant Bank | 060004 |
| Grooming Microfinance Bank | 090195 |
| GT MOBILE | 923 |
| GTBank Mobile Money | 315 |
| GTBank Plc | 058 |
| Hackman Microfinance Bank | 090147 |
| Haggai Mortgage Bank Limited | 070017 |
| Hala MFB | 090291 |
| Hasal Micro-finance Bank | 958 |
| Hedonmark | 931 |
| Heritage Bank | 030 |
| IBILE Microfinance Bank | 090118 |
| IKENNE MFB | 090324 |
| Ikire MFB | 090279 |
| Imo State Microfinance Bank | 090258 |
| Imperial Homes Mortgage Bank | 938 |
| Infinity Microfinance Bank | 090157 |
| Infinity Trust Mortgage Bank | 070016 |
| Innovectives Kesh | 100029 |
| Intellfin | 941 |
| IRL Microfinance Bank | 090149 |
| JAIZ Bank | 301 |
| Jubliee Life | 906 |
| Kadick Integration Limited | 110008 |
| Kadpoly MICROFINANCE BANK | 090320 |
| KCMB Microfinance Bank | 090191 |
| Kegow | 100015 |
| Keystone Bank | 082 |
| Kontagora MFB | 090299 |
| Kuda Micro-finance Bank | 50211 |
| La Fayette Microfinance Bank | 090155 |
| Lagos Building Investment Company | 070012 |
| Lapo Microfinance Bank | 090177 |
| Lavender Microfinance Bank | 090271 |
| Letshego MFB | 090420 |
| Lovonus Microfinance Bank | 090265 |
| M36 | 100035 |
| Mainland MICROFINANCE BANK | 090323 |
| Mainstreet Micro-finance Bank | 014 |
| Malachy Microfinance Bank | 090174 |
| Manny Microfinance bank | 090383 |
| MAUTECH Microfinance Bank | 090423 |
| Mayfair MFB | 090321 |
| MayFresh Mortgage Bank | 070019 |
| Megapraise Microfinance Bank | 090280 |
| Meridian MFB | 090275 |
| Microcred Microfinance Bank | 090136 |
| Midland Microfinance Bank | 090192 |
| Mint-Finex Micro-finance Bank | 50304 |
| Mkudi | 100011 |
| Money Trust Micro-finance Bank | 963 |
| MoneyBox | 934 |
| Mutual Benefits Microfinance Bank | 090190 |
| Mutual Trust Microfinance Bank | 090151 |
| Nagarta Microfinance Bank | 090152 |
| Navy Microfinance Bank | 090263 |
| Ndiorah Microfinance Bank | 090128 |
| New Dawn Microfinance Bank | 090205 |
| New Prudential Bank | 090108 |
| NIP Virtual Bank | 999999 |
| NIRSAL Microfinance Bank | 090194 |
| Nnew women MFB | 090283 |
| Nova Merchant Bank | 637 |
| NPF Micro-finance Bank | 947 |
| Oche MFB | 090333 |
| Ohafia Microfinance Bank | 090119 |
| Okpoga Microfinance Bank | 090161 |
| Olabisi Onabanjo University Microfinance Bank | 090272 |
| Omiye MFB | 090295 |
| Omoluabi Mortgage Bank Plc | 950 |
| One Finance | 940 |
| PAGA | 916 |
| Page Micro-finance Bank | 951 |
| PALMPAY | 100033 |
| PARALLEX BANK | 526 |
| Parkway | 311 |
| ParkWay-ReadyCash | 917 |
| Parralex Microfinance bank | 090004 |
| PatrickGold Microfinance Bank | 090317 |
| PayAttitude Online | 943 |
| PAYCOM | 305 |
| PecanTrust Microfinance Bank | 090137 |
| Pennywise Microfinance Bank | 090196 |
| Personal Trust Microfinance Bank | 090135 |
| Petra Microfinance Bank | 090165 |
| Pillar MFB | 090289 |
| Platinum Mortgage Bank | 070013 |
| Polaris Bank | 076 |
| Polyuwanna MFB | 090296 |
| Prestige Microfinance bank | 090274 |
| Providus Bank | 101 |
| Purplemoney MFB | 090303 |
| Quickfund Microfinance Bank | 090261 |
| Rahama MFB | 090170 |
| Rand Merchant Bank | 502 |
| Refuge Mortgage Bank | 070011 |
| Regent Micro-finance Bank | 955 |
| Reliance Microfinance Bank | 090173 |
| RenMoney Microfinance Bank | 090198 |
| Rephidim MICROFINANCE BANK | 090322 |
| Richway Microfinance Bank | 090132 |
| Royal Exchange Microfinance Bank | 090138 |
| Rubies Micro-finance Bank | 125 |
| Safe Haven MFB | 090286 |
| SafeTrust | 909 |
| Sagamu Micro-finance Bank | 966 |
| Seed Capital Micro-finance Bank | 609 |
| Sparkle | 090325 |
| Stanbic IBTC @ease Wallet | 921 |
| Stanbic IBTC Bank | 221 |
| Stanbic Mobile | 304 |
| Standard Chartered Bank | 068 |
| Stanford Microfinance Bak | 090162 |
| Stellas Microfinance Bank | 090262 |
| Sterling Bank | 232 |
| Sterling Mobile | 936 |
| Sulsap MFB | 090305 |
| Suntrust Bank Nigeria Limited | 100 |
| TAGPAY | 937 |
| Taj Bank | 302 |
| TCF Micro-finance Bank | 567 |
| Teasy MOBILE | 924 |
| Titan Trust Bank | 102 |
| Trident Microfinance Bank | 090146 |
| Trust MFB | 090327 |
| Trustbond Mortgage Bank | 090005 |
| Trustfund Microfinance Bank | 090276 |
| U AND C MFB | 090315 |
| UNAAB MFB | 090331 |
| Uniben Microfinance Bank | 090266 |
| Unical Microfinance Bank | 090193 |
| Union Bank | 032 |
| United Bank for Africa | 033 |
| Unity Bank | 215 |
| UNN MFB | 090251 |
| Verite Microfinance Bank | 090123 |
| VFD Micro-finance Bank | 566 |
| Virtue Microfinance Bank | 090150 |
| Visa Microfinance Bank | 090139 |
| VT Networks | 926 |
| Wema Bank | 035 |
| WetLand Micro-finance Bank | 954 |
| Xslnce Microfinance Bank | 090124 |
| Yes Microfinance Bank | 090142 |
| Zenith Bank Plc | 057 |
| ZENITH Mobile | 322 |
| ZINTERNET - KONGAPAY | 939 |
### Special Disbursement Flows
Some payout corridors require custom nested payload shapes (such as Kenya Paybill, Till Number, and PesaLink) or additional mandatory compliance details (such as Cameroon CEMAC sender identity).
For complete architectural walkthroughs and country rules, see:
* [**Payout Methods Guide**](/making-payments/methods): Step-by-step technical guides for all disbursement channels.
* [**Country Guides Index**](/supported-countries): Country-specific payout corridors, network rules, and test numbers.
`payment_method_type`: `"pay bill"`
Disburse directly to an M-Pesa Paybill business number with an associated account reference.
**Documentation & Guides:**
* [Payout Methods: Kenya Paybill](/making-payments/methods#a-m-pesa-paybill-payouts)
* [Kenya Country Guide: M-Pesa Paybill Payouts](/countries/kenya#payouts-disbursements)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"sender": "YOUR_INTEGRATION_NAME",
"timestamp": 1724835600,
"salt": "random_salt_12345",
"signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
"params": {
"amount": 500,
"currency": "KES",
"country_id": 1,
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "pay bill",
"payment_reference": "YOUR-PAYOUT-REF",
"client_callback_url": "https://yourdomain.com/niobi/payout-callback",
"third_party_reference_1": "TX-KES-PAYBILL-01",
"paybill": [
{
"paybill_number": "333111",
"account_number": "00000000"
}
]
}
}
```
`payment_method_type`: `"till number"`
Disburse directly to an M-Pesa Buy Goods till merchant.
**Documentation & Guides:**
* [Payout Methods: Kenya Buy Goods Till](/making-payments/methods#b-m-pesa-till-number-buy-goods-payouts)
* [Kenya Country Guide: Buy Goods Till Payouts](/countries/kenya#payouts-disbursements)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"sender": "YOUR_INTEGRATION_NAME",
"timestamp": 1724835600,
"salt": "random_salt_12345",
"signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
"params": {
"amount": 500,
"currency": "KES",
"country_id": 1,
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "till number",
"payment_reference": "YOUR-PAYOUT-REF",
"client_callback_url": "https://yourdomain.com/niobi/payout-callback",
"third_party_reference_1": "TX-KES-TILL-01",
"tillnumber": [
{
"till_number": "222750"
}
]
}
}
```
`payment_method_type`: `"pesalink"`
Real-time bank transfer to any commercial bank in Kenya. See [Supported Kenyan Banks](#list-of-supported-kenyan-banks) above for `bank_code` values.
**Documentation & Guides:**
* [Payout Methods: PesaLink Instant Bank Transfers](/making-payments/methods#c-pesalink-instant-bank-transfers)
* [Kenya Country Guide: PesaLink Bank Transfers](/countries/kenya#payouts-disbursements)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"params": {
"amount": 5000,
"client_callback_url": "https://example.com/callback",
"country_id": 1,
"currency": "KES",
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "pesalink",
"payment_reference": "YOUR-PAYOUT-REF",
"third_party_reference_1": "TX-KES-PESA-2002",
"pesalink": [
{
"bank_name": "Co-operative Bank",
"bank_code": "11",
"branch_name": "Nairobi",
"account_name": "John Doe",
"account_number": "123223837"
}
]
},
"salt": "random_salt_12345",
"sender": "YOUR_INTEGRATION_NAME",
"timestamp": 1724835600,
"signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0"
}
```
`payment_method_type`: `"bank"`
Direct bank disbursements to commercial and microfinance banks (e.g. Nigeria NUBAN, South Africa RTC/EFT, or International SWIFT/SEPA/Wire).
**Documentation & Guides:**
* [Payout Methods: Nigeria NGN Bank Payouts](/making-payments/methods#3-nigeria-ngn-bank-payouts)
* [Nigeria Country Guide: Bank Payouts](/countries/nigeria#payouts-disbursements)
* [South Africa Country Guide: Bank Payouts](/countries/south-africa#payouts-disbursements)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"sender": "YOUR_INTEGRATION_NAME",
"timestamp": 1724835600,
"salt": "random_salt_12345",
"signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
"params": {
"amount": 5000,
"currency": "NGN",
"country_id": 17,
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "bank",
"payment_reference": "YOUR-PAYOUT-REF",
"client_callback_url": "https://yourdomain.com/niobi/payout-callback",
"third_party_reference_1": "TX-NGN-DISB-1001",
"bank": [
{
"bank_name": "First Bank of Nigeria",
"bank_code": "011",
"branch_name": "Victoria Island",
"account_name": "John Doe",
"account_number": "0123456789"
}
]
}
}
```
In accordance with CEMAC regional financial compliance regulations, all payouts in Cameroon (`country_id: 4`, currency `XAF`) require the identification details of the originating sender: `sender_firstname`, `sender_lastname`, and `sender_phone_number` (all required).
**Documentation & Guides:**
* [Payout Methods: Cameroon CEMAC Compliance](/making-payments/methods#4-cameroon-xaf-compliance-cemac-sender-information)
* [Cameroon Country Guide: CEMAC Compliance Rules](/countries/cameroon#payouts-disbursements)
```json theme={null}
{
"client_id": "YOUR_CLIENT_ID",
"sender": "YOUR_INTEGRATION_NAME",
"timestamp": 1724835600,
"salt": "random_salt_12345",
"signature": "d4e5f6a7b8c90123456789abcdef0123456789abcdef0123456789abcdef01",
"params": {
"amount": 10000,
"currency": "XAF",
"country_id": 4,
"first_name": "Jean",
"last_name": "Dupont",
"mobile": "237791189789",
"email": "jean.dupont@example.com",
"city": "Yaounde",
"sender_firstname": "John",
"sender_lastname": "Doe",
"sender_phone_number": "237690000000",
"payment_method_type": "Orange",
"Orange": [
{ "phone_number": "237791189789" }
],
"client_callback_url": "https://yourdomain.com/niobi/payout-callback",
"payment_reference": "CAM-DISB-3001"
}
}
```
## OpenAPI
````yaml post /api/v4/niobi-unified-payments
openapi: 3.0.0
info:
title: Niobi API
description: >-
REST API for collecting payments, sending payouts, and managing
multi-currency wallets across Africa and global corridors. All requests
require IP whitelisting and a unique per-request HMAC SHA-256 signature.
version: 4.0.0
servers:
- url: https://sandbox.users.niobi.co
description: Sandbox, Development and Testing
security: []
tags:
- name: Niobi
description: API Endpoints of Niobi
paths:
/api/v4/niobi-unified-payments:
post:
tags:
- payment
summary: Niobi Unified Payments
description: >-
One endpoint for all disbursement methods across all supported markets.
Sends payouts via mobile money, bank transfer, or other supported rails.
Each request must carry a freshly generated signature, signatures cannot
be reused across requests. See the [Making Payments
Guide](/making-payments/basics) and [Payout
Methods](/making-payments/methods) for the full field matrix per market.
operationId: NiobiUnifiedPayments
requestBody:
description: >-
Signed request envelope. All root fields except params are
authentication fields.
required: true
content:
application/json:
schema:
required:
- client_id
- params
- salt
- sender
- timestamp
- signature
properties:
client_id:
description: >-
Your Client ID from the Niobi Dashboard under Workspace >
Integrations.
type: string
example: K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr
params:
required:
- amount
- currency
- payment_reference
- first_name
- last_name
- mobile
- email
- country_id
- city
- postal_code
- line1
- client_callback_url
- payment_method_type
- sender_firstname*
- sender_lastname*
- sender_phone_number*
properties:
amount:
description: >-
Payout amount in the smallest whole unit of the
currency. Pass 1000 for 1000 KES, not 10.00.
type: integer
example: 1000
customer_identifier:
description: >-
Sub-wallet identifier. Required only if disbursing from
a sub-wallet.
type: integer
example: 1234
currency:
description: >-
ISO 4217 currency code for the payout. Must match the
destination country.
type: string
example: KES
payment_reference:
description: >-
Your internal reference for this payout. Returned in
callbacks so you can reconcile.
type: string
example: TRANS-123456789
first_name:
description: First name of the recipient.
type: string
example: John
last_name:
description: Last name of the recipient.
type: string
example: Doe
mobile:
description: Recipient's phone number in international format.
type: string
example: '254647647649'
email:
description: Recipient's email address.
type: string
example: john@doe.com
country_id:
description: >-
Numeric country ID for the destination market. See the
supported countries table on this page.
type: integer
example: '1'
city:
description: Recipient's city.
type: string
example: Nairobi
postal_code:
description: Recipient's postal code.
type: string
example: '001001'
line1:
description: Recipient's street address.
type: string
example: 123 Main St
description:
description: Optional note or memo attached to the payout.
type: string
example: Invoice payment
client_callback_url:
description: >-
HTTPS endpoint Niobi will POST the payout result to.
Must be publicly reachable.
type: string
example: https://your-domain.com/niobi/result
third_party_reference_1:
description: Your internal transaction reference. Optional.
type: string
format: string
third_party_reference_2:
description: Your external transaction reference. Optional.
type: string
format: string
sub_merchant_id:
description: >-
The sub-merchant's ID. Required only if your integration
is configured for sub-merchant routing; not applicable
otherwise. See [Sub-Merchant
Management](/submerchant/sub-merchant-management).
type: string
format: uuid
is_third_party_reference_1_unique:
description: >-
Set to true to reject duplicate payouts sharing the same
third_party_reference_1 value.
type: boolean
format: boolean
is_third_party_reference_2_unique:
description: >-
Set to true to reject duplicate payouts sharing the same
third_party_reference_2 value.
type: boolean
format: boolean
payment_method_type:
description: >-
The payout rail to use. Must match a method available in
the destination country. See the [Disbursements
Guide](/making-payments/basics) for the full
method-per-country matrix.
type: string
enum:
- mtn
- Orange
- Vodacom
- Airtel
- at
- Vodafone
- tnm
- Zamtel
- Halotel
- Tigo
- Free
- send money
- till number
- pay bill
- pesalink
example: send money
mtn:
description: Recipient's MTN mobile number in international format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's MTN mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Orange:
description: >-
Recipient's Orange mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Orange mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Vodacom:
description: >-
Recipient's Vodacom mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Vodacom mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Airtel:
description: >-
Recipient's Airtel mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Airtel mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
at:
description: >-
Recipient's AirtelTigo mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's AirtelTigo mobile number in
international format.
type: string
format: phone_number
example: '254647647649'
type: object
Vodafone:
description: >-
Recipient's Vodafone mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Vodafone mobile number in
international format.
type: string
format: phone_number
example: '254647647649'
type: object
tnm:
description: Recipient's TNM mobile number in international format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's TNM mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Zamtel:
description: >-
Recipient's Zamtel mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Zamtel mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Halotel:
description: >-
Recipient's Halotel mobile number in international
format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Recipient's Halotel mobile number in international
format.
type: string
format: phone_number
example: '254647647649'
type: object
Tigo:
description: Recipient's Tigo mobile number in international format.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Enter the recipient's mobile number. Be sure to
use the right fomatting
type: string
format: phone_number
example: '254647647649'
type: object
Free:
description: >-
Using Free method needs a recipient's phone number of
payment method
type: array
items:
required:
- phone_number
properties:
phone_number:
description: >-
Enter the recipient's mobile number. Be sure to
use the right fomatting
type: string
format: phone_number
example: '254647647649'
type: object
sendmoney:
description: Details for the send money payment method.
type: array
items:
required:
- phone_number
properties:
phone_number:
description: Recipient's mobile number for send money method.
type: string
example: '254647647649'
type: object
paybill:
description: Details for the pay bill payment method.
type: array
items:
required:
- paybill_number
- account_number
properties:
paybill_number:
description: Paybill number for the transaction.
type: string
example: '123456'
account_number:
description: Account number for the transaction.
type: string
example: '123456789'
type: object
tillnumber:
description: Details for the till number payment method.
type: array
items:
required:
- till_number
properties:
till_number:
description: Till number for the transaction.
type: string
example: '123456'
type: object
pesalink:
description: Details for the pesalink payment method.
type: array
items:
required:
- bank_name
- bank_code
- branch_name
- account_name
- account_number
properties:
bank_name:
description: Bank name for the pesalink transfer.
type: string
example: ABC
bank_code:
description: Bank code for the pesalink transfer.
type: string
example: '00'
branch_name:
description: Branch name for the pesalink transfer.
type: string
example: ABC
account_name:
description: Account name for the pesalink transfer.
type: string
example: ABC
account_number:
description: Account number for the pesalink transfer.
type: string
example: '123456789'
type: object
bank:
description: >-
Details for bank transfers (e.g. Nigeria NGN, South
Africa ZAR, and international bank payouts).
type: array
items:
required:
- bank_name
- bank_code
- branch_name
- account_name
- account_number
properties:
bank_name:
description: Bank name for the bank transfer.
type: string
example: First Bank of Nigeria
bank_code:
description: Bank code for the bank transfer.
type: string
example: '011'
branch_name:
description: Branch name for the bank transfer.
type: string
example: Victoria Island
account_name:
description: Account name for the bank transfer.
type: string
example: John Doe
account_number:
description: Account number or IBAN for the bank transfer.
type: string
example: '0123456789'
type: object
sender_firstname:
description: >-
First name of the sender. Required for XAF (Cameroon)
payouts only.
type: string
example: John
sender_lastname:
description: >-
Last name of the sender. Required for XAF (Cameroon)
payouts only.
type: string
example: Doe
sender_phone_number:
description: >-
Sender's phone number in international format. Required
for XAF (Cameroon) payouts only.
type: string
example: '237600000000'
type: object
salt:
description: >-
A unique random string you generate per request. Must be the
same value used when generating the signature.
type: string
example: justrandomstring
sender:
description: >-
The exact title of your integration as registered in the
Dashboard. Case-sensitive.
type: string
example: John.co
timestamp:
description: >-
Unix timestamp in seconds at the time of signing. Must match
the value used to generate the signature.
type: integer
example: 1709363033
signature:
description: >-
SHA-256 signature computed from this payload. Generate via
the [Signature
endpoint](/api-reference/authentication/generate-signature)
or your own backend.
type: string
example: >-
2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807
type: object
responses:
'200':
description: Payment process initiated successfully.
content:
application/json:
schema:
properties:
success:
type: boolean
example: true
message:
description: >-
Describes the result of initiating the payout. Exact
wording may vary depending on the payment processor or
channel.
type: string
example: Payment process initiated successfully.
data:
type: object
properties:
reference:
type: string
example: NIO-PAY-001
description: Niobi transaction tracking ID for status query
type:
type: string
example: send money
description: Payout disbursement method channel
total:
type: number
example: 1000
description: Disbursement principal amount
creation_date:
type: string
example: '2026-08-29T12:00:00Z'
description: Transaction creation timestamp
execution_date:
type: string
example: '2026-08-29T12:00:00Z'
description: Execution timestamp
from:
type: string
example: John Doe
description: Sender merchant account title
to:
type: string
example: '254161166649'
description: Recipient phone number or bank account
invoice_date:
type: string
example: '2026-08-29T12:00:00Z'
description: Invoice timestamp
invoice_amount:
type: number
example: 1000
description: Invoice amount
payment_step:
type: integer
example: 1
description: >-
Step 1: Request initiated and queued upstream. Final
status arrives via Step 2 callback.
status_code:
type: string
example: '000000'
type: object
example:
success: true
message: Payment process initiated successfully.
data:
reference: S000001234
type: MPESA Send Money
total: 500
creation_date: '2026-08-12T09:53:40.000000Z'
execution_date: '2026-08-12T09:53:44.000000Z'
from: John Doe
to: '254712345678'
invoice_date: '2026-08-12'
invoice_amount: 500
payment_step: 1
status_code: '000000'
example:
success: true
message: Payment process initiated successfully.
data:
reference: NIO-PAY-001
type: send money
total: 1000
creation_date: '2026-08-29T12:00:00Z'
execution_date: '2026-08-29T12:00:00Z'
from: John Doe
to: '254161166649'
invoice_date: '2026-08-29T12:00:00Z'
invoice_amount: 1000
payment_step: 1
status_code: '000000'
'400':
description: >-
Country was not found or Niobi user not found or Payment process
initiation failed.
content:
application/json:
schema:
properties:
success:
type: boolean
example: false
message:
type: string
example: >-
Country was not found or Niobi user not found or Payment
process initiation failed.
type: object
'403':
description: >-
Entity integration record not found or Client id not matched or
Request was not verified.
content:
application/json:
schema:
properties:
success:
type: boolean
example: false
message:
type: string
example: >-
Entity integration record not found or Client id not
matched or Request was not verified.
type: object
'404':
description: User not found
content:
application/json:
schema:
properties:
success:
type: boolean
example: false
message:
type: string
example: User not found.
type: object
'500':
description: Internal Server Error
````