Quick Start

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

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 (corporate accounts coming soon)
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 verification link valid for 1 week
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.

Step 3: Complete Verification

Choose one of two methods:

Option A: WebSDK Link (Recommended)

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.

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'

Upload identity document (PASSPORT, ID_CARD, DRIVERS, or RESIDENCE_PERMIT)
Upload proof of address (PROOF_OF_ADDRESS)
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"
  }'

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'

Quick Start

On this page