​
Create a USD Payout Example

The Payout API allows users to process payouts in US Dollars (USD) to recipients in the United States 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 Request

    ​
    Request Body Breakdown

    FieldTypeDescriptionRequired
    recipientObjectDetails of the payout recipientYes
    recipient.idStringUnique identifier for the recipientOptional
    recipient.nameStringFull name of the recipientYes
    recipient.firstNameStringFirst name of the recipientYes
    recipient.lastNameStringLast name of the recipientYes
    recipient.typeStringRecipient type (INDIVIDUAL or BUSINESS)Yes
    recipient.accountObjectRecipient’s bank account detailsYes
    account.accountNumberStringBank account number of the recipientYes
    account.sortCodeStringSort code of the recipient’s bankYes
    account.routingNumberStringRouting number for the recipient’s bankYes
    recipient.paymentChannelStringPayment method (BANK_TRANSFER)Yes
    recipient.currencyStringCurrency code (e.g., USD)Yes
    recipient.countryStringCountry code (e.g., US)Yes
    recipient.storedBooleanWhether recipient info is stored for future useYes
    quoteIdStringUnique Quote ID for the payoutYes
    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": "a1b2c3d4-e5f6-7890-abcd-xxxxxxxxxxxxx",
    "reason": "Gift",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 160000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 100
      },
      "rate": 1600,
      "fee": {
        "amount": 500
      }
    },
    "recipient": {
      "name": "Adeolu Adebayo",
      "type": "BANK",
      "account": {
        "accountNumber": "8612343XXXXXXX"",
        "bankName": "Mock Bank",
        "sortCode": "044XX"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "USD",
      "country": "US"
    },
    "created": "2025-02-27T14:17:48.038044",
    "processed": "2025-02-27T14:20:49.712685"
  }
}

    ​
    Response Breakdown

    Here’s the plain markdown version with the inner lines removed:
    FieldTypeDescription
    messageStringTransaction creation message
    statusStringStatus of the transaction
    dataObjectDetails of the transaction
    data.idStringUnique ID of the transaction
    data.reasonStringReason provided for the transaction
    data.referenceNumberStringReference number for tracking
    data.typeStringType of transaction (e.g., SEND)
    data.stateStringCurrent state of the transaction
    data.quoteObjectQuote details associated with the transaction
    data.quote.idStringQuote ID
    data.quote.sourceObjectSource currency details
    data.quote.source.currencyStringSource currency code (e.g., NGN)
    data.quote.source.countryStringSource country code (e.g., NG)
    data.quote.source.amountNumberSource amount
    data.quote.targetObjectTarget currency details
    data.quote.target.currencyStringTarget currency code (e.g., USD)
    data.quote.target.countryStringTarget country code (e.g., US)
    data.quote.target.amountNumberTarget amount
    data.quote.rateNumberExchange rate
    data.quote.feeObjectFee details
    data.quote.fee.amountNumberFee amount
    data.recipientObjectRecipient details
    data.recipient.nameStringName of the recipient
    data.recipient.typeStringType of recipient (e.g., BANK)
    data.recipient.accountObjectRecipient’s account information
    data.recipient.account.accountNumberStringBank account number
    data.recipient.account.bankNameStringBank Name
    data.recipient.account.sortCodeStringBank sort code
    data.recipient.paymentChannelStringPayment method used
    data.recipient.currencyStringRecipient’s currency code
    data.recipient.countryStringRecipient’s country code
    data.createdStringCreation timestamp
    data.processedStringProcessing timestamp

    ​
    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.