Withdrawal Status Changed
Withdrawal Status Changed documentation for Compose Finance APIs and integrations.
Triggered when withdrawal status changes (PROCESSING, PROPOSED, PARTIALLY_SIGNED, COMPLETED, FAILED, CANCELLED, EXPIRED, PENDING_REVERSAL, REVERSED). A withdrawal the recipient's bank returns sends PENDING_REVERSAL, then REVERSED once refunded. A withdrawal Compose reverses before it completes or fails moves to FAILED and sends this event.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
Example Requests
/withdrawal.status_changedWithdrawal Created Webhook
Triggered when a withdrawal request is created.
Create customer withdrawal POST
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, EURC and AUDD (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`. A withdrawal that fails after it was recorded, such as one with an insufficient custodial balance, is kept as `FAILED` and sends `withdrawal.created` and `withdrawal.status_changed` with status `FAILED`; retrying with the same `idempotencyKey` returns that record. The error response then carries its `transactionId` and `status`. **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 whose bank payment fails moves to `FAILED`. A custodial balance is refunded automatically. A wallet withdrawal is refunded on-chain. One the recipient's bank returns, before or after `COMPLETED`, moves to `PENDING_REVERSAL` and then to `REVERSED`: it is refunded to the balance or wallet it was paid from, less the reversal fee converted at the withdrawal's exchange rate; `reversal` shows the fee and the refund. Each status change sends `withdrawal.status_changed`. 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, USDT or AUDD: EURC returns `400`, as does an AUD withdrawal bank when AUD functionality is not enabled for your organization. AUDD is paid out only as AUD, to AUD withdrawal banks, at a rate of 1 unless a spread applies; the fee is returned in `fee`. AUDD to a EUR or USD account returns `400`, and an organization without the AUDD balance enabled gets `403`. **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`.

