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:

Header	Value	Required
`Content-Type`	`application/json`	✅ Yes
`x-api-key`	`YOUR_API_KEY`	✅ Yes

Sample Request

curl --location --request POST '{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient": {
    "id": "ef2503ff-aec9-40e5-bfcf-xxxxxxxxxxxxx",
    "firstName": "Adeolu",
    "lastName": "Adebayo",
    "type": "BUSINESS",
    "account": {
      "accountNumber": "8612343XXXXXXX",
      "bankName": "Mock Bank",
      "sortCode": "044XX",
      "routingNumber": "342672"
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "USD",
    "country": "US",
    "stored": true
  },
  "quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
  "reason": "Gift"
}'

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 (INDIVIDUAL or BUSINESS)	Yes
recipient.account	Object	Recipient’s bank account details	Yes
account.accountNumber	String	Bank account number of the recipient	Yes
account.sortCode	String	Sort code of the recipient's bank	Yes
account.routingNumber	String	Routing number for the recipient's bank	Yes
recipient.paymentChannel	String	Payment method (BANK_TRANSFER)	Yes
recipient.currency	String	Currency code (e.g., USD)	Yes
recipient.country	String	Country code (e.g., US)	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": "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:

Field	Type	Description
`message`	String	Transaction creation message
`status`	String	Status of the transaction
`data`	Object	Details of the transaction
`data.id`	String	Unique ID of the transaction
`data.reason`	String	Reason provided for the transaction
`data.referenceNumber`	String	Reference number for tracking
`data.type`	String	Type of transaction (e.g., `SEND`)
`data.state`	String	Current state of the transaction
`data.quote`	Object	Quote details associated with the transaction
`data.quote.id`	String	Quote ID
`data.quote.source`	Object	Source currency details
`data.quote.source.currency`	String	Source currency code (e.g., `NGN`)
`data.quote.source.country`	String	Source country code (e.g., `NG`)
`data.quote.source.amount`	Number	Source amount
`data.quote.target`	Object	Target currency details
`data.quote.target.currency`	String	Target currency code (e.g., `USD`)
`data.quote.target.country`	String	Target country code (e.g., `US`)
`data.quote.target.amount`	Number	Target amount
`data.quote.rate`	Number	Exchange rate
`data.quote.fee`	Object	Fee details
`data.quote.fee.amount`	Number	Fee amount
`data.recipient`	Object	Recipient details
`data.recipient.name`	String	Name of the recipient
`data.recipient.type`	String	Type of recipient (e.g., `BANK`)
`data.recipient.account`	Object	Recipient's account information
`data.recipient.account.accountNumber`	String	Bank account number
`data.recipient.account.bankName`	String	Bank Name
`data.recipient.account.sortCode`	String	Bank sort code
`data.recipient.paymentChannel`	String	Payment method used
`data.recipient.currency`	String	Recipient’s currency code
`data.recipient.country`	String	Recipient’s country code
`data.created`	String	Creation timestamp
`data.processed`	String	Processing timestamp

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.

NGN to GBP NGN to CNY AliPay (Email)