Quick Start

Make your first Compose API calls to create customers and start moving funds quickly.

Make your first Compose API calls to create customers and start moving funds quickly. Try the Compose API Explorer (experimental), a demo app that showcases how to integrate with the Compose API and walk through the core flows.

Step 1: Create a Customer

curl -X POST 'https://compose.finance/api/v2/customers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "JOHN DOE",
    "accountType": "individual",
    "email": "[email protected]"
  }'

Create a customer record with their basic information:

  • name - Customer's full name
  • accountType - individual or corporate
  • expectedMonthlyVolume - (Optional) Expected monthly volume in EUR. If not provided, the customer will enter this during the KYC flow.
  • email - Optional email address

Returns a customerId (UUID) for subsequent API calls.

Step 2: Initiate KYC Verification

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/kyc' \
  -H 'Authorization: Bearer YOUR_API_KEY'

This creates the customer's verification profile and returns:

  • kycFlowLink - A stable KYC flow link for this customer
  • kycVerified - Current verification status

If expectedMonthlyVolume was provided during customer creation, the questionnaire is automatically submitted. Otherwise, the customer will complete the questionnaire during the KYC flow.

For corporate customers, KYC link generation is handled manually by onboarding. Calling POST /customers/{customerId}/kyc returns 400, and your team will receive onboarding instructions by email.

Step 3: Complete Verification

Choose one of two methods:

Redirect the customer to the kycFlowLink URL. They will complete the entire verification flow in their browser, including:

  • Identity document upload
  • Liveness check (video selfie)
  • Proof of address upload
  • Any required questionnaires

The link can be opened in a browser, embedded in an iframe, or used in a mobile WebView. Verification is automatically submitted when all steps are complete.

Detecting events in an iframe

When kycFlowLink is embedded in an iframe, the page forwards Sumsub verification events to the parent window via window.postMessage, so your UI can react to progress. These are client-side browser events, separate from the server-side customer.kyc.* webhooks below. Each message is { source: "compose-finance-kyc", version: 1, customerId, type, payload }, where type is one of:

  • idCheck.onApplicantSubmitted: documents submitted. Treat this as "submitted" rather than "approved"; for levels that need manual review the final decision arrives later (via webhooks or status polling).
  • idCheck.onApplicantStatusChanged: a terminal decision. Read payload.reviewResult.reviewAnswer (GREEN = approved, RED = rejected).
  • idCheck.onError: verification could not start or failed; see payload.message.

In your handler, confirm event.origin is https://www.auth.compose.finance and ignore any message whose event.data.source is not compose-finance-kyc. The <iframe> must set allow="camera; microphone; fullscreen", otherwise the liveness and document-capture steps cannot use the camera. See the Embed in iframe code sample on the Initiate customer KYC endpoint below for a complete, copy-paste example.

Option B: API Document Upload (Partial)

Upload identity and proof of address documents programmatically:

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/documents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/passport.jpg' \
  -F 'idDocType=PASSPORT' \
  -F 'country=GBR'
  1. Upload identity document (PASSPORT, ID_CARD, DRIVERS, or RESIDENCE_PERMIT)
  2. Upload proof of address (PROOF_OF_ADDRESS)
  3. For double-sided documents (ID_CARD, DRIVERS), upload both FRONT_SIDE and BACK_SIDE

Important: The liveness check (video selfie) cannot be completed via API. After uploading documents, redirect the customer to the kycFlowLink to complete the liveness check. Verification is automatically submitted when all steps including liveness are complete.

Step 4: Check Verification Status

curl -X GET 'https://compose.finance/api/v2/customers/{customerId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Poll this endpoint to check verification progress:

  • kyc.kycVerified - true when verification is approved
  • kyc.stepsStatus - Overall status: not_started, incomplete, uploaded, pending, approved, rejected, or disabled
  • kyc.steps - Individual step statuses

When to poll:

  • After redirecting customer to kycFlowLink - poll every 5-10 seconds until stepsStatus changes from incomplete
  • After stepsStatus becomes pending - poll every 30-60 seconds until kycVerified is true or stepsStatus is rejected

Step 5: Configure Customer Wallets & Developer Fees

Customer wallets enable direct-to-wallet deposits where USDC is automatically sent to your customer's crypto wallet when they make a fiat deposit. This is ideal for B2B use cases where you want to facilitate crypto transfers without holding funds.

Setting Up Customer Wallets

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/deposit/wallets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "currency": "usdc",
    "chain": "base"
  }'

Register a USDC wallet address (on Base network) for your customer.

How funds are routed:

  • When a customer deposits fiat (EUR) to their assigned bank account, the funds are automatically converted to USDC
  • USDC is then sent directly to the customer's registered wallet address
  • No manual intervention required - the entire flow is automated

Note: Customer wallets are required for unlicensed organizations before deposits can be processed. For licensed organizations, wallets are optional - if not configured, funds are sent to your organization's wallet.

Earning Developer Fees

Monetize your integration by configuring fees on customer transactions. Fees are automatically deducted from each deposit made to a customer wallet and accumulate in your developer fee balance.

curl -X PATCH 'https://compose.finance/api/v2/customers/{customerId}/developer-fees' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "developerSpreadFeeBps": 100
  }'

Fee Types:

  • developerSpreadFeeBps - Spread fee in basis points (1 bp = 0.01%). Applied to the USDC amount, effectively reducing the exchange rate.

Fee Calculation Example:

Example with 950 USDC and 1% spread (100 bps):
Spread fee: 950 × 100 / 10,000 = 9.50 USDC
Customer receives: 950 - 9.50 = 940.50 USDC

Claiming Your Fees:

Fees accumulate in your developer fee balance and can be claimed at any time: Check your current balance:

curl -X GET 'https://compose.finance/api/v2/developer-fees' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Claim fees to your organization's wallet:

curl -X POST 'https://compose.finance/api/v2/developer-fees' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Step 6: Start Transacting

Once kycVerified is true (and wallet configured for unlicensed orgs): Get bank deposit details:

curl -X GET 'https://compose.finance/api/v2/customers/{customerId}/deposit?currency=eur' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Get transaction history:

curl -X GET 'https://compose.finance/api/v2/customers/{customerId}/transactions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Authentication

Previous Page

KYC Levels

Next Page

On this page

Step 1: Create a CustomerStep 2: Initiate KYC VerificationStep 3: Complete VerificationOption A: Verification Link (Recommended)Detecting events in an iframeOption B: API Document Upload (Partial)Step 4: Check Verification StatusStep 5: Configure Customer Wallets & Developer FeesSetting Up Customer WalletsEarning Developer FeesStep 6: Start Transacting