Create customer withdrawal bank

Adds a new bank account for withdrawals. The customer must be KYC verified, except for AUD withdrawal banks.

Currency and payment rails

SEPA (EUR): provide currency: "EUR", paymentRail: "SEPA", iban, and bic.
FEDWIRE (USD): provide currency: "USD", paymentRail: "FEDWIRE", accountNumber, and routingNumber.
SWIFT (USD): provide currency: "USD", paymentRail: "SWIFT", accountNumber (or IBAN), bic, bankName, bankAddress, and bankCountry.
AU_BANK_TRANSFER (AUD): provide currency: "AUD", paymentRail: "AU_BANK_TRANSFER", bsb, accountNumber, the payee's firstName, lastName and dateOfBirth, and the full address (addressLine1, city, postalCode, country). Only for AUD-only customers, verified or not, when AUD functionality is enabled for your organization. The payee is an individual: CUSTOMER and OTHER_INDIVIDUAL are active immediately, and OTHER_BUSINESS is refused. AUD-only customers cannot add EUR or USD accounts.

For backwards compatibility the API still accepts currency without paymentRail (EUR maps to SEPA, USD to FEDWIRE), but new integrations must send paymentRail.

Recipient Types

CUSTOMER - The customer themselves. Auto-approved if the beneficiary name matches the customer's verified name (KYC name for individuals, organization name for corporates). Returns 400 on name mismatch. AUD withdrawal banks are not name-checked: they are active immediately.
OTHER_INDIVIDUAL - A third-party individual. Requires manual approval, except for AUD withdrawal banks, which are active immediately.
OTHER_BUSINESS - A third-party business. Requires manual approval.

If recipientType is not specified, it defaults to CUSTOMER.

Address

For CUSTOMER recipients, addressLine1 and city are optional. If omitted, the address is auto-resolved from the customer's KYC data (individuals) or stored business address (corporates). You can check the available address via GET /customers/{customerId}/kyc/address. For OTHER_INDIVIDUAL and OTHER_BUSINESS, address fields are required. AUD withdrawal banks always require the payee's full address (addressLine1, city, postalCode, country).

Validation

EUR: IBAN and BIC/SWIFT formats are validated automatically
USD Fedwire: account number and routing number are validated automatically
USD SWIFT: BIC/SWIFT format is validated automatically, and bank name/address/country are required
AUD: the BSB must be 6 digits and the account number 1–9 digits; the account is checked with the payout provider before it is saved, and nothing is saved if that fails (502, safe to retry)
For CUSTOMER: beneficiary name is checked against the customer's verified identity (individual) or organization name (corporate), except for AUD withdrawal banks

Authorization

bearerAuth

AuthorizationBearer <token>

Organization API key obtained on Settings > API Keys page in Compose UI.

In: header

Path Parameters

customerId*string

Unique identifier of the customer

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

beneficiaryName*string

Full name of the bank account holder

Length1 <= length

currency*string

Currency for this withdrawal bank.

Value in"EUR"

paymentRail*string

Payment rail for this withdrawal bank.

Value in"SEPA"

iban*string

International Bank Account Number (IBAN) for EUR withdrawals.

Length1 <= length

bic*string

Bank Identifier Code (BIC/SWIFT) for EUR withdrawals.

Length1 <= length

addressLine1?string

Street address of the account holder. Optional for CUSTOMER recipient type — auto-resolved from KYC data (individual) or stored address (corporate) when not provided. Required for OTHER_INDIVIDUAL and OTHER_BUSINESS.

Length1 <= length

city?string

City of the account holder. Optional for CUSTOMER recipient type — auto-resolved from KYC data (individual) or stored address (corporate) when not provided. Required for OTHER_INDIVIDUAL and OTHER_BUSINESS.

Length1 <= length

postalCode?string

Postal code of the account holder. Required for OTHER_INDIVIDUAL and OTHER_BUSINESS. For CUSTOMER it is auto-resolved from KYC data (individual) or stored address (corporate) when the address is omitted; if you supply addressLine1 or city you must supply postalCode too (country on its own does not require it).

Length1 <= length

country?string

ISO 3166-1 alpha-2 country code of the account holder's address. Optional for CUSTOMER recipients — auto-resolved from KYC data (individual) or stored address (corporate). Required for OTHER_INDIVIDUAL and OTHER_BUSINESS. Returns 400 if country cannot be resolved.

Length2 <= length <= 2

recipientType?string

Type of recipient. Case-insensitive (e.g. "customer" or "Customer" are accepted). CUSTOMER: the customer themselves (auto-approved with name verification). OTHER_INDIVIDUAL/OTHER_BUSINESS: third party (requires approval). Default: CUSTOMER.

Value in"CUSTOMER" | "OTHER_INDIVIDUAL" | "OTHER_BUSINESS"

recipientEmail?string

Email address for payment notifications. Required when notificationEnabled is true.

Formatemail

notificationEnabled?boolean

Whether to send payment notifications to the recipient email

Defaultfalse

Response Body

`application/json`

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/withdrawal/banks' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{    "currency": "EUR",    "paymentRail": "SEPA",    "beneficiaryName": "JOHN DOE",    "iban": "DE89370400440532013000",    "bic": "COBADEFFXXX",    "addressLine1": "123 Main Street",    "city": "Berlin",    "postalCode": "10115"  }'

{
  "id": "bank_123abc",
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "beneficiaryName": "JOHN DOE",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "addressLine1": "123 Main Street",
  "city": "Berlin",
  "postalCode": "10117",
  "country": "DE",
  "currency": "EUR",
  "paymentRail": "SEPA",
  "recipientType": "CUSTOMER",
  "recipientEmail": "[email protected]",
  "notificationEnabled": false,
  "status": "ACTIVE",
  "fundingSource": "VIRTUAL_ACCOUNT",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "wallets": [
    {
      "id": "wallet_123abc",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "currency": "usdc",
      "chain": "base",
      "enabled": true,
      "createdAt": "2024-01-15T10:30:05.000Z",
      "updatedAt": "2024-01-15T10:30:05.000Z",
      "instructions": "Send USDC to this address to automatically receive funds in your bank account. Minimum: 5 USDC."
    }
  ]
}

{
  "error": "iban: Invalid IBAN format"
}

{
  "error": "Unauthorized - Invalid or missing API key or session"
}

{
  "error": "Customers feature is not enabled for your organization"
}

{
  "error": "Customer not found"
}

{
  "message": "Invalid media type."
}

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "Internal server error"
}

{
  "error": "The bank account could not be added right now. Please try again."
}

Create customer withdrawal bank

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

415application/json

429application/json

500application/json

502application/json

EUR individual recipient (active immediately)

EUR business recipient (pending approval)

USD individual recipient (active immediately)

USD SWIFT individual recipient (active immediately)

AUD withdrawal bank for an AUD-only customer (active immediately)

Invalid IBAN

Invalid BIC

Invalid USD account number

Invalid USD routing number

Missing SWIFT bank name

Missing SWIFT bank address

Missing SWIFT bank country

Name doesn't match KYC

KYC not verified

Currency unavailable for organization

Malformed JSON

Name doesn't match organization name

AUD-only customer

AUD withdrawal bank for a standard customer

AUD withdrawal bank for a business

Invalid BSB

AUD withdrawal bank refused by the payout provider

AUD unavailable for organization

Feature not enabled

Customer disabled

Error field

Message field

Payout provider unavailable

Bank account could not be verified

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`