How to Create a USD Bank Transfer
USD bank transfers send funds to a bank account through the INTERNATIONAL_WIRE rail. The destination bank can be in the United States or in one of the other supported countries: China, Hong Kong, Japan, Armenia, Azerbaijan and Georgia.
You can create the transfer in a single request. There is no need to create the beneficiary or the bank account beforehand: when you submit the transfer with the account details and the beneficiary, the API creates the payout destination (the bank account) and its beneficiary for you. If the same account was used before, it is reused instead of duplicated.
There are two ways to create a USD transfer:
- Option A — New transfer with the bank details and beneficiary in the same request
- Option B — Reuse a previously created payout destination with its
id
Read the Bank Transfers Overview first for authentication, the request format and the transfer lifecycle.
Endpoint
POST /payout/transfer
API Reference: Create a bank transfer
The request is multipart/form-data. The destination field is sent as a JSON-encoded string.
PDF attachments
PDF attachments are required for USD transfers, for example the invoice that supports the payment.
- Format: PDF only
- Maximum 10 files per transfer
- Maximum 1 MB per file
Add one -F "files=@..." part per file.
Option A — New Destination in the Same Request
Pass the bank details and the beneficiary inside destination. The API validates them against the international wire rail and creates the destination.
Required fields for this option:
| Field | Description |
|---|---|
currency | USD |
amount | Amount in USD |
files | One or more PDF documents |
destination.rail | INTERNATIONAL_WIRE |
destination.country | ISO code of the destination bank country, e.g. US |
destination.accountIdentifierValue | Destination account number or IBAN |
destination.institution.name | Bank name |
destination.institution: bank code | At least one of swiftBic or an ABA routing number. See below |
destination.beneficiary.name | Beneficiary name or legal entity name |
destination.beneficiary.type | fisico (individual) or juridico (company) |
destination.beneficiary.taxId | Beneficiary tax identification number |
destination.beneficiary.address | Beneficiary address |
destination.beneficiary.country | ISO code of the beneficiary country |
Optional fields: destination.label to find the destination later, destination.institution.address, and destination.beneficiary.email.
Identifying the bank
You must provide the bank's SWIFT/BIC code, its ABA routing number, or both:
| Field | Description |
|---|---|
institution.swiftBic | SWIFT/BIC code of the bank |
institution.scheme + institution.identifier | Set scheme to US_ABA and identifier to the 9-digit ABA routing number of a US bank. Both fields must be sent together |
If both are present, both are stored.
Request — United States, with ABA routing number
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=USD" \
-F "amount=1000.00" \
-F 'destination={"rail":"INTERNATIONAL_WIRE","country":"US","accountIdentifierValue":"000123456789","label":"Acme Corp - JPMorgan","institution":{"name":"JPMorgan Chase Bank","scheme":"US_ABA","identifier":"021000021"},"beneficiary":{"name":"Acme Corp","type":"juridico","taxId":"12-3456789","address":"350 Fifth Avenue, New York, NY 10118","country":"US"}}' \
-F "files=@invoice.pdf" \
-F "files=@transfer_order.pdf"
Request — Other countries, with SWIFT/BIC
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=USD" \
-F "amount=1000.00" \
-F 'destination={"rail":"INTERNATIONAL_WIRE","country":"JP","accountIdentifierValue":"1234567890","label":"Tanaka Trading - Mizuho","institution":{"name":"Mizuho Bank","swiftBic":"MHCBJPJT"},"beneficiary":{"name":"Tanaka Trading Co.","type":"juridico","taxId":"1234567890123","address":"1-1 Marunouchi, Chiyoda-ku, Tokyo","country":"JP"}}' \
-F "files=@invoice.pdf"
If an active destination with the same account already exists but is linked to a different beneficiary, the request is rejected. If it is the same beneficiary, reuse the destination explicitly with its
id(Option B).
Option B — Existing Payout Destination
If a payout destination was created before, by a previous transfer or directly through the destinations API, reuse it by passing its id. No other destination fields are needed.
Find an existing destination
curl -X GET "/api/v1/payout-destination?rails=INTERNATIONAL_WIRE" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>"
This returns a paginated list of the active payout destinations of the authenticated user. Use the optional country parameter to narrow it down and the optional search parameter to look for a label or bank name, then use the id of the destination you want.
Request
curl -X POST "/api/v1/payout/transfer" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <token>" \
-F "currency=USD" \
-F "amount=1000.00" \
-F 'destination={"id":"d6c6c357-343f-4106-8f7d-b678c60ff10a"}' \
-F "files=@invoice.pdf"
Send either
idor the destination fields, never both.
Creating the destination or the beneficiary separately (optional)
If you prefer to build your list of saved bank accounts before sending money, for example to let your users pick one, you can create the pieces on their own:
Then send transfers with destination.id, as in Option B. This is a convenience, not a requirement.
Response (201) — All options
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"type": "transfer",
"payoutNumber": "002095696342671878",
"status": "pending",
"currency": "USD",
"amount": "1000.00",
"pdfDocuments": [
"https://files.example.com/invoice.pdf",
"https://files.example.com/transfer_order.pdf"
],
"destination": {
"id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
"label": "Acme Corp - JPMorgan",
"rail": "INTERNATIONAL_WIRE",
"country": "US",
"currency": "USD",
"accountIdentifierScheme": "LOCAL_BANK_ACCOUNT_NUMBER",
"accountIdentifierValue": "000123456789",
"institution": {
"name": "JPMorgan Chase Bank",
"scheme": "US_ABA",
"identifier": "021000021"
},
"beneficiary": {
"name": "Acme Corp",
"taxId": {
"scheme": "OTHER",
"value": "12-3456789"
}
}
},
"createdAt": "2026-05-14T12:05:00.000Z",
"updatedAt": "2026-05-14T12:05:00.000Z"
}
Unlike the other currencies, USD transfers don't use an exchange rate, so amountInUSD and quote are not set and are not part of the example above.
destination is a snapshot of the destination taken when the transfer was created. Later edits to the destination don't change it.
Balance Impact
| Event | Effect on Balance |
|---|---|
| Transfer created | amount is immediately deducted from the user's available balance |
| Transfer rejected | Amount is automatically restored to the user's balance |