How to Create a EUR Transfer

EUR transfers require a pre-existing bank account belonging to a beneficiary registered in the system.

---

Step 1 — Create a Beneficiary with a European 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.

For European countries, the bank account must include ibanNumber and swiftBic in addition to the base fields.

Request

curl -X POST "/api/v1/beneficiary" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme GmbH",
    "type": "juridico",
    "taxId": "DE123456789",
    "country": "DE",
    "address": "Unter den Linden 1, 10117 Berlin",
    "email": "finance@acme.de",
    "bankAccount": {
      "name": "Acme GmbH - Deutsche Bank",
      "accountNumber": "1234567890",
      "bankCountry": "DE",
      "bankName": "Deutsche Bank",
      "ibanNumber": "DE89370400440532013000",
      "swiftBic": "DEUTDEDB"
    }
  }'

Bank account required fields for European countries

Field	Description
name	Label for this bank account
accountNumber	Destination account number
bankCountry	ISO country code — must be a supported European country
bankName	Name of the destination bank
ibanNumber	Full IBAN number
swiftBic	SWIFT/BIC code for international routing

Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme GmbH",
  "type": "juridico",
  "taxId": "DE123456789",
  "address": "Unter den Linden 1, 10117 Berlin",
  "country": "DE",
  "email": "finance@acme.de",
  "bankAccounts": [
    {
        "id": "d6c6c357-343f-4106-8f7d-b678c60ff10a",
        "name": "Acme GmbH - Deutsche Bank",
        "accountNumber": "1234567890",
        "bankCountry": "DE",
        "bankName": "Deutsche Bank",
        "ibanNumber": "DE89370400440532013000",
        "swiftBic": "DEUTDEDB"
  }
  ]
  "createdAt": "2026-05-14T12:00:00.000Z",
  "updatedAt": "2026-05-14T12:00:00.000Z"
}

---

Step 2 — Create the EUR 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 EUR 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>" \
  -H "Content-Type: multipart/form-data" \
  -F "bankAccountId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "currency=EUR" \
  -F "amount=950.00" \
  -F "files[0]=@invoice.pdf" \
  -F "files[1]=@invoice-2.pdf"

Request Example

curl -X POST /api/v1/transfer \
  -H "Authorization: Bearer <token>" \
  -F "bankAccountId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "currency=EUR" \
  -F "amount=950.00" \
  -F "files=@/path/to/invoice.pdf" \
  -F "files=@/path/to/transfer_order.pdf"

Response (201)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transferNumber": "002095696342671878",
  "status": "pending",
  "currency": "EUR",
  "amount": "840.71",
  "amountInUSD": "950.00",
  "quote": "1.13",
  "pdfDocuments": [
    "https://files.example.com/invoice.pdf",
    "https://files.example.com/transfer_order.pdf"
  ],
  "bankAccount": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Acme GmbH - Deutsche Bank",
    "bankCountry": "DE",
    "accountNumber": "1234567890",
    "bankName": "Deutsche Bank",
    "ibanNumber": "DE89370400440532013000",
    "swiftBic": "DEUTDEDB"
  },
  "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

---