Payouts

Initiate Fiat Payout

Send fiat currency from your wallet to an external bank account.

POST /v1/payouts/fiat

Headers

Header Required Description
X-Api-Key Yes Your API key
X-Idempotency-Key Yes Unique key to prevent duplicate payouts
Content-Type Yes application/json

Request Body

Common Fields

Field Type Required Description
amount number Yes Amount to send. Must meet the per-currency minimum (see below).
currency string Yes Fiat currency: USD, EUR, or GBP
countryCode string Yes Destination country (ISO 3166-1 alpha-2, e.g. US, GB)
bankName string Yes Name of the destination bank
accountNumber string Yes For IBAN countries, the beneficiary IBAN. For non-IBAN countries (e.g. US, Canada, Australia, and most of Africa/Asia/LATAM), the plain local account number.
bankCode string Yes Bank identifier. Interpreted by destination: ACH routing number for USD→US, UK sort code for GBP→GB, SWIFT/BIC otherwise.
beneficiaryType string Yes BUSINESS or INDIVIDUAL
streetAddress string Yes Beneficiary street address
city string Yes Beneficiary city
postalCode string Yes Beneficiary postal code
reference string No Payment reference (max 30 chars, alphanumeric with spaces, commas, periods, and hyphens)
paymentPurpose string No Purpose of payment
paymentPurposeAttachmentId string No Id of a file previously uploaded via POST /v1/files. Use the data.id returned by that endpoint verbatim (e.g. file_3f1e0a7c-5b2d-4f9c-8a31-90c8b1f4e2a7). The file must belong to your account.
beneficiaryRelationship string Conditional Relationship to the beneficiary. Required when currency is USD. One of: EMPLOYEE, CONTRACTOR, VENDOR, SUBSIDIARY, MERCHANT, CUSTOMER, LANDLORD, FAMILY, OTHER.

Individual Beneficiary Fields

Required when beneficiaryType is INDIVIDUAL:

Field Type Required Description
firstName string Conditional Beneficiary first name
lastName string Conditional Beneficiary last name

Business Beneficiary Fields

Required when beneficiaryType is BUSINESS:

Field Type Required Description
businessName string Conditional Business legal name

National Routing Fields (non-IBAN destinations)

Some non-IBAN destinations identify the branch with a national routing code alongside the account number. Supply the field(s) for the destination country:

Field Type Required when Description
institutionNumber string countryCode is CA Canadian institution number — exactly 3 digits (e.g. 003)
transitNumber string countryCode is CA Canadian transit (branch) number — exactly 5 digits (e.g. 12345)
bsbNumber string countryCode is AU or NZ BSB (Bank-State-Branch) number — exactly 6 digits (e.g. 062000)
ifscCode string countryCode is IN IFSC code — 11 characters: 4 letters, 0, then 6 alphanumerics (e.g. SBIN0001234)

Minimum Amounts

Currency Minimum
USD 100
GBP 30
EUR 30

Requests below the minimum for the selected currency are rejected with 400 Bad Request and a message of the form Minimum payout amount for <CURRENCY> is <amount>.

Routing by Destination

The API automatically routes the payout based on the currency and destination country:

Currency Destination Method bankCode used as accountNumber used as
USD US ACH Routing number Account number
USD / EUR / GBP IBAN country SWIFT / SEPA SWIFT/BIC code IBAN
USD / EUR / GBP Non-IBAN country SWIFT SWIFT/BIC code Local account number
USD / EUR / GBP Canada SWIFT SWIFT/BIC code Account number (+ institutionNumber and transitNumber)
USD / EUR / GBP Australia / New Zealand SWIFT SWIFT/BIC code Account number (+ bsbNumber)
USD / EUR / GBP India SWIFT SWIFT/BIC code Account number (+ ifscCode)
GBP GB FPS UK sort code UK 8-digit account number

Non-IBAN countries (US, Canada, Australia, India, and most of Africa, Asia and Latin America) are identified by a plain account number rather than an IBAN; for these, pass the account number in accountNumber. Some also require a national routing code — see National Routing Fields (Canada institutionNumber+transitNumber, Australia/New Zealand bsbNumber, India ifscCode).

Bank Detail Validation

Before the payout is submitted, the bank details are verified. If the details fail validation, the request is rejected with 400 Bad Request before any funds move:

{
  "status": false,
  "message": "Invalid bank details.",
  "errors": ["Invalid IBAN checksum", "BIC not recognised"]
}

Example Request (Individual, USD to US) 

curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-660e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "countryCode": "US",
    "bankName": "Chase Bank",
    "accountNumber": "0123456789",
    "bankCode": "021000021",
    "beneficiaryType": "INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "streetAddress": "123 Main St",
    "city": "New York",
    "postalCode": "10001",
    "reference": "INV-2026-001",
    "paymentPurpose": "Supplier payment",
    "beneficiaryRelationship": "VENDOR"
  }'

Attaching a Payment Purpose Document

To accompany a payout with supporting documentation (e.g. an invoice or contract), upload the file first via POST /v1/files, then reference the returned id on the payout:

# 1. Upload the file
curl -X POST "https://api.esca.finance/v1/files" \
  -H "X-Api-Key: your_api_key_here" \
  -F "file=@invoice.pdf"
# → { "data": { "id": "file_3f1e0a7c-5b2d-4f9c-8a31-90c8b1f4e2a7" } }

# 2. Initiate the payout, referencing the file
curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-880e8400-e29b-41d4-a716-446655440003" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "countryCode": "US",
    "bankName": "Chase Bank",
    "accountNumber": "0123456789",
    "bankCode": "021000021",
    "beneficiaryType": "BUSINESS",
    "businessName": "Acme Corp",
    "streetAddress": "123 Main St",
    "city": "New York",
    "postalCode": "10001",
    "paymentPurpose": "Supplier payment for invoice 2026-001",
    "paymentPurposeAttachmentId": "file_3f1e0a7c-5b2d-4f9c-8a31-90c8b1f4e2a7",
    "beneficiaryRelationship": "VENDOR"
  }'

The id may only be referenced by the same account that uploaded the file — using a file id that belongs to a different account returns 400 Bad Request.

Example Request (Business, GBP to UK) 

curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-770e8400-e29b-41d4-a716-446655440002" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "GBP",
    "countryCode": "GB",
    "bankName": "Barclays",
    "accountNumber": "20015555",
    "bankCode": "200000",
    "beneficiaryType": "BUSINESS",
    "businessName": "Acme Corp",
    "streetAddress": "456 High St",
    "city": "London",
    "postalCode": "EC1A 1BB"
  }'

Example Request (Business, USD to Canada)

Canada is a non-IBAN destination: pass the plain account number plus the 3-digit institutionNumber and 5-digit transitNumber.

curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-990e8400-e29b-41d4-a716-446655440004" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "countryCode": "CA",
    "bankName": "Royal Bank of Canada",
    "accountNumber": "7654321",
    "bankCode": "ROYCCAT2",
    "institutionNumber": "003",
    "transitNumber": "12345",
    "beneficiaryType": "BUSINESS",
    "businessName": "Maple Trading Inc",
    "streetAddress": "200 Bay St",
    "city": "Toronto",
    "postalCode": "M5J 2J5",
    "paymentPurpose": "Consulting",
    "beneficiaryRelationship": "VENDOR"
  }'

Example Request (Business, USD to Australia)

Australia and New Zealand are non-IBAN destinations: pass the account number plus the 6-digit bsbNumber.

curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-aa0e8400-e29b-41d4-a716-446655440005" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "countryCode": "AU",
    "bankName": "National Australia Bank",
    "accountNumber": "123456789",
    "bankCode": "NATAAU33",
    "bsbNumber": "062000",
    "beneficiaryType": "BUSINESS",
    "businessName": "Outback Trading Pty",
    "streetAddress": "1 George St",
    "city": "Sydney",
    "postalCode": "2000",
    "beneficiaryRelationship": "VENDOR"
  }'

Example Request (Business, USD to India)

India is a non-IBAN destination: pass the account number plus the 11-character ifscCode.

curl -X POST "https://api.esca.finance/v1/payouts/fiat" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: payout-bb0e8400-e29b-41d4-a716-446655440006" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "countryCode": "IN",
    "bankName": "State Bank of India",
    "accountNumber": "50100123456789",
    "bankCode": "SBININBB",
    "ifscCode": "SBIN0001234",
    "beneficiaryType": "BUSINESS",
    "businessName": "Lotus Exports Pvt",
    "streetAddress": "12 MG Road",
    "city": "Mumbai",
    "postalCode": "400001",
    "beneficiaryRelationship": "VENDOR"
  }'

Example Response 

{
  "status": true,
  "message": "Payout initiated successfully",
  "data": {
    "payoutId": "f7a8b9c0-d1e2-3456-abcd-ef7890123456",
    "type": "fiat",
    "currency": "USD",
    "amount": 500,
    "fee": 5.00,
    "status": "PROCESSING",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:31:00.000Z",
    "bankName": "Chase Bank",
    "bankAccountNumber": "0123456789",
    "firstName": "John",
    "lastName": "Doe"
  }
}

For business beneficiaries, the response includes businessName instead of firstName/lastName.

Error Responses

Status Description
400 Invalid request, unsupported country, or bank details that fail upstream validation (response includes an errors array — see Bank Detail Validation)
401 Invalid or expired API key
409 Duplicate request (idempotency conflict)
429 Rate limit exceeded
500 Payout failed
Previous
Crypto Payout
Next
Payout Status