# Withdrawals

A withdrawal pays funds out of a merchant balance to an external wallet. You create it through the **API** or the **admin panel**.

Through the API, request a **quote** (`POST /withdrawal/quote`), then **commit** it (`POST /withdrawal/commit`). Commit debits your balance and Cryptonly sends the transfer on-chain.

Withdrawal amounts are set by you in **crypto**, along with the destination wallet address. The network fee from the quote is debited together with the amount.

## Quote and commit

* **Quote** returns a fee estimate and a short-lived `quoteId`. Set `allowAutoConvert: true` to cover a shortfall from other balances — see [Auto converting](https://docs.cryptonly.net/guides/withdrawals/auto-converting.md).
* **Commit** creates the withdrawal in `created` and debits the amount plus the network fee.
* `orderId` on the quote is the idempotency key. Reuse it when retrying the quote, then commit once you have a `quoteId`.

## How status and webhooks work

Withdrawals have [statuses](https://docs.cryptonly.net/guides/withdrawals/statuses.md). Cryptonly sends a signed `withdrawal.statusChanged` webhook when the withdrawal **status** changes after commit.

Important behaviors for integrators:

* The commit response returns `created`. The balance, including the network fee, is already debited. The first webhook typically arrives when the withdrawal moves to `processing`.
* From `processing`, the withdrawal finishes as `completed` or `failed`.
* On `failed`, the debited balance is returned.
* Treat `completed` and `failed` as the final outcomes. `cancelled` is in the status enum, but current flows do not emit it.

## Related pages

- [Processing lifecycle](https://docs.cryptonly.net/guides/withdrawals/withdrawals-lifecycle.md): Full step-by-step flow
- [Statuses](https://docs.cryptonly.net/guides/withdrawals/statuses.md): Status table and integration notes
- [Webhooks](https://docs.cryptonly.net/api-reference/webhooks.md): withdrawal.statusChanged verification and payloads
- [Auto converting](https://docs.cryptonly.net/guides/withdrawals/auto-converting.md): Cover a shortfall from other balances