Create customer withdrawal

Server URLloading...

POST

/api/v2/customers/{customerId}/withdrawal

Send

Authorization

Path

Body

Creates a withdrawal to the customer's registered bank account.

Prerequisites

API withdrawals must be enabled for your organization. If not enabled, this endpoint returns 403 Forbidden. Contact support to enable API withdrawals.

This endpoint requires an API key. Browser-session withdrawals must use the dashboard approval flow.

Execution Modes

1. Automatic Execution (PROCESSING) — Withdrawal executes immediately when:

   • Sufficient available allowance
   • Sufficient USDC balance in wallet

2. Manual Approval (PROPOSED) — Transaction created for dashboard approval when:

   • Withdrawal exceeds available allowance
   • Insufficient USDC balance in wallet (user can deposit funds before signing)
   • Automatic execution fails (transaction converted to manual approval)

PROPOSED is only used when the on-chain allowance module is configured. If API withdrawals are enabled but the module or delegate is not configured on your Safe, or the allowance cannot be read, the request fails with 500 {"error": "Failed to execute withdrawal"}. If your organization has no Safe wallet, wallet USDC withdrawals fail with 404 (custodial withdrawals do not need a Safe). GET /customers/withdrawal/allowance returns enabled: false in these cases.

Custodial Balances

USDT and EURC (and USDC when source is custodial) are held on the customer's custodial balance rather than the wallet. These withdrawals are debited and paid out immediately (PROCESSING) when the organization has custodial balances and API withdrawals enabled. There is no manual-approval fallback: an insufficient custodial balance returns 400, and a disabled feature returns 403.

AUD Withdrawals

AUD-only customers withdraw to their AUD withdrawal banks (paymentRail: "AU_BANK_TRANSFER") from the wallet or a custodial balance when AUD functionality is enabled for your organization; the customer does not need to be KYC verified, and the account must be active. The withdrawal stays PROCESSING until the bank payment settles. A withdrawal that reached COMPLETED can later move to FAILED if the receiving bank returns the payment; a withdrawal.status_changed webhook is sent. Standard customers cannot withdraw to AUD withdrawal banks, and AUD-only customers still get 400 for EUR and USD accounts. AUD withdrawals are funded with USDC or USDT only: EURC returns 400, as does an AUD withdrawal bank when AUD functionality is not enabled for your organization.

Amount Specification

Specify the withdrawal amount using one of:

• sourceAmount: Amount in the source currency to withdraw
• targetAmount: Amount to receive in the bank's currency

The target currency is automatically determined by the withdrawal bank's configured currency.

Idempotency

Use the idempotencyKey to safely retry requests. Duplicate requests with the same key return the original transaction without creating a new one. Reusing a key for a different customer returns 409.

Path Parameters

Response Body

curl -X POST 'https://compose.finance/api/v2/customers/{customerId}/withdrawal' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Content-Type: application/json' \  -d '{    "withdrawalBankId": "bank_123abc",    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440001",    "targetAmount": "850"  }'

{
  "id": "txn_abc123",
  "type": "WITHDRAWAL",
  "status": "PROCESSING",
  "requiresUiAction": false,
  "paymentRail": "SEPA",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "completedAt": null,
  "reference": null,
  "sourceCurrency": "USDC",
  "targetCurrency": "EUR",
  "sourceAmount": "1000",
  "targetAmount": "862.5",
  "exchangeRate": "0.865",
  "fee": "2.5",
  "withdrawalBank": {
    "id": "bank_123abc",
    "beneficiaryName": "JOHN DOE",
    "currency": "EUR",
    "paymentRail": "SEPA",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  },
  "walletAddress": null,
  "developerFee": null,
  "txHash": null
}

{
  "message": "Invalid request body.",
  "errors": [
    {
      "code": "custom",
      "message": "Provide either 'sourceAmount' or 'targetAmount' (amount in bank currency)",
      "path": []
    }
  ]
}

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

{
  "error": "API withdrawals are not enabled for this organization"
}

{
  "error": "Customer not found"
}

{
  "error": "Idempotency key already used for a different customer"
}

{
  "message": "Invalid media type."
}

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "Internal server error"
}

{
  "error": "Exchange rate temporarily unavailable"
}