How to Create a USD Transfer

USD transfers require a pre-existing bank account belonging to a beneficiary registered in the system. The destination bank can be in the United States or an Asian country.

---

Step 1 — Create a Beneficiary with a Bank Account

Use POST /beneficiary to create the beneficiary and one bank account in a single request. The bankAccount object is embedded in the body.

Required bank account fields vary by destination region:

United States

Field	Required	Notes
name	Yes	Label for this bank account
accountNumber	Yes	Destination account number
bankCountry	Yes	US
bankName	Yes	Name of the destination bank
ibanNumber	Yes	IBAN number
swiftBic	Conditional	Required if achRoutingNumber is not provided
achRoutingNumber	Conditional	Required if swiftBic is not provided

At least one of swiftBic or achRoutingNumber must be provided. If both are present, both are stored.

Asian countries

Field	Required
name	Yes
accountNumber	Yes
bankCountry	Yes
bankName	Yes
ibanNumber	Yes
swiftBic	Yes

---

Request — US bank account example

curl -X POST "/api/v1/beneficiary" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "type": "juridico",
    "taxId": "12-3456789",
    "country": "US",
    "address": "350 Fifth Avenue, New York, NY 10118",
    "bankAccount": {
      "name": "Acme Corp - JPMorgan",
      "accountNumber": "000123456789",
      "bankCountry": "US",
      "bankName": "JPMorgan Chase Bank",
      "ibanNumber": "US12345678901234567890",
      "achRoutingNumber": "021000021"
    }
  }'

Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "type": "juridico",
  "taxId": "12-3456789",
  "address": "350 Fifth Avenue, New York, NY 10118",
  "country": "US",
  "bankAccounts": [
    {
      "id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
      "name": "Acme Corp - JPMorgan",
      "accountNumber": "000123456789",
      "bankCountry": "US",
      "bankName": "JPMorgan Chase Bank",
      "ibanNumber": "US12345678901234567890",
      "achRoutingNumber": "021000021"
    }
  ],
  "createdAt": "2026-05-14T12:00:00.000Z",
  "updatedAt": "2026-05-14T12:00:00.000Z"
}

---

Step 2 — Create the USD Transfer

Use POST /transfer with multipart/form-data. Pass bankAccountId along with the financial fields and attach the required PDF files.

PDF attachments are required for USD transfers. The request will fail without them.

Constraints for attached files:

• Format: PDF only
• Maximum 10 files per transfer
• Maximum 1 MB per file

Request

curl -X POST "/api/v1/transfer" \
  -H "Authorization: Bearer <token>" \
  -F "bankAccountId=d6c6c357-343f-4106-8f7d-b678c60ff10a" \
  -F "currency=USD" \
  -F "amount=1000.00" \
  -F "files[0]=@invoice.pdf" \
  -F "files[1]=@transfer_order.pdf"

Response (201)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transferNumber": "002095696342671878",
  "status": "pending",
  "currency": "USD",
  "amount": "1000.00",
  "amountInUSD": "1000.00",
  "quote": "1.00",
  "pdfDocuments": [
    "https://files.example.com/invoice.pdf",
    "https://files.example.com/transfer_order.pdf"
  ],
  "bankAccount": {
    "id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
    "name": "Acme Corp - JPMorgan",
    "bankCountry": "US",
    "accountNumber": "000123456789",
    "bankName": "JPMorgan Chase Bank",
    "ibanNumber": "US12345678901234567890",
    "achRoutingNumber": "021000021"
  },
  "createdAt": "2026-05-14T12:05:00.000Z",
  "updatedAt": "2026-05-14T12:05:00.000Z"
}

---

Balance Impact

Event	Effect on Balance
Transfer created	Amount in USD is immediately deducted from the user's available balance
Transfer rejected	Amount is automatically restored to the user's balance