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

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
}