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 when virtual accounts are available for your organization. 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

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 GBP."
}

{
  "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"
}
{
  "message": "Invalid media type."
}
{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "Internal server error"
}

Verify Ethereum address POST

Validates an Ethereum address and provides information about its type. **Checks Performed** - Address format validation (EIP-55 checksum; all-lowercase addresses are accepted) - Contract detection (checks if address has deployed code on Base) - Safe wallet identification (checks if it's a Safe multisig on Base) **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.