Withdrawals
Pay a customer from your balance. There is no checkout popup — your CRM calls the API.
Available balance
Paid orders credit your balance in the asset the customer paid, on the network they used. Read it with GET /v1/balance: assets lists each asset and network with what is available in your main wallet and what is collectible (received, not collected yet); the top-level available is the same in USD. Available is the main wallet balance less withdrawals already being sent and less fees owed to Bytix. A withdrawal of USDT on Tron is covered by the available USDT on Tron only, and is held from it until the merchant approves or rejects it. You cannot overdraw: create returns 40001 (HTTP 409) with the available amount in the message.
Your account may also have limits: a maximum per withdrawal, a total per UTC day, and an amount under which withdrawals are approved automatically without waiting for staff. They are listed under Settings → Developer. A withdrawal outside a limit returns 40003.
Payout wallets
Customer withdrawals must go to a destination the merchant has approved. Submit an address with POST /v1/payout-wallets (payer_id, address, asset, network). Invalid addresses on that network are rejected immediately. Valid addresses stay pending until the merchant approves or rejects them in the dashboard under Withdrawals → Whitelisted wallets. A customer wallet can also be added there by hand (Add wallet, with the customer ID); Bytix reviews those before they turn approved, and they are listed here like any other. When wallet screening is enabled for your workspace, each new address gets a risk check first and the dashboard shows the result before it can be approved; the API does not change. List with GET /v1/payout-wallets. Create the payout only after status is approved for that payer_id, address, asset and network; the payout must use the same payer_id.
Create
POST https://api.bytix.ai/v1/payouts with a unique payout_id per workspace. Amounts are USD decimal strings. asset and network must match a row in data.payout_coins from GET /v1/coins (ticker + network name). A new payout returns awaiting_approval until a merchant approves it in the dashboard Withdrawals list, or it is approved automatically under your auto-approve limit. At approval Bytix checks the main wallet's live balance on the blockchain: the asset must be there (less withdrawals already on their way), and enough of the native coin for the network fee; otherwise approval is refused with 40001 or 40002, or with 50300 when the balance cannot be read at that moment, and the payout stays awaiting_approval until it is approved again. Rejection returns the held amount to the balance.
curl -X POST "https://api.bytix.ai/v1/payouts" \
-H "Authorization: Bearer pk_..." \
-H "Content-Type: application/json" \
-d '{
"payout_id": "wd_001",
"amount": "25.00",
"asset": "USDT",
"network": "Tron",
"address": "T...",
"payer_id": "user_1001"
}'Confirm
- Handle
payout.awaiting_approval, thenpayout.pendingon approval,payout.submittedwhen it is sent, thenpayout.completedorpayout.failed. A decline ispayout.rejected. Ack with the plain text bodysuccess. See Webhooks. - Or poll POST /v1/payouts/info with
payout_id.
On failed or rejected, the held amount returns to the balance. Treat only completed as money left the merchant.
Errors
| Code | Typical cause |
|---|---|
40000 | Missing fields, amount ≤ 0, unknown asset/network, invalid address, unapproved wallet |
40001 | HTTP 409. Not enough of that asset on that network in the main wallet (also on approval, from its live balance) |
40002 | HTTP 409, on approval. Not enough native coin in the main wallet for the network fee |
40003 | Above the maximum withdrawal or the daily withdrawal limit of your account |
40100 | Missing or invalid API key |
40400 | Query with an unknown payout_id |
50300 | HTTP 503. Your wallets are still being prepared, or a live balance could not be checked right now |