BxBytix

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.

bash
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

  1. Handle payout.awaiting_approval, then payout.pending on approval, payout.submitted when it is sent, then payout.completed or payout.failed. A decline is payout.rejected. Ack with the plain text body success. See Webhooks.
  2. 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

CodeTypical cause
40000Missing fields, amount ≤ 0, unknown asset/network, invalid address, unapproved wallet
40001HTTP 409. Not enough of that asset on that network in the main wallet (also on approval, from its live balance)
40002HTTP 409, on approval. Not enough native coin in the main wallet for the network fee
40003Above the maximum withdrawal or the daily withdrawal limit of your account
40100Missing or invalid API key
40400Query with an unknown payout_id
50300HTTP 503. Your wallets are still being prepared, or a live balance could not be checked right now