Virtual accounts

Create customer virtual account

Create a dedicated named virtual account for a customer.

POST
/api/v2/customers/{customerId}/virtual-account

Creates a dedicated named virtual IBAN for the customer. For individual customers, address and identity information is pulled from Sumsub KYC verification. For corporate customers, a verified business address and registration number must already be on file (completed via Compose onboarding). The account creation is asynchronous.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/virtual-account' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{"currency": "EUR"}'
{
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING",
  "virtualAccountId": "corr-12345-abcde",
  "message": "Virtual account creation initiated. IBAN will be provided via webhook once the provider processes the request."
}

{
  "error": "No virtual account provider configured for USD. Please contact support."
}

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

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

{
  "error": "Customer not found"
}
{
  "error": "Customer already has an active virtual account for this provider"
}
{
  "error": "Internal server error"
}

Verify Ethereum address POST

Validates an Ethereum address and provides information about its type. **Checks Performed** - Address format validation (checksum) - Contract detection (checks if address has deployed code) - Safe wallet identification (checks if it's a Gnosis Safe multisig) **Use Cases** - Validate customer wallet addresses before saving - Detect if a recipient is a smart contract - Identify Safe wallets for display purposes

Get customer virtual account GET

Returns the virtual account details and status for a specific virtual account ID. Use `GET /virtual-accounts` to list all virtual accounts for a customer.