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
}