Transfers API

Programmatically send money from your Transfer wallet to any Nigerian bank account. The typical flow:

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

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer sk_test_...` (test) or `Bearer sk_live_...` (live) — see Authentication

Payout-initiating endpoints below additionally require the OWNER or ADMIN role.

Important

Every payout-initiating endpoint on this page — Initiate a Transfer and Settlement Payout — is disabled in test mode and returns a 403. There's no sandboxed simulation for outbound money movement; use a live key (sk_live_...), which also requires KYB verification on your account.

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-account

Note

Rate limited to 20 requests/minute, tighter than the default.

Request Body

Field	Type	Required	Description
`accountNumber`	string	Yes	10-digit bank account number
`bankCode`	string	Yes	Bank code from the bank 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. Returns the same object as activate, or null if not yet activated.

GET /api/v1/transfers/funding-account

Example Request

curl -X GET "https://api.uveruspayments.com/api/v1/transfers/funding-account" \
     -H "Authorization: Bearer sk_live_..."

Initiate a Transfer

Send funds from your Transfer wallet to any Nigerian bank account.

Important

Amounts are in kobo — the lowest denomination. 500000 kobo = ₦5,000. Minimum transfer is 100 kobo (₦1). Live mode and KYB verification required — see the note above.

POST /api/v1/transfers

Note

Requires OWNER or ADMIN role. Rate limited to 10 requests/minute.

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 the bank list
`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-A1B2C3D4E5F6G7H8",
  "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

Settlement Payout

Pay out from your Settlement wallet — the balance built up from completed checkout payments — to one of your registered payout accounts. This is a separate flow from Initiate a Transfer above, which sends from the Transfer wallet to any bank account.

Register a payout account first from Settings → Payout Accounts in the dashboard; this API only pays out to accounts already on file, identified by payoutAccountId.

POST /api/v1/transfers/settlement-payout

Note

Requires OWNER or ADMIN role, live mode, and KYB verification. Rate limited to 5 requests/minute.

Request Body

Field	Type	Required	Description
`payoutAccountId`	string	Yes	ID of a payout account registered on your account
`amount`	integer	Yes	Amount in kobo. Min: `100`. Must not exceed your Settlement balance.

Example Request

curl -X POST "https://api.uveruspayments.com/api/v1/transfers/settlement-payout" \
     -H "Authorization: Bearer sk_live_..." \
     -H "Content-Type: application/json" \
     -d '{
       "payoutAccountId": "uuid",
       "amount": 2000000
     }'

Example Response

{
  "reference": "SPO-A1B2C3D4E5F6G7H8",
  "status": "processing",
  "amount": 2000000
}

The resulting payout also shows up via Get Transfer by Reference and List Transfers below, using the same SPO- prefixed reference.

Get Transfer by Reference

Retrieve the current status and details of a specific transfer or settlement payout. Returns the same object as Initiate a Transfer.

GET /api/v1/transfers/{reference}

Example Request

curl -X GET "https://api.uveruspayments.com/api/v1/transfers/TRF-A1B2C3D4E5F6G7H8" \
     -H "Authorization: Bearer sk_live_..."

List Transfers

Returns a paginated list of outbound transfers, including settlement payouts — see Pagination.

GET /api/v1/transfers

Query 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

{
  "transfers": [
    {
      "id": "a3f1e291-2b4c-4d5e-9f1a-abc123def456",
      "reference": "TRF-A1B2C3D4E5F6G7H8",
      "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
}

Webhook Events

Uverus fires a webhook to your configured URL when a transfer or settlement payout settles:

transfer.success — funds were delivered to the recipient
transfer.failed — the transfer failed; funds were returned to your wallet

{
  "event": "transfer.success",
  "data": {
    "reference": "TRF-A1B2C3D4E5F6G7H8",
    "amount": 500000,
    "currency": "NGN",
    "status": "success",
    "accountNumber": "0123456789",
    "accountName": "JOHN DOE",
    "bankName": "Guaranty Trust Bank"
  },
  "timestamp": "2026-06-20T14:30:05.000Z",
  "webhookId": "uuid"
}

See the Webhooks guide for the full envelope shape and HMAC signature verification.

Transfers API

On this page