Create a GBP Payout Example
The Payout API allows users to process payouts in Pounds (GBP) to recipients via Bank Transfer.
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 |
Sample cURL Request
curl --location --request POST '{{baseURL}}//v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--form '{
"recipient":{
"name":"Chidinma Okafor",
"type":"BUSINESS", //or PERSON
"account":{
"bankName":"Mock Bank",
"sortCode":"2222",
"accountNumber":"11111111"
},
"paymentChannel":"BANK_TRANSFER",
"currency":"GBP",
"country":"GB"
},
"quoteId":"19e31fc3-71a4-4dde-875f-xxxxxxxxxxxxx",
"reason":"Family Support"
}Request Body Breakdown
| Field | Type | Description | Required |
|---|---|---|---|
recipient | Object | Details of the payout recipient | ✅ Yes |
recipient.id | String | Unique identifier for the recipient | Optional |
recipient.name | String | Full name of the recipient | ✅ Yes |
recipient.firstName | String | First name of the recipient | ✅ Yes |
recipient.lastName | String | Last name of the recipient | ✅ Yes |
recipient.type | String | Recipient type (PERSON or BUSINESS) | ✅ Yes |
recipient.account | Object | Recipient’s bank account details | ✅ Yes |
account.bankName | String | Recipient’s bank name | ✅ Yes |
account.accountNumber | String | Bank account number of the recipient | ✅ Yes |
account.sortCode | String | Sort code of the recipient's bank | ✅ Yes |
recipient.paymentChannel | String | Payment method (BANK_TRANSFER) | ✅ Yes |
recipient.currency | String | Currency code (e.g., GBP) | ✅ Yes |
recipient.country | String | Country code (e.g., GB) | ✅ Yes |
recipient.stored | Boolean | Whether recipient info is stored for future use | ✅ Yes |
quoteId | String | Unique Quote ID for the payout | ✅ Yes |
reason | String | Reason for the payout (e.g., Gift, Invoice Payment) | ✅ Yes |
Success Response (200 OK)
If the payout is successfully created, the API returns the following response:
{
"message": "Transaction created successfully",
"status": "success",
"data": {
"id": "b8c7d6e5-f4a3-210f-fedc-xxxxxxxxxxxxx",
"remark": "Family Support",
"reason": "Family Support",
"referenceNumber": "GBPTO21XXXXX",
"type": "SEND",
"state": "COMPLETED",
"quote": {
"id": "7a2f1c8e-3b12-4a9a-8cde-xxxxxxxxxxxxx",
"source": {
"currency": "GBP",
"country": "GB",
"amount": 100
},
"target": {
"currency": "NGN",
"country": "NG",
"amount": 212800
},
"rate": 2128,
"fee": {
"amount": 1500
}
},
"recipient": {
"name": "Chidinma Okafor",
"firstName": "Chidinma",
"lastName": "Okafor",
"type": "BANK",
"account": {
"accountNumber": "111111111",
"sortCode": "2222",
"bankName": "Mock Bank"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "GBP",
"country": "GB"
},
"created": "2025-06-11T10:15:30.000000",
"processed": "2025-06-11T10:15:30.000000'
}
}
Response Breakdown
| Field | Type | Description | Example |
|---|---|---|---|
message | String | Status message of the payout creation | "Transaction created successfully" |
status | String | Status of the payout | "success" |
data | Object | Details of the payout transaction | |
data.id | String | Unique ID of the transaction | "b8c7d6e5-f4a3-210f-fedc-xxxxxxxxxxxxx" |
data.reason | String | Reason for the payout | "Family Support" |
data.referenceNumber | String | Unique reference number for the payout | "GBPTO210KXYZ" |
data.type | String | Type of transaction | "SEND" |
data.state | String | State of the payout (PENDING, COMPLETED, etc.) | "PENDING" |
data.quote | Object | Details of the quote | |
data.quote.id | String | Quote ID | "7a2f1c8e-3b12-4a9a-8cde-XX" |
data.quote.source | Object | Source currency details | |
data.quote.source.currency | String | Source currency code | "GBP" |
data.quote.source.country | String | Source country code | "GB" |
data.quote.source.amount | Number | Amount sent in source currency | 100 |
data.quote.target | Object | Target currency details | |
data.quote.target.currency | String | Target currency code | "NGN" |
data.quote.target.country | String | Target country code | "NG" |
data.quote.target.amount | Number | Amount received in target currency | 212800 |
data.quote.rate | Number | Exchange rate used | 2128 |
data.quote.fee | Object | Fee details | |
data.quote.fee.amount | Number | Fee amount in source currency | 1500 |
data.recipient | Object | Recipient details | |
data.recipient.name | String | Recipient’s full name | "Chidinma Okafor" |
data.recipient.firstName | String | Recipient’s first name | "Chidinma" |
data.recipient.lastName | String | Recipient’s last name | "Okafor" |
data.recipient.relationship | String | Relationship with the recipient | "SELF" |
data.recipient.type | String | Recipient type (BANK) | "BANK" |
data.recipient.account | Object | Bank account details | |
data.recipient.account.accountNumber | String | Bank account number | "1234567890" |
data.recipient.account.sortCode | String | Sort code of the recipient’s bank | "089002" |
data.recipient.account.bankName | String | Bank name of the recipient | "Zenith Bank" |
data.recipient.paymentChannel | String | Payment method (BANK_TRANSFER) | "BANK_TRANSFER" |
data.recipient.currency | String | Currency code of payout | "NGN" |
data.recipient.country | String | Country code of the recipient | "NG" |
data.created | String | Timestamp when the transaction was created | "2025-06-11T10:15:30.000000" |
data.processed | String | Timestamp when the payout was processed or null | "2025-06-11T10:15:40.000000" |
Payout Transaction States
The payout transaction can have one of the following states:
| State | Description |
|---|---|
COMPLETED | The payout was successfully processed. |
PENDING | The payout is still being processed. |
FAILED | The payout failed to process. |
REFUNDED | The payout has been sent back to sender. |
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.