Skip to main content

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:

FieldDescription
currencyUSD
amountAmount in USD
filesOne or more PDF documents
destination.railINTERNATIONAL_WIRE
destination.countryISO code of the destination bank country, e.g. US
destination.accountIdentifierValueDestination account number or IBAN
destination.institution.nameBank name
destination.institution: bank codeAt least one of swiftBic or an ABA routing number. See below
destination.beneficiary.nameBeneficiary name or legal entity name
destination.beneficiary.typefisico (individual) or juridico (company)
destination.beneficiary.taxIdBeneficiary tax identification number
destination.beneficiary.addressBeneficiary address
destination.beneficiary.countryISO 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:

FieldDescription
institution.swiftBicSWIFT/BIC code of the bank
institution.scheme + institution.identifierSet 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 id or 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​

EventEffect on Balance
Transfer createdamount is immediately deducted from the user's available balance
Transfer rejectedAmount is automatically restored to the user's balance