Payouts
Payout API Documentation
Payout Channels
The following payout channels are available:
BANK_TRANSFER
: Standard bank transferPUSH_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
istrue
, the API will perform both lookup and payout in one call. - If
singleCall
isfalse
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
}
Updated about 1 month ago