USD Payout

This endpoint allows you to process payouts in US Dollars (USD) to recipients with a bank account in the United States.

Endpoint

POST: {{baseURL}}/v2/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

Here are examples of how to make a USD payout request in different languages.

curl --location --request POST '{{baseURL}}/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipient": {
    "name": "Linda Collins",
    "type": "BUSINESS",
    "address": "200 Koch Vista, New York, NY 10001",
    "account": {
      "accountNumber": "8573629XX",
      "swiftCode": "12345",
      "bankName": "Chase Bank",
      "address": "1948 Kemmer Ville, New York, NY 10002",
      "routingNumber": "0210000XX"
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "USD",
    "country": "US",
    "stored": false
  },
  "quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
  "reason": "Gift",
  "remark": "Testing"
}'

Request Body Breakdown

Field	Type	Description	Required
`quoteId`	String	The unique ID of the quote for this payout.	✅ Yes
`reason`	String	The purpose of the transfer (e.g., `Payment for services`).	✅ Yes
`remark`	String	An optional, additional note about the transaction.	❔ No
`recipient`	Object	An object containing all details about the person receiving the funds.	✅ Yes
`recipient.name`	String	The full name of the recipient or business.	✅ Yes
`recipient.type`	String	The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`.	✅ Yes
`recipient.address`	String	The recipient's full residential or business address.	✅ Yes
`recipient.paymentChannel`	String	The payment method. Must be `BANK_TRANSFER` for USD payouts.	✅ Yes
`recipient.currency`	String	The ISO currency code. Must be `USD`.	✅ Yes
`recipient.country`	String	The recipient's two-letter ISO country code. Must be `US`.	✅ Yes
`recipient.stored`	Boolean	A flag indicating whether to save the recipient for future use.	✅ Yes
`recipient.account`	Object	An object containing the recipient's bank account details.	✅ Yes
`recipient.account.accountNumber`	String	The recipient's bank account number.	✅ Yes
`recipient.account.swiftCode`	String	The recipient bank swift code.	✅ Yes
`recipient.account.bankName`	String	The name of the recipient's bank.	✅ Yes
`recipient.account.address`	String	The address of the recipient's bank branch.	✅ Yes
`recipient.account.routingNumber`	String	The 9-digit ABA routing transit number for the recipient's bank.	✅ 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": "Linda Collins",
      "type": "BUSINESS",
      "address": "200 Koch Vista, New York, NY 10001",
      "account": {
          "accountNumber": "8573629XX",
          "swiftCode": "1234",
          "bankName": "Chase Bank",
          "address": "1948 Kemmer Ville, New York, NY 10002",
          "routingNumber": "0210000XX"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "USD",
      "country": "US"
    },
    "created": "2025-02-27T14:17:48.038044Z",
    "processed": "2025-02-27T14:20:49.712685Z"
  }
}

Response Breakdown

Field	Type	Description
`message`	String	A confirmation message indicating the result of the request.
`status`	String	The overall status of the request, e.g., `success`.
`data`	Object	A container for all the transaction data.
`data.id`	String	The unique identifier for this payout transaction.
`data.reason`	String	The reason for the payout provided in the request.
`data.referenceNumber`	String	A unique reference number generated for the payout.
`data.type`	String	The type of transaction, e.g., `SEND`.
`data.state`	String	The current state of the payout (`COMPLETED`, `PENDING`, etc.).
`data.quote.id`	String	The unique ID of the quote used for the transaction.
`data.quote.source.currency`	String	The three-letter currency code of the source funds.
`data.quote.target.amount`	Number	The converted amount that the recipient received.
`data.recipient.name`	String	The full name of the recipient.
`data.recipient.type`	String	The type of recipient entity, e.g., `BUSINESS`.
`data.recipient.account.accountNumber`	String	The recipient's bank account number.
`data.recipient.account.bankName`	String	The name of the recipient's bank.
`data.recipient.account.swiftCode`	String	The swift code of the recipient's bank.
`data.created`	String	ISO 8601 timestamp of when the transaction was created.
`data.processed`	String	ISO 8601 timestamp of when the transaction was processed.

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`	Insufficient Balance	Insufficient Balance
`401`	Unauthorized	Invalid API key provided.
`403`	Forbidden	IP not whitelisted
`404`	Not Found	The requested endpoint does not exist.
`422`	Unprocessable Entity	Invalid quote ID provided.
`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 CAD