USD → USD via Swift

This endpoint allows you to process USD payouts to recipients in the United States using the SWIFT payment channel for international wire transfers.

Endpoint

POST: {{baseURL}}/v2/payout

Payment Channel Overview

Channel	Description	Use Case
`SWIFT`	International wire transfer using SWIFT code	Cross-border USD wire transfers

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 Requests

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": "885406477269",
      "bankName": "DBS Bank Limited",
      "intermediaryBankSwiftCode": "CHASUS33XXX"
    },
    "paymentChannel": "SWIFT",
    "country": "US",
    "currency": "USD"
  },
  "quoteId": "d3267c84-2b3c-4d6e-9f8g-xxxxxxxxxxxx",
  "reason": "Gift",
  "invoice": "4b9b6d30-a2ed-421a-bd69-11536344f071",
  "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., `Gift`, `Payment for services`).	✅ Yes
`invoice`	String	Optional identifier for the invoice (returned from file upload).	❌ No
`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.nickName`	String	A nickname or alias for the recipient.	❔ No
`recipient.gender`	String	Gender of the recipient. Enum: `M`, `F`.	❔ No
`recipient.occupation`	String	The recipient’s occupation or profession.	❔ No
`recipient.type`	String	The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`.	✅ Yes
`recipient.paymentChannel`	String	The payment method. Use `SWIFT` for international wire transfers.	✅ 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.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 SWIFT/BIC code of the recipient’s bank.	✅ Yes
`recipient.account.sortCode`	String	The bank sort code.	❔ No
`recipient.account.bankName`	String	The name of the recipient’s bank.	✅ Yes
`recipient.account.bankCity`	String	The city where the bank is located.	❔ No
`recipient.account.intermediaryBankSwiftCode`	String	The SWIFT/BIC code of the intermediary bank.	❔ No (Conditional)

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",
    "invoice": "4b9b6d30-a2ed-421a-bd69-11536344f071",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "d3267c84-2b3c-4d6e-9f8g-xxxxxxxxxxxx",
      "source": {
        "currency": "USD",
        "country": "US",
        "amount": 1000
      },
      "target": {
        "currency": "USD",
        "country": "US",
        "amount": 1000
      },
      "rate": 1,
      "fee": {
        "amount": 25
      }
    },
    "recipient": {
      "name": "James Wilson",
      "nickName": "Blue",
      "gender": "M",
      "occupation": "business entrepreneur",
      "type": "BUSINESS",
      "account": {
        "sortCode": "02090",
        "swiftCode": "GTBINGLA",
        "bankCity": "Atlanta",
        "accountNumber": "885406477269",
        "bankName": "DBS Bank Limited",
        "intermediaryBankSwiftCode": "CHASUS33XXX"
      },
      "paymentChannel": "SWIFT",
      "country": "US",
      "currency": "USD"
    },
    "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.invoice`	String	Optional identifier for the invoice 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/BIC 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.

Understanding Intermediary Banks

An Intermediary Bank (also known as a correspondent bank) is a third-party bank that acts as a middleman between the sending bank and the beneficiary bank to facilitate international wire transfers.

Why is an Intermediary SWIFT Code Needed?

When the sending bank and the beneficiary bank do not have a direct financial relationship, they use an intermediary bank to move the funds across borders. This is extremely common for USD transfers outside the United States.

When is the field required?

Required: If your beneficiary bank requires funds to be routed through a specific intermediary bank to receive USD. This information is typically provided in the beneficiary’s wire instructions.
Optional: If the beneficiary bank has a direct relationship with major US clearing banks, this field can be left blank.

How to get the Intermediary SWIFT Code?

The recipient must obtain these details directly from their bank. It is usually found in the “International Wire Instructions” or “Transfer Details” section of their bank’s documentation.

UI Reference

In the meCash dashboard, the Intermediary Bank SWIFT Code field is located within the Add Beneficiary form under the Bank Account section.

Frequently Asked Questions (FAQ)

What happens if the intermediary SWIFT code is missing?

If an intermediary bank is required for the route but not provided, the transfer may be delayed as banks attempt to find a valid route, or it may be rejected and returned (minus processing fees).

What happens if the wrong code is provided?

Providing an incorrect SWIFT code will result in a failed transaction. The funds will eventually be returned to your wallet, but this can take several business days and may incur rejection fees from the involved banks.

Does every USD SWIFT transfer require an intermediary bank?

No. Many large international banks have direct “correspondent” relationships. However, for smaller regional banks or specific corridors, an intermediary is essential for successful delivery.

Best Practices

✅ Ensure quoteId is valid and linked to an existing quote.
✅ Confirm that the recipient’s bank account number and SWIFT code are correct.
✅ Use SWIFT payment channel for international wire transfers requiring SWIFT/BIC codes.
✅ 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.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Transactions

Webhooks

Endpoint

Payment Channel Overview

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Breakdown

Payout Transaction States

Error Handling

Understanding Intermediary Banks

Why is an Intermediary SWIFT Code Needed?

When is the field required?

How to get the Intermediary SWIFT Code?

UI Reference

Frequently Asked Questions (FAQ)

Best Practices

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Transactions

Webhooks

​Endpoint

​Payment Channel Overview

​Request Details

​Headers

​Sample Requests

​Request Body Breakdown

​Success Response (200 OK)

​Response Breakdown

​Payout Transaction States

​Error Handling

​Understanding Intermediary Banks

​Why is an Intermediary SWIFT Code Needed?

​When is the field required?

​How to get the Intermediary SWIFT Code?

​UI Reference

​Frequently Asked Questions (FAQ)

​Best Practices

Endpoint

Payment Channel Overview

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Breakdown

Payout Transaction States

Error Handling

Understanding Intermediary Banks

Why is an Intermediary SWIFT Code Needed?

When is the field required?

How to get the Intermediary SWIFT Code?

UI Reference

Frequently Asked Questions (FAQ)

Best Practices