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.
• 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. 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 lifecycleFull step-by-step flow

StatusesStatus table and integration notes

Webhookswithdrawal.statusChanged verification and payloads

Auto convertingCover a shortfall from other balances