Create customer withdrawal bank

Server URLloading...

POST

/api/v2/customers/{customerId}/withdrawal/banks

Send

Authorization

Path

Body

Adds a new bank account for withdrawals. The customer must be KYC verified.

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.

Legacy requests may still send currency without paymentRail; EUR maps to SEPA and USD maps to FEDWIRE.

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.
• OTHER_INDIVIDUAL - A third-party individual. Requires manual approval.
• 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.

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
• For CUSTOMER: beneficiary name is checked against the customer's verified identity (individual) or organization name (corporate)

Path Parameters

Response Body

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

{
  "id": "bank_123abc",
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "beneficiaryName": "JOHN DOE",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "addressLine1": "123 Main Street",
  "city": "Berlin",
  "country": "DE",
  "currency": "EUR",
  "paymentRail": "SEPA",
  "recipientType": "CUSTOMER",
  "recipientEmail": "[email protected]",
  "notificationEnabled": false,
  "status": "ACTIVE",
  "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"
}