Manage balance
Use the balance and fees reference to check available funds, configured deposit addresses, and deposit fees before creating a purchase or sending a deposit. This guide explains how to interpret the amounts; the first API request does not require funds.
Read available funds
available is the amount currently available to spend. on_hold reports funds tied to
in-flight purchases. A successful purchase consumes its actual price; its movement out of
on_hold does not mean that amount returns to available.
For example, start with $100 available. An $18.40 purchase approved with max_price: 20
leaves $81.60 available and contributes $18.40 to the in-flight amount. Successful completion
clears that in-flight amount while available remains $81.60. A confirmed full refund of that
purchase restores the $18.40. Other concurrent activity can change these totals.
Read the latest balance to reconcile funds. Do not calculate spendable balance by treating all terminal purchase states as refunds or by adding every delivered webhook amount.
Deposit funds
Use the address and network returned for your account, and check the current fee response.
Track the deposit in the merchant cabinet. Receipt is confirmed by balance.deposited.
See the deposit event.
The cabinet shows Whitepay and existing Heleket addresses separately. Whitepay issuance
is disabled by default. Read wallet availability
before requesting an address; only send to a Whitepay address with can_deposit: true.
After an interrupted creation request, refresh the saved state and reconcile that request.
Do not create a replacement. Include the memo/tag when shown; it is not part of the QR.
Amounts in deposit notifications are not a stream of unique credits merely because their
event IDs differ. Use the provider deposit identity (provider, provider_uuid) for business deduplication
when applying a deposit credit. The same event ID identifies delivery duplicates.
Reconcile a discrepancy
- Read the current balance and the relevant purchase details/history.
- Check the webhook delivery log for notifications that reached the retry limit or failed permanently.
- Follow delivery recovery when a stored notification needs attention.
Webhooks have bounded delivery attempts. They are notifications, not a complete balance ledger or a guarantee that every state change can be recovered through event replay.