Bank Transfer Payouts Guide

This guide explains how to implement bank transfer payouts using our API. The process involves two main steps: 1. Fetch List of Banks 2. Name Enquiry - Verify bank account details 3. Initiate Bank Transfer - Process the actual transfer

Fetch Bank Lists

Here's the endpoints to fetch a list of banks

GET {BASE_URL}/api/v1/banks

Sample Response

{
  "status": "200",
  "message": "Successful",
  "data": [
    "000014": "ACCESS BANK",
    "000013": "GTBANK PLC",
    "000023": "PROVIDUS BANK",
    ...
  ]
}

Name Enquiry

Before initiating a bank transfer, you need to verify the recipient's bank account details using the Name Enquiry endpoint.

Request

POST {BASE_URL}/api/v1/transfer-requests/name-enquiry

Required Parameters

Parameter	Type	Description
institutionCode	string	Bank institution code
accountNumber	string	Beneficiary account number
businessId	string	Your business ID
currency	string	Currency (NGN, ZAR, defaults to NGN if not provided)
### Response
The API will return the following information:

Field	Type	Description
accountName	string	Name of the account holder
accountNumber	string	Verified account number
bankCode	string	Bank code
bankName	string	Name of the bank

Sample Response

{
  "status": "200",
  "message": "Successful",
  "data": {
    {
        "accountNumber": "0123456789",
        "accountName": "John Doe",
        "bankCode": "044",
        "bankName": "Access Bank"
    }
}

Initiate Bank Transfer

After verifying the account details, you can proceed with initiating the bank transfer.

Request

POST {BASE_URL}/api/v1/transfer-requests/bank-transfer

Required Parameters

Parameter	Type	Description
amount	double	Transfer amount
beneficiaryAccountNumber	string	Recipient's account number
beneficiaryAccountName	string	Recipient's account name
beneficiaryBankCode	string	Bank code (same as institutionCode from name enquiry)
reference	string	Unique reference from merchant
transferType	string	Type of transfer (WALLET_TO_WALLET, WALLET_TO_BANK_ACCOUNT, WALLET_TO_MOMO or WALLET_TO_EFT)
countryCode	string	Country code
currency	string	Currency code
email	string	Email address
businessId	string	Your business ID
#### Optional Parameters

Parameter	Type	Description
walletId	string (UUID)	ID of the wallet to debit. Required when the business has multiple wallets of the same currency, or whenever fromSubWallet is true; if omitted otherwise, the first wallet matching the requested currency is used.
fromSubWallet	boolean	Set to true to debit one of your own sub-wallets instead of your main business wallet. When true, walletId is required and must be the sub-wallet's walletId, and its currency must match the currency of this request. Defaults to false.
narration	string	Transfer description
### Response
The API will return the following information:

Field	Type	Description
paymentStatus	string	Status of the transfer (PENDING, PROCESSING, SUCCESSFUL, FAILED, or REJECTED)
currency	string	Currency of the transfer
amount	double	Transfer amount
fee	string	Transfer fee
onusReference	string	System-generated reference
merchantReference	string	Your original reference

• Path: /api/v1/transfer-requests/bank-transfer
• Method: POST
• Request Body:

  {
    "reference": "unique_reference_123",
    "amount": 5000.00,
    "beneficiaryAccountNumber": "0123456789",
    "beneficiaryAccountName": "John Doe",
    "beneficiaryBankCode": "044",
    "transferType": "WALLET_TO_BANK_ACCOUNT",
    "countryCode": "NG",
    "currency": "NGN",
    "businessId": "your_business_id",
    "walletId": "wallet_uuid",
    "email": "customer@example.com",
    "notificationUrl": "https://your-webhook-url.com/callback"
  }
  

• Response Body:

  {
    "paymentStatus": "PENDING",
    "currency": "NGN",
    "amount": 5000.00,
    "fee": 25.00,
    "onusReference": "POUT12345678",
    "merchantReference": "unique_reference_123"
  }
  

Paying Out From a Sub-Wallet

To pay a beneficiary directly from a sub-wallet's balance instead of your main business wallet, set fromSubWallet to true and walletId to the sub-wallet's walletId.

• Path: /api/v1/transfer-requests/bank-transfer
• Method: POST
• Request Body:

  {
    "reference": "unique_reference_124",
    "amount": 5000.00,
    "beneficiaryAccountNumber": "0123456789",
    "beneficiaryAccountName": "John Doe",
    "beneficiaryBankCode": "044",
    "transferType": "WALLET_TO_BANK_ACCOUNT",
    "countryCode": "NG",
    "currency": "NGN",
    "businessId": "your_business_id",
    "walletId": "sub_wallet_id",
    "fromSubWallet": true,
    "email": "customer@example.com"
  }
  

• Response Body:

  {
    "paymentStatus": "PENDING",
    "currency": "NGN",
    "amount": 5000.00,
    "fee": 25.00,
    "onusReference": "POUT12345679",
    "merchantReference": "unique_reference_124"
  }
  

Initiate Mobile Money Payout (Wallet to MoMo)

• Path: /api/v1/transfer-requests/bank-transfer
• Method: POST
• Request Body:

  {
    "beneficiaryAccountNumber":  "+2250505000001",
    "countryCode": "CI",
    "currency": "XOF",
    "beneficiaryAccountName": "Olamide Smith",
    "momoNetwork": "MTN_COTE_DIVOIRE",
    "transferType": "WALLET_TO_MOMO",
    "amount": "150",
    "businessId": "{{businessId}}",
    "reference": "{{unique_reference}}",
    "narration": "Mobile Money Payout to Olamide",
    "notificationUrl": "https://optional.notification.url"
  }
  

• Response Body:

  {
    "status": 200,
    "message": "Success",
    "data": {
      "paymentStatus": "PENDING",
      "currency": "XOF",
      "amount": 150,
      "fee": 10,
      "onusReference": "{{onusRef}}",
      "merchantReference": "{{merchantRef}}"
    }
  }
  

Fetch List of MoMo Networks

• Path: /api/v1/mobile-money/networks
• Method: GET
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer {merchant_api_bearer_token}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "VODAFONE_GHANA": {
        "currency": "GHS",
        "countryCode": "GH"
      }
    },
    {
      "MPESA_KENYA": {
        "currency": "KES",
        "countryCode": "KE"
      }
    },
    {
      "ORANGE_COTE_DIVOIRE": {
        "currency": "XOF",
        "countryCode": "CI"
      }
    }
    ...
  ]
}

Initiate EFT (ZAR) Payout (Wallet to EFT)

• Path: /api/v1/transfer-requests/bank-transfer
• Method: POST
• Request Body:

  {
    "beneficiaryAccountNumber": "9876543210",
    "countryCode": "ZA",
    "currency": "ZAR",
    "beneficiaryAccountName": "Olamide Smith",
    "eftBank": "AFRICAN_BANK",
    "transferType": "WALLET_TO_EFT",
    "amount": "150",
    "businessId": "{{businessId}}",
    "reference": "{{unique_reference}}",
    "narration": "EFT Payout to Olamide",
    "notificationUrl": "https://optional.notification.url"
  }
  

• Response Body:

  {
    "status": 200,
    "message": "Success",
    "data": {
      "paymentStatus": "PENDING",
      "currency": "ZAR",
      "amount": 150,
      "fee": 10,
      "onusReference": "{{onusRef}}",
      "merchantReference": "{{merchantRef}}"
    }
  }
  

Fetch List of EFT Banks

• Path: /api/v1/banks?key=ZAR
• Method: GET
• Headers:
• Content-Type: application/json
• Authorization: Bearer {merchant_api_bearer_token}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "ABSA": "ABSA",
    "AFRICAN_BANK": "African Bank",
    "ALBARAKA_BANK": "Albaraka Bank",
    "BANK_ZERO": "Bank Zero",
    "BIDVEST_BANK": "Bidvest Bank",
    "CAPITEC_BANK": "Capitec Bank",
    "CITIBANK": "CitiBank",
    "DISCOVERY_BANK": "Discovery Bank",
    "FNB": "FNB",
    "HSBC_BANK": "HSBC Bank",
    "INVESTEC": "Investec",
    "NEDBANK": "Nedbank",
    "RMB": "RMB",
    "SASFIN_BANK": "Sasfin Bank",
    "STANDARD_BANK": "Standard Bank",
    "STANDARD_CHARTERED_BANK": "Standard Chartered Bank",
    "TYMEBANK": "Tymebank",
    "UBANK": "Ubank Limited"
  }
}

Fetch List of Transfer Requests

You can retrieve a list of all your transfer requests with optional filtering.

Request

GET {BASE_URL}/api/v1/transfer-requests?merchantId={merchantId}

Query Parameters

Parameter	Type	Description
merchantId	string	Required
id	string	Filter by transfer ID
status	string	Filter by status (PROCESSING, SUCCESSFUL or FAILED)
onusReference	string	Filter by system-generated reference
accountNumber	string	Filter by account number
merchantReference	string	Filter by your original reference
businessIds	string (array)	Filter by business IDs
channel	string	Filter by payment channel (CARD, BANK_TRANSFER, WALLET_TRANSFER, MOBILE_MONEY, EFT)
transferType	string	Filter by transfer type (WALLET_TO_BANK_ACCOUNT, WALLET_TO_WALLET, WALLET_TO_MOMO)
currency	string	Filter by currency
reversed	boolean	Filter by reversed status
refund	boolean	Filter by refund status
createdFrom	datetime	Filter by creation date (format: YYYY-MM-DD)
createdTo	datetime	Filter by creation date (format: YYYY-MM-DD)

Response

The API will return a paginated list of transfer requests with the following information:

Field	Type	Description
pageNo	number	Current page number
pageSize	number	Number of items per page
lastPage	number	Last page number
totalNumberOfItems	number	Total number of items
content	array	Array of transfer request objects

Transfer Request Object

Field	Type	Description
id	string	Transfer ID
businessId	string	Business ID
merchantUserId	string	Merchant user ID
amount	double	Transfer amount
fee	double	Transfer fee
paymentChannel	string	Payment channel
currency	string	Currency
countryCode	string	Country code
beneficiaryAccountNumber	string	Recipient's account number
beneficiaryAccountName	string	Recipient's account name
walletId	string	Wallet ID
beneficiaryWalletId	string	Recipient's wallet ID (for wallet-to-wallet transfers)
bankCode	string	Bank code
bankName	string	Bank name
onusReference	string	System-generated reference
reference	string	Your original reference
paymentStatus	string	Status of the transfer
transferType	string	Type of transfer
narration	string	Transfer description
createdDate	datetime	Date and time of creation
lastUpdatedDate	datetime	Date and time of last update

Testing On Sandbox Environment

Use these account numbers when testing on Sandbox:

Account Number	Status
9999991112	SUCCESSFUL
9999991114	FAILED
9999991111	PROCESSING

Fund NGN Account

(only applicable on sandbox for NGN payout accounts)

• Path: /api/v1/fund-ngn-account
• Method: POST
• Request Body:
• accountNumber: string (required)
• amount: double (required)
• Response Body:
• message: string

Bulk Transfers

See Bulk Transfers

Prerequisites

Before initiating any payout, ensure the following are configured on the Merchant Dashboard for the active environment:

1. IP Whitelisting: Your server's IP address(es) must be whitelisted. Navigate to Settings → IP Whitelist on the dashboard and add the outbound IP(s) of your server. Payout requests from non-whitelisted IPs will be rejected.
2. Sufficient wallet balance: Confirm your wallet has enough funds before initiating a transfer. Use the Fetch Wallets endpoint to check available balances.

Important Notes

1. Always perform Name Enquiry before initiating a transfer to ensure the account details are valid
2. Store both the merchantReference and onusReference for reconciliation purposes
3. The transferType should be set to WALLET_TO_BANK_ACCOUNT for bank transfers
4. Ensure all amounts are in the correct currency format
5. Use the Fetch List of Transfer Requests endpoint to monitor the status of your transfers