​
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:
HeaderValueRequired
Content-Typeapplication/json✅ Yes
x-api-keyYOUR_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

FieldTypeDescriptionRequired
recipientObjectDetails of the payout recipient✅ Yes
recipient.idStringUnique identifier for the recipientOptional
recipient.nameStringFull name of the recipient✅ Yes
recipient.firstNameStringFirst name of the recipient✅ Yes
recipient.lastNameStringLast name of the recipient✅ Yes
recipient.typeStringRecipient type (PERSON or BUSINESS)✅ Yes
recipient.accountObjectRecipient’s bank account details✅ Yes
account.bankNameStringRecipient’s bank name✅ Yes
account.accountNumberStringBank account number of the recipient✅ Yes
account.sortCodeStringSort code of the recipient’s bank✅ Yes
recipient.paymentChannelStringPayment method (BANK_TRANSFER)✅ Yes
recipient.currencyStringCurrency code (e.g., GBP)✅ Yes
recipient.countryStringCountry code (e.g., GB)✅ Yes
recipient.storedBooleanWhether recipient info is stored for future use✅ Yes
quoteIdStringUnique Quote ID for the payout✅ Yes
reasonStringReason 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

FieldTypeDescriptionExample
messageStringStatus message of the payout creation"Transaction created successfully"
statusStringStatus of the payout"success"
dataObjectDetails of the payout transaction
data.idStringUnique ID of the transaction"b8c7d6e5-f4a3-210f-fedc-xxxxxxxxxxxxx"
data.reasonStringReason for the payout"Family Support"
data.referenceNumberStringUnique reference number for the payout"GBPTO210KXYZ"
data.typeStringType of transaction"SEND"
data.stateStringState of the payout (PENDING, COMPLETED, etc.)"PENDING"
data.quoteObjectDetails of the quote
data.quote.idStringQuote ID"7a2f1c8e-3b12-4a9a-8cde-XX"
data.quote.sourceObjectSource currency details
data.quote.source.currencyStringSource currency code"GBP"
data.quote.source.countryStringSource country code"GB"
data.quote.source.amountNumberAmount sent in source currency100
data.quote.targetObjectTarget currency details
data.quote.target.currencyStringTarget currency code"NGN"
data.quote.target.countryStringTarget country code"NG"
data.quote.target.amountNumberAmount received in target currency212800
data.quote.rateNumberExchange rate used2128
data.quote.feeObjectFee details
data.quote.fee.amountNumberFee amount in source currency1500
data.recipientObjectRecipient details
data.recipient.nameStringRecipient’s full name"Chidinma Okafor"
data.recipient.firstNameStringRecipient’s first name"Chidinma"
data.recipient.lastNameStringRecipient’s last name"Okafor"
data.recipient.relationshipStringRelationship with the recipient"SELF"
data.recipient.typeStringRecipient type (BANK)"BANK"
data.recipient.accountObjectBank account details
data.recipient.account.accountNumberStringBank account number"1234567890"
data.recipient.account.sortCodeStringSort code of the recipient’s bank"089002"
data.recipient.account.bankNameStringBank name of the recipient"Zenith Bank"
data.recipient.paymentChannelStringPayment method (BANK_TRANSFER)"BANK_TRANSFER"
data.recipient.currencyStringCurrency code of payout"NGN"
data.recipient.countryStringCountry code of the recipient"NG"
data.createdStringTimestamp when the transaction was created"2025-06-11T10:15:30.000000"
data.processedStringTimestamp 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:
StateDescription
COMPLETEDThe payout was successfully processed.
PENDINGThe payout is still being processed.
FAILEDThe payout failed to process.
REFUNDEDThe payout has been sent back to sender.

​
Error Handling

Status CodeMeaningExample Response
400Bad RequestInvalid parameters
401UnauthorizedInvalid API key
422Unprocessable EntityInvalid quote ID
500Internal Server ErrorAn 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.