Overview
The Remittance API sends funds from a merchant wallet (KES or USD) to a recipient on a supported destination corridor, over mobile money or bank transfer. Quotes are live-priced. The wallet is debited only when you execute the transfer.
- Purpose: Quote, verify, and send cross-border payouts from your business wallet.
- Target Audience: Merchants and fintechs sending payouts to supported destination countries.
Integration flow
- Authenticate with a Bearer token and whitelist your server IP.
- Save the sender (KYC) profile, then confirm readiness.
- List destinations. For bank rails, fetch banks for that country.
- Request a quote (send or receive amount).
- Verify the recipient phone or bank account.
- Create the remittance against the quote. By default it executes immediately.
- Poll status or wait for the webhook on your
result_url.
Authentication
All remittance endpoints except the provider callback require a Bearer token and an approved source IP. Pass the merchant business as X-Business-Id.
| Header | Type | Description | Required |
|---|
| Authorization | string | Bearer token from Authentication. | Yes |
| Accept | string | application/json | Yes |
| Content-Type | string | application/json on POST/PUT. | Conditional |
| X-Business-Id | integer | Merchant business ID. If omitted, the first business on the authenticated user is used. | Recommended |
Remittance does not use Signature or x-hash. Those headers apply to C2B/B2C payment endpoints only.
Source wallets
Fund the transfer from a wallet whose currency is KES or USD. wallet_no is the wallet slug. The wallet must belong to the business in X-Business-Id.
Destination corridors
Use ISO country codes and the matching currency. Fetch the live list from Destinations & Banks.
| Country | Code | Currency |
|---|
| Tanzania | TZ | TZS |
| United Arab Emirates | AE | AED |
| Bangladesh | BD | BDT |
| United Kingdom | GB | GBP |
| Ghana | GH | GHS |
| India | IN | INR |
| Kenya | KE | KES |
| Nigeria | NG | NGN |
| Pakistan | PK | PKR |
| Rwanda | RW | RWF |
| Uganda | UG | UGX |
| United States | US | USD |
| South Africa | ZA | ZAR |
Rails
| Rail | Recipient fields |
|---|
mobile_money | other_names, surname, phone (international format, e.g. 2567XXXXXXXX) |
bank | other_names, surname, account_number, bank_code, bank_name |
Statuses
| Status | Meaning |
|---|
pending_approval | Created with auto_execute: false. Wallet not yet debited. |
processing | Submitted to the payout rail. Wallet already debited. |
successful | Provider confirmed payout. |
failed | Provider rejected the payout or submit failed. |
expired | Reserved status. Request a new quote if the quote TTL elapsed. |
Endpoint catalog
| Method | Path | Auth | Page |
|---|
| GET | /api/v2/remit/readiness | Bearer + IP | Sender |
| PUT | /api/v2/remit/sender | Bearer + IP | Sender |
| GET | /api/v2/remit/destinations | Bearer + IP | Destinations |
| GET | /api/v2/remit/banks?country=UG | Bearer + IP | Destinations |
| POST | /api/v2/remit/quotes | Bearer + IP | Quote |
| POST | /api/v2/remit/verify | Bearer + IP | Verify |
| POST | /api/v2/remit | Bearer + IP | Create |
| POST | /api/v2/remit/{id}/execute | Bearer + IP | Create |
| GET | /api/v2/remit | Bearer + IP | Status |
| GET | /api/v2/remit/{reference} | Bearer + IP | Status |
| POST | /api/v2/remit/callback | Public (provider) | Status |
Wallet debit
- Create with
auto_execute: true (default) debits immediately and submits the payout.
- Create with
auto_execute: false leaves the remittance in pending_approval. Debit happens on POST /api/v2/remit/{id}/execute.
- Existing C2B collections and B2C payouts are unchanged. Remittance is a separate
/api/v2/remit/* surface.
Terms of Use & Legal
By using this API, you agree to our Terms of Service and Privacy Policy. Do not share sensitive data or credentials.