Transfers API
Send funds from your Transfer wallet to any bank account in Nigeria
The Transfers API lets you programmatically send money from your Transfer wallet to any Nigerian bank account. The typical flow is:
- List banks to get a valid
bankCode - Verify the account to confirm the recipient's name
- Fund your Transfer wallet (one-time setup)
- Initiate a transfer
Authentication
All transfer endpoints require your secret key in the Authorization header.
Authorization: Bearer sk_live_your_secret_key[!IMPORTANT] Use
sk_live_...for real payouts.sk_test_...will route through the sandbox — no real money moves.
List Banks
Returns all banks supported for NGN payouts.
GET /api/v1/transfers/banksQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
currency | string | No | Currency code. Defaults to NGN. |
Example Request
curl -X GET "https://api.uveruspayments.com/api/v1/transfers/banks?currency=NGN" \
-H "Authorization: Bearer sk_live_..."Example Response
[
{ "name": "Access Bank", "code": "044", "currency": "NGN" },
{ "name": "First Bank of Nigeria", "code": "011", "currency": "NGN" },
{ "name": "Guaranty Trust Bank", "code": "058", "currency": "NGN" },
{ "name": "United Bank for Africa", "code": "033", "currency": "NGN" },
{ "name": "Zenith Bank", "code": "057", "currency": "NGN" }
]Verify Bank Account
Resolve a bank account number to an account name before initiating a transfer. This prevents sending to the wrong account.
POST /api/v1/transfers/verify-accountRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
accountNumber | string | Yes | 10-digit bank account number |
bankCode | string | Yes | Bank code from the /transfers/banks list |
currency | string | No | Currency code. Defaults to NGN. |
Example Request
curl -X POST "https://api.uveruspayments.com/api/v1/transfers/verify-account" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "0123456789",
"bankCode": "044"
}'Example Response
{
"account_name": "JOHN DOE",
"account_number": "0123456789",
"bank_code": "044"
}Fund Your Transfer Wallet
To initiate transfers, your Transfer wallet must have a sufficient balance. The easiest way to fund it is by activating a dedicated virtual bank account — a permanent account number you can send money to at any time.
Activate a Funding Account
Generate a permanent dedicated virtual bank account for your Transfer wallet. This is a one-time setup — calling it again returns the existing account.
POST /api/v1/transfers/funding-account/activate[!NOTE] Requires OWNER or ADMIN role.
Example Request
curl -X POST "https://api.uveruspayments.com/api/v1/transfers/funding-account/activate" \
-H "Authorization: Bearer sk_live_..."Example Response
{
"accountNumber": "9190967871",
"accountName": "YOUR BUSINESS NAME",
"bankName": "Wema Bank",
"bankCode": "035",
"currency": "NGN",
"isActive": true
}Send any amount to this account and your Transfer wallet balance is credited automatically within seconds.
Get Funding Account
Retrieve your existing dedicated funding account details.
GET /api/v1/transfers/funding-accountcurl -X GET "https://api.uveruspayments.com/api/v1/transfers/funding-account" \
-H "Authorization: Bearer sk_live_..."Returns the same object as activate, or null if not yet activated.
Initiate a Transfer
Send funds from your Transfer wallet to a bank account.
[!IMPORTANT] Amounts are in kobo — the lowest denomination.
500000kobo = ₦5,000. Minimum transfer is100kobo (₦1).
POST /api/v1/transfers[!NOTE] Requires OWNER or ADMIN role.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | integer | Yes | Amount in kobo (e.g. 500000 = ₦5,000). Min: 100 |
bankCode | string | Yes | Bank code from /transfers/banks |
accountNumber | string | Yes | Recipient's 10-digit bank account number |
narration | string | No | Description shown on the recipient's bank statement |
currency | string | No | Currency code. Defaults to NGN. |
bankName | string | No | Bank name (for display purposes only) |
Example Request
curl -X POST "https://api.uveruspayments.com/api/v1/transfers" \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 500000,
"bankCode": "058",
"accountNumber": "0123456789",
"narration": "Payment for invoice #1042",
"bankName": "Guaranty Trust Bank"
}'Example Response
{
"id": "a3f1e291-2b4c-4d5e-9f1a-abc123def456",
"reference": "TRF-SPO-1718901234567",
"amount": 500000,
"currency": "NGN",
"status": "pending",
"bankCode": "058",
"bankName": "Guaranty Trust Bank",
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"narration": "Payment for invoice #1042",
"createdAt": "2026-06-20T14:30:00.000Z"
}Transfer Statuses
| Status | Description |
|---|---|
pending | Transfer queued, awaiting processing |
processing | Sent to the bank network |
success | Funds delivered to recipient |
failed | Transfer failed — funds returned to your Transfer wallet |
Get Transfer by Reference
Retrieve the current status and details of a specific transfer.
GET /api/v1/transfers/{reference}Example Request
curl -X GET "https://api.uveruspayments.com/api/v1/transfers/TRF-SPO-1718901234567" \
-H "Authorization: Bearer sk_live_..."Returns the same TransferResponse object as the initiate endpoint.
List Transfers
Returns a paginated list of all outbound transfers.
GET /api/v1/transfersQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Records per page. Defaults to 20. |
offset | integer | No | Records to skip. Defaults to 0. |
currency | string | No | Filter by currency. Defaults to NGN. |
Example Request
curl -X GET "https://api.uveruspayments.com/api/v1/transfers?limit=20&offset=0" \
-H "Authorization: Bearer sk_live_..."Example Response
{
"data": [
{
"id": "a3f1e291-2b4c-4d5e-9f1a-abc123def456",
"reference": "TRF-SPO-1718901234567",
"amount": 500000,
"currency": "NGN",
"status": "success",
"bankCode": "058",
"bankName": "Guaranty Trust Bank",
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"narration": "Payment for invoice #1042",
"createdAt": "2026-06-20T14:30:00.000Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}Webhook Events
Uverus fires a webhook to your configured URL when a transfer status changes.
{
"event": "transfer.success",
"data": {
"reference": "TRF-SPO-1718901234567",
"amount": 500000,
"currency": "NGN",
"status": "success",
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"bankName": "Guaranty Trust Bank"
}
}See the Webhooks guide for HMAC signature verification.