Skip to main content
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

​
Supported Payment Channels

USD payouts support two payment channels:
ChannelDescriptionUse Case
BANK_TRANSFERStandard domestic bank transfer using routing numberACH/Domestic US transfers
SWIFTInternational wire transfer using SWIFT codeInternational/Cross-border transfers

​
Request Details

​
Headers

Include these headers in your request:
HeaderValueRequired
Content-Typeapplication/json✅ Yes
x-api-keyYOUR_API_KEY✅ Yes

​
Sample Requests

Use BANK_TRANSFER for standard domestic US bank transfers via routing number.
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

FieldTypeDescriptionRequired
quoteIdStringThe unique ID of the quote for this payout.✅ Yes
reasonStringThe purpose of the transfer (e.g., Gift, Payment for services).✅ Yes
remarkStringAn optional, additional note about the transaction.❔ No
recipientObjectAn object containing all details about the person receiving the funds.✅ Yes
recipient.nameStringThe full name of the recipient or business.✅ Yes
recipient.typeStringThe type of recipient. Enum: INDIVIDUAL, BUSINESS.✅ Yes
recipient.addressStringThe recipient’s full residential or business address.✅ Yes
recipient.paymentChannelStringThe payment method. Use BANK_TRANSFER for domestic transfers.✅ Yes
recipient.currencyStringThe ISO currency code. Must be USD.✅ Yes
recipient.countryStringThe recipient’s two-letter ISO country code. Must be US.✅ Yes
recipient.storedBooleanA flag indicating whether to save the recipient for future use.❔ No
recipient.accountObjectAn object containing the recipient’s bank account details.✅ Yes
recipient.account.accountNumberStringThe recipient’s bank account number.✅ Yes
recipient.account.routingNumberStringThe 9-digit ABA routing transit number for the recipient’s bank.✅ Yes
recipient.account.swiftCodeStringThe recipient bank SWIFT code.❔ No
recipient.account.bankNameStringThe name of the recipient’s bank.✅ Yes
recipient.account.addressStringThe address of the recipient’s bank branch.❔ No

​
Success Response (200 OK)

If the payout is successfully created, the API returns the following response:
copy
{
  "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

FieldTypeDescription
messageStringA confirmation message indicating the result of the request.
statusStringThe overall status of the request, e.g., success.
dataObjectA container for all the transaction data.
data.idStringThe unique identifier for this payout transaction.
data.reasonStringThe reason for the payout provided in the request.
data.referenceNumberStringA unique reference number generated for the payout.
data.typeStringThe type of transaction, e.g., SEND.
data.stateStringThe current state of the payout (COMPLETED, PENDING, etc.).
data.quote.idStringThe unique ID of the quote used for the transaction.
data.quote.source.currencyStringThe three-letter currency code of the source funds.
data.quote.target.amountNumberThe converted amount that the recipient received.
data.recipient.nameStringThe full name of the recipient.
data.recipient.typeStringThe type of recipient entity, e.g., BUSINESS.
data.recipient.account.accountNumberStringThe recipient’s bank account number.
data.recipient.account.bankNameStringThe name of the recipient’s bank.
data.recipient.account.swiftCodeStringThe swift code of the recipient’s bank.
data.createdStringISO 8601 timestamp of when the transaction was created.
data.processedStringISO 8601 timestamp of when the transaction was processed.

​
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
400Insufficient BalanceInsufficient Balance
401UnauthorizedInvalid API key provided.
403ForbiddenIP not whitelisted
404Not FoundThe requested endpoint does not exist.
422Unprocessable EntityInvalid quote ID provided.
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 BANK_TRANSFER for domestic US transfers with routing numbers.
✅ Use SWIFT for international wire transfers requiring SWIFT/BIC codes.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.