Create customer withdrawal bank

Adds a new bank account for withdrawals. The customer must be KYC verified. **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** - IBAN and BIC formats are validated automatically - For CUSTOMER: beneficiary name is checked against the customer's verified identity (individual) or organization name (corporate)

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

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

IBAN and BIC formats are validated automatically
For CUSTOMER: beneficiary name is checked against the customer's verified identity (individual) or organization name (corporate)

Authorization

bearerAuth

AuthorizationBearer <token>

Organization API key obtained from PropelAuth

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

iban*string

International Bank Account Number

Length1 <= length

bic*string

Bank Identifier Code (SWIFT)

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

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 '{    "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",
  "recipientType": "OTHER_INDIVIDUAL",
  "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": "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"
}

Create customer withdrawal bank

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

Individual recipient (immediately active)

Business recipient (requires approval)

Invalid IBAN

Invalid BIC

Name doesn't match KYC

KYC not verified

Feature not enabled

Customer disabled

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`