NGN Payouts
This endpoint allows you to send payouts in NGN to recipients in Nigeria. The request must include the recipient's details, payment method, and a valid quoteId
.
Endpoint
POST: {{baseURL}}/v1/payout
Request Details
Headers
Include these headers in your request:
Header | Value | Required |
---|---|---|
Content-Type | application/json | ✅ Yes |
x-api-key | YOUR_API_KEY | ✅ Yes |
Request Examples
curl --location --request POST '{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"remark": "Testing",
"reason": "Gift",
"quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
"recipient": {
"name": "Adeolu Adebayo",
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG",
"account": {
"bankName": "GT Bank",
"accountNumber": "001040XXXXX",
"bankCode": "058"
}
}
}'
Request Body
The following fields are required when making an NGN payout request:
Field | Type | Description |
---|---|---|
remark | String | Additional note about the transaction. |
reason | String | Purpose of the transfer (e.g., Gift ). |
quoteId | String | Unique Quote ID for the payout. |
recipient.name | String | Full name of the recipient. |
recipient.paymentChannel | String | Payment method (BANK_TRANSFER ). |
recipient.currency | String | ISO currency code (NGN ). |
recipient.country | String | ISO country code (NG ). |
recipient.account.bankName | String | Name of the recipient's bank. |
recipient.account.accountNumber | String | Recipient’s bank account number. |
recipient.account.bankCode | String | The 3-digit bank code (e.g., 058 for GTBank). |
Success Response (200 OK)
If the payout is successfully created, the API returns the following response:
{
"message": "Transaction created successfully",
"status": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"remark": "Testing",
"reason": "Gift",
"referenceNumber": "TXYZD6RWSQMKF",
"type": "SEND",
"state": "COMPLETED",
"quote": {
"id": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
"source": {
"currency": "USD",
"country": "US",
"amount": 100
},
"target": {
"currency": "NGN",
"country": "NG",
"amount": 147000
},
"rate": 1470,
"fee": {
"amount": 500
}
},
"recipient": {
"name": "Adeolu Adebayo",
"firstName": "Adeolu",
"lastName": "Adebayo",
"relationship": "SELF",
"type": "BANK",
"account": {
"accountNumber": "001040XXXXX",
"bankCode": "058"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
},
"created": "2025-08-22T10:55:48.038044",
"processed": "2025-08-22T10:58:49.712685"
}
}
Error Handling
Status Code | Meaning | Example Response |
---|---|---|
400 | Bad Request | Invalid parameters |
401 | Unauthorized | Invalid API key |
422 | Unprocessable Entity | Invalid quote ID |
500 | Internal Server Error | An internal error occurred |
Best Practices
✅ Ensure quoteId
is valid and linked to an existing quote.
✅ Confirm that the recipient’s bank account number and bank code are correct.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.