Overview

Our Payouts Service streamlines the process for businesses to send money directly to customers’ bank accounts or mobile money wallets. Designed for high reliability, the service maximizes the likelihood of a successful payout by operating from a prefunded wallet. The payout flow consists of two main steps:

Lookup: This initial step verifies the recipient’s details to ensure accurate and secure transactions.

Payout Call: Once the lookup is complete, the payout request is queued and processed asynchronously. The system intelligently selects the optimal provider from our network to fulfill the transaction efficiently.

Getting Integration Credentials

To call our payouts service, you need to get your Client Id and Client Secret from the business portal. You can find the guide here Getting Integration Credentials.

You can create your wallet on the business portal and pick the wallet ID from there under the wallets menu.

Funding your Wallet

You can fund your wallet position via bank transfer from any of your banking apps. The bank details to transfer into the wallet are visible on your wallet dtails page.

Payout Status

We currently have 3 main statuses:

Payout API Documentation

Payout Channels

The following payout channels are available:

• BANK_TRANSFER: Standard bank transfer
• PUSH_TO_CARD: Transfer Directly to customer's card

You can view the individual nuances for the different payout channels here

Create Payout Transaction

Creates a new payout transaction. This endpoint can perform both lookup and payout in a single call if singleCall is set to true.

Endpoint: POST /api/v1/payouts

Request

{
  "transactionReference": "PAYOUT-123456",
  "payoutChannel": "BANK_TRANSFER",
  "amount": 1000.00,
  "currencyCode": "NGN",
  "narration": "Salary payment",
  "recipient": {
    "recipientBank": "044",
    "recipientName": "John Doe",
    "recipientAccount": "1234567890"
  },
  "walletDetails": {
    "walletId": "WALLET-001",
    "pin": "1234"
  },
  "singleCall": true
}

Note:

• payoutChannel should be one of the available Payout Channels listed above.
• If singleCall is true, the API will perform both lookup and payout in one call.
• If singleCall is false or not provided, you must first make a separate lookup call before calling this endpoint.

Response

{
  "id": "123456",
  "reference": "REF-123456",
  "transactionReference": "PAYOUT-123456",
  "amount": 1000.00,
  "fee": 10.00,
  "currencyCode": "NGN",
  "channel": "BANK_TRANSFER",
  "status": "PROCESSING",
  "narration": "Salary payment",
  "clientId": "MERCHANT-001",
  "recipientAccount": "1234567890",
  "recipientBank": "044",
  "recipientName": "John Doe",
  "sourceAccount": "WALLET-001",
  "responseCode": "00",
  "responseDescription": "Transaction in progress",
  "processingReference": "PROC-123456",
  "walletDebit": true,
  "retryCount": 0
}

Customer Lookup

Looks up customer information for a payout. This step is required before calling the payout endpoint if singleCall is set to false or not provided in the payout request.

Endpoint: POST /api/v1/payouts/customer-lookup

Request

{
  "transactionReference": "LOOKUP-123456",
  "payoutChannel": "BANK_TRANSFER",
  "recipient": {
    "currencyCode": "NGN",
    "amount": 1000.00,
    "recipientBank": "044",
    "recipientName": "John Doe",
    "recipientAccount": "1234567890"
  }
}

Note: payoutChannel should be one of the available Payout Channels listed above.

Response

{
  "reference": "REF-123456",
  "transactionReference": "LOOKUP-123456",
  "currencyCode": "NGN",
  "amount": 1000.00,
  "recipientBank": "044",
  "recipientName": "John Doe",
  "recipientAccount": "1234567890"
}

Get Payout Transaction

Retrieves a payout transaction by its reference.

Endpoint: GET /api/v1/payouts/{transactionReference}

Response

{
  "id": "123456",
  "reference": "REF-123456",
  "transactionReference": "PAYOUT-123456",
  "amount": 1000.00,
  "fee": 10.00,
  "currencyCode": "NGN",
  "channel": "BANK_TRANSFER",
  "status": "SUCCESSFUL",
  "narration": "Salary payment",
  "clientId": "MERCHANT-001",
  "recipientAccount": "1234567890",
  "recipientBank": "044",
  "recipientName": "John Doe",
  "sourceAccount": "WALLET-001",
  "responseCode": "00",
  "responseDescription": "Transaction successful",
  "processingReference": "PROC-123456",
  "walletDebit": true,
  "retryCount": 0
}