Wallet Guide

This guide explains how to manage your wallets.

Fetch Wallets

Here's the endpoints to fetch a list of wallets

GET {BASE_URL}/api/v1/merchants/{merchantId}/wallets

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "xxx-xxx-xxx",
      "currency": "NGN",
      "status": "ACTIVE",
      "availableBalance": 50000000.00,
      "lienAmount": 0.00,
      "entityType": "BUSINESS",
      "entityId": "xxx-xxx-xxx",
      "purpose": "ALL",
      "maxSinglePayout": 1000000.00,
      "minSinglePayout": 500.00,
      "maxDailyPayout": 5000000.00,
      "businessName": "Test Business",
      "merchantName": "Test Merchant",
      "walletName": "Test Business",
      "createdDate": "2025-01-01 01:01:01",
      "lastUpdatedDate": "2025-01-01 01:01:01",
      "aggregatorWallet": false,
      "payoutAllowed": true,
      "active": true
    },
    {
      "id": "xxx-xxx-xxx",
      "currency": "KES",
      "status": "ACTIVE",
      "availableBalance": 1000000.00,
      "lienAmount": 0.00,
      "entityType": "BUSINESS",
      "entityId": "xxx-xxx-xxx",
      "purpose": "ALL",
      "maxSinglePayout": 10000.00,
      "minSinglePayout": 50.00,
      "maxDailyPayout": 100000.00,
      "businessName": "Test Business",
      "merchantName": "Test Merchant",
      "walletName": "Test Business",
      "createdDate": "2025-01-01 01:01:01",
      "lastUpdatedDate": "2025-01-01 01:01:01",
      "aggregatorWallet": false,
      "payoutAllowed": true,
      "active": true
    }
  ]
}

Wallet to Wallet Transfer

You can use the Wallet to Wallet transfer feature to transfer funds between business wallets.

Request

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

Required Parameters

Parameter	Type	Description
amount	double	Transfer amount
senderBusinessId	string	The Business ID of the Sending Wallet
beneficiaryBusinessId	string	The Business ID of the Receiving Wallet
reference	string	Unique reference from merchant
countryCode	string	Country code
currency	string	Currency code
narration	string	Transfer description

Optional Parameters

Parameter	Type	Description
walletId	string (UUID)	ID of the sender's wallet to debit. Required when the sender business has multiple wallets of the same currency; if omitted, the first matching wallet is used.
beneficiaryWalletId	string (UUID)	ID of the beneficiary's wallet to credit. Required when the beneficiary business has multiple wallets of the same currency; if omitted, the wallet matching the sender's gateway is preferred, falling back to the first available wallet of that currency. Required (and must be a sub-wallet's walletId) when isBeneficiaryBusinessIssuedWallet is true.
isBeneficiaryBusinessIssuedWallet	boolean	Set to true to fund one of your own sub-wallets instead of transferring to another business. When true, beneficiaryBusinessId must be the same as senderBusinessId (the opposite of the default rule below), and beneficiaryWalletId must be the sub-wallet's walletId. Defaults to false.

Funding a sub-wallet vs. transferring to another business: by default, senderBusinessId and beneficiaryBusinessId must be different businesses. The one exception is funding your own sub-wallet (isBeneficiaryBusinessIssuedWallet=true), where they must be the same business — you're moving funds from your main wallet into one of your own sub-wallets, not to a different business.

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/wallet-transfer
• Method: POST
• Request Body:

  {
    "reference": "{unique_reference}",
    "amount": 5000.00,
    "senderBusinessId": "{sender_business_id}",
    "beneficiaryBusinessId": "{beneficiary_business_id}",
    "countryCode": "NG",
    "currency": "NGN",
    "narration": "Fund Transfer to Other Business",
    "walletId": "{sender_wallet_id}",
    "beneficiaryWalletId": "{beneficiary_wallet_id}"
  }
  

• Response Body:

  {
    "paymentStatus": "SUCCESSFUL",
    "currency": "NGN",
    "amount": 5000.00,
    "fee": 0.00,
    "onusReference": "ONUS-WTRNF-xxx-xxx-xxx",
    "merchantReference": "BUS-TRNF-001"
  }
  

Funding Your Own Sub-Wallet

To top up a sub-wallet you've created, set isBeneficiaryBusinessIssuedWallet to true, use your own business ID for both senderBusinessId and beneficiaryBusinessId, and set beneficiaryWalletId to the sub-wallet's walletId (returned when you created it).

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

  {
    "reference": "{unique_reference}",
    "amount": 5000.00,
    "senderBusinessId": "{your_business_id}",
    "beneficiaryBusinessId": "{your_business_id}",
    "countryCode": "NG",
    "currency": "NGN",
    "narration": "Payroll wallet top-up",
    "beneficiaryWalletId": "{sub_wallet_id}",
    "isBeneficiaryBusinessIssuedWallet": true
  }
  

• Response Body:

  {
    "paymentStatus": "SUCCESSFUL",
    "currency": "NGN",
    "amount": 5000.00,
    "fee": 0.00,
    "onusReference": "ONUS-WTRNF-xxx-xxx-xxx",
    "merchantReference": "{unique_reference}"
  }
  

Fetch Wallet Transactions

Here's the endpoints to fetch a list of wallet transactions for business

GET {BASE_URL}/api/v1/merchants/{merchantId}/wallet-transactions?businessId={businessId}

Required Parameters: - merchantId: The Merchant's ID - businessId: The ID of any business attached to the Merchant

Optional Query Parameters: - pageNo: Page Number (Default: 1) - pageSize: Page Size (Default: 30) - createdFrom: Start Date (e.g 2025-01-31) - createdTo: Start Date (e.g 2025-06-15) - pageSize: Page Size (Default: 30) - transactionType: Transaction Type (CREDIT, DEBIT, LIEN, REVERSAL, UNLIEN) - currency: Currency (e.g NGN, KES, USD, etc) - onusReference: ONUS Reference of the wallet transaction - product: Specific Product (PAYIN, PAYOUT, WALLET_FUNDING)

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "pageNo": 1,
    "pageSize": 10,
    "lastPage": 1,
    "totalNumberOfItems": 2,
    "content": [
        {
            "businessName": "Test Business",
            "merchantName": "Test Merchant",
            "businessId": null,
            "id": "xxx-xxx-xxx",
            "walletId": null,
            "product": "PAYIN",
            "currency": "NGN",
            "channel": "WALLET_TRANSFER",
            "transactionType": "CREDIT",
            "transactionStatus": "SUCCESSFUL",
            "amount": 9.90,
            "referenceId": "xxx-xxx-xxx",
            "onusReference": "ONUS-STTL-xxx-xxx-xxx",
            "narration": "Business Settlement",
            "primaryTransactionId": null,
            "walletName": null,
            "entityId": "xxx-xxx-xxx",
            "entityType": "BUSINESS",
            "createdDate": "2025-09-29 01:18:00",
            "lastUpdatedDate": "2025-09-29 01:18:00",
            "reversal": false,
            "fee": false
        },
        {
            "businessName": "Test Business",
            "merchantName": "Test Merchant",
            "businessId": null,
            "id": "xxx-xxx-xxx",
            "walletId": null,
            "product": "PAYOUT",
            "currency": "NGN",
            "channel": "BANK_TRANSFER",
            "transactionType": "DEBIT",
            "transactionStatus": "SUCCESSFUL",
            "amount": 5.00,
            "referenceId": "xxx-xxx-xxx",
            "onusReference": "ONUS-TRNF-xxx-xxx-xxx",
            "narration": "Name Identification",
            "primaryTransactionId": null,
            "walletName": null,
            "entityId": "xxx-xxx-xxx",
            "entityType": "BUSINESS",
            "createdDate": "2025-09-25 14:09:27",
            "lastUpdatedDate": "2025-09-25 14:09:27",
            "reversal": false,
            "fee": true
        }
    ]
  }
}