Developer fees

Update customer developer fees

Configure developer fees charged on customer transactions.

PATCH
/api/v2/customers/{customerId}/developer-fees

Updates the developer fee configuration for the customer. These fees are deducted from customer deposits before USDC is sent to their wallet.

Fee Types

  • developerSpreadFeeBps: Spread fee in basis points (0-2500, max 25%). Applied to the USDC amount.

Fee Calculation

spreadFee = amount × spreadFeeBps / 10000
customerReceives = amount - spreadFee

Example: 1000 USDC deposit with 1% spread (100 bps) → customer receives 990 USDC

Authorization

bearerAuth
AuthorizationBearer <token>

Organization API key obtained on Settings > API Keys page in Compose UI.

In: header

Path Parameters

customerId*string

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

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  }'
{
  "customerId": "550e8400-e29b-41d4-a716-446655440001",
  "developerSpreadFeeBps": 100,
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

{
  "message": "Invalid request body.",
  "errors": [
    {
      "code": "too_big",
      "maximum": 2500,
      "type": "number",
      "inclusive": true,
      "exact": false,
      "message": "Basis points cannot exceed 2500 (25%)",
      "path": [
        "developerSpreadFeeBps"
      ]
    }
  ]
}

{
  "error": "Unauthorized - Invalid or missing API key or session"
}
{
  "error": "Customers feature is not enabled for your organization"
}
{
  "error": "Invalid request data"
}
{
  "message": "Invalid media type."
}
{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "Internal server error"
}

Get developer fee balance GET

Returns your organization's current developer fee balance. This balance accumulates from fees charged on customer deposits and can be claimed to your organization's wallet. All three amounts read `"0"` until your organization's wallet is configured for claiming, even if fees have accrued.

Import a customer with a share token POST

Creates a customer from a share token generated in your Sumsub account. Verification steps the customer already completed carry over; the customer finishes the rest through the returned `kycFlowLink`. A selfie carries over only when your Sumsub level records it as a short video; otherwise the customer records one through the link. Share tokens are single-use. `idempotencyKey` is required unless `dryRun` is set; reuse it on retries so they return the same customer. If a retry under a new `idempotencyKey` finds the customer its first request created, it gets `409 DUPLICATE_CUSTOMER` with `existingCustomerId`. If that earlier import isn't finished, the request finishes it and returns `201` for that customer, or `503` with `existingCustomerId`. Set `dryRun` to check a token without using it. Available only when share-token imports are enabled for your organization. Contact support to enable it.