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 three SWIFT-based payment channels. All use the same recipient fields — the only difference is who bears the transfer charges.
ChannelCharge BearerDescription
SWIFT_CUSTOMERSenderThe sending customer bears all transfer charges.
SWIFT_SHAREDBoth partiesTransfer charges are shared between sender and beneficiary.
SWIFT_BENEFICIARYBeneficiaryThe beneficiary bears all transfer charges.

​
Request Details

​
Headers

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

​
Sample Requests

Use SWIFT_CUSTOMER when the sender bears all transfer charges. Replace paymentChannel with SWIFT_SHARED if charges should be split with the beneficiary, or SWIFT_BENEFICIARY if the beneficiary bears all charges.
All SWIFT channels use identical request fields — only the paymentChannel value changes.
curl --location --request POST '{{baseURL}}/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "recipient": {
    "name": "James Wilson",
    "nickName": "Blue",
    "gender": "M",
    "occupation": "business entrepreneur",
    "type": "BUSINESS",
    "account": {
      "sortCode": "02090",
      "swiftCode": "GTBINGLA",
      "bankCity": "Atlanta",
      "accountNumber": "885406******",
      "bankName": "DBS Bank Limited",
      "intermediarySwiftCode": "CHASUS33XXX"
    }
  },
  "sender": {
    "name": "Test Limited",
    "icNumber": "96671******",
    "nationality": "NG",
    "address": {
      "line1": "12 main st"
    },
    "mobileNumber": "+234872******",
    "occupation": "HEALTHCARE"
  },
  "paymentChannel": "SWIFT_CUSTOMER",
  "currency": "USD",
  "quoteId": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
  "reason": "Gift",
  "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
  "remark": "Testing"
}'

​
Request Body Breakdown

FieldTypeDescriptionRequired
paymentChannelStringThe SWIFT channel to use. SWIFT_CUSTOMER — sender bears all charges; SWIFT_SHARED — charges split; SWIFT_BENEFICIARY — beneficiary bears all charges.✅ Yes
currencyStringThe ISO currency code. Must be USD.✅ Yes
quoteIdStringThe unique ID of the quote for this payout.✅ Yes
reasonStringThe purpose of the transfer (e.g., Gift, Payment for services).✅ Yes
invoiceStringOptional identifier for the invoice (returned from file upload).❔ No
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.nickNameStringA nickname or alias for the recipient.❔ No
recipient.genderStringGender of the recipient. Enum: M, F.❔ No
recipient.occupationStringThe recipient’s occupation or profession.❔ No
recipient.typeStringThe type of recipient. Enum: INDIVIDUAL, BUSINESS.✅ Yes
recipient.accountObjectAn object containing the recipient’s bank account details.✅ Yes
recipient.account.accountNumberStringThe recipient’s bank account number.✅ Yes
recipient.account.swiftCodeStringThe SWIFT/BIC code of the recipient’s bank.✅ Yes
recipient.account.sortCodeStringThe bank sort code.❔ No
recipient.account.bankNameStringThe name of the recipient’s bank.✅ Yes
recipient.account.bankCityStringThe city where the bank is located.❔ No
senderObjectAn object containing details about the person initiating the transfer.✅ Yes
sender.nameStringThe full name of the sender or business.✅ Yes
sender.icNumberStringThe sender’s identification/IC number.✅ Yes
sender.nationalityStringThe sender’s two-letter ISO nationality code (e.g., NG).✅ Yes
sender.addressObjectAn object containing the sender’s address details.✅ Yes
sender.address.line1StringThe first line of the sender’s address.✅ Yes
sender.mobileNumberStringThe sender’s mobile number in international format (e.g., +234...).✅ Yes
sender.occupationStringThe sender’s occupation or industry (e.g., HEALTHCARE).✅ Yes
sender.nameStringThe full name of the sender.✅ Yes
sender.icNumberStringThe IC number of the sender.✅ Yes
sender.nationalityStringThe ISO nationality code of the sender.✅ Yes
sender.addressStringThe address of the sender.✅ Yes
sender.mobileNumberStringThe phone number of the sender.✅ Yes
sender.occupationStringThe occupation of the sender.✅ Yes

​
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": "274fd8a4-38f1-43c9-bf74-ae7744a0dba5",
        "remark": "User-friendly",
        "reason": "Gift",
        "referenceNumber": "0XCGU0EYFEK0Y",
        "invoice": {
            "fileName": "image.png"
        },
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "4da9d52d-618b-4683-b408-8844d1b520cd",
            "paymentChannel": "SWIFT_CUSTOMER",
            "source": {
                "currency": "USD",
                "country": "US",
                "amount": 10.00
            },
            "target": {
                "currency": "USD",
                "country": "US",
                "amount": 10.00
            },
            "rate": 1.00000000,
            "fee": {
                "amount": 100.00,
                "stampDuty": 0
            },
            "summary": {
                "total": 110.00
            },
            "settlement": "1hr",
            "quoteCurrency": "USD"
        },
        "recipient": {
            "name": "Crystal Strosin",
            "nickName": "magenta",
            "gender": "M",
            "type": "BUSINESS",
            "account": {
                "bankName": "DBS Bank Limited",
                "sortCode": "02090",
                "accountNumber": "885406477269",
                "bankCity": "Atlanta",
                "swiftCode": "GTBINGLA"
            },
            "occupation": "business enterpreneur"
        },
        "sender": {
            "name": "Test Limited",
            "icNumber": "96671733919",
            "nationality": "NG",
            "address": {
                "line1": "12 main st"
            },
            "mobileNumber": "+234872272808",
            "occupation": "HEALTHCARE"
        },
        "created": "2026-04-23T18:06:41.022734019Z",
        "processed": "2026-04-23T18:06:41.022734019Z"
    }
}

​
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.remarkStringAn optional, additional note about the transaction.
data.reasonStringThe reason for the payout (e.g., Gift).
data.referenceNumberStringA unique reference number generated for the payout.
data.invoiceObjectDetails of the uploaded invoice.
data.invoice.fileNameStringThe name of the invoice file.
data.typeStringThe type of transaction, e.g., SEND.
data.stateStringThe current state of the payout (PENDING, COMPLETED, etc.).
data.quote.idStringThe unique ID of the quote used for the transaction.
data.quote.paymentChannelStringThe payment channel used (e.g., SWIFT_CUSTOMER, SWIFT_SHARED, SWIFT_BENEFICIARY).
data.quote.source.currencyStringSource currency code.
data.quote.source.amountNumberTotal source amount before fees.
data.quote.target.currencyStringDestination currency code.
data.quote.target.amountNumberThe converted amount that the recipient receives.
data.quote.rateNumberThe exchange rate applied to the transaction.
data.quote.fee.amountNumberThe transaction fee charged.
data.quote.fee.stampDutyNumberApplied stamp duty (if any).
data.quote.summary.totalNumberTotal amount (amount + fees) deducted from wallet.
data.quote.settlementStringThe estimated time for settlement.
data.quote.quoteCurrencyStringThe currency in which the quote is priced.
data.recipient.nameStringThe full name of the recipient.
data.recipient.nickNameStringRecipient’s nickname.
data.recipient.genderStringGender (M or F).
data.recipient.typeStringThe type of recipient entity, e.g., BUSINESS.
data.recipient.account.bankNameStringName of the recipient’s bank.
data.recipient.account.accountNumberStringRecipient’s bank account number.
data.recipient.account.swiftCodeStringSWIFT/BIC code of the bank.
data.recipient.occupationStringOccupation of the recipient.
data.sender.nameStringFull name of the sender.
data.sender.icNumberStringSender’s ID number.
data.sender.nationalityStringISO country code of the sender’s nationality.
data.sender.address.line1StringPrimary address line of the sender.
data.sender.mobileNumberStringInternational mobile number of the sender.
data.sender.occupationStringOccupation of the sender.
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 SWIFT_CUSTOMER when the sender bears all transfer charges, SWIFT_SHARED when charges are split, or SWIFT_BENEFICIARY when the beneficiary bears all charges.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.
Testing Failed Payouts: In the sandbox environment, you can simulate a failed payout by setting "remark": "fail" in your request. This triggers a payout.failed webhook, allowing you to test your error handling.