Payouts

Non-custodial payout orchestration

billing.io payouts are an orchestration layer for your outbound payments. You execute the on-chain transaction from your own wallet — billing.io tracks intent, verifies settlement, and reconciles.

billing.io never moves crypto on your behalf. This preserves the non-custodial model while giving you full reconciliation and audit capabilities.

Payout orchestration is available on Scale plans and above.

---

How it works

1. Create a payout intent describing what you plan to send
2. Approve the intent (review workflow)
3. Execute the transfer from your wallet using any tool you prefer
4. Submit the transaction hash to billing.io
5. billing.io verifies the transaction on-chain via the chain-watcher
6. Settlement recorded — reconciliation entry created automatically

---

Payout intent lifecycle

draft

Created but not yet approved. Use this state to queue payouts for review.

approved

Reviewed and approved. Ready for on-chain execution.

executed

Transaction hash submitted. Chain-watcher begins monitoring.

verifying

Transaction detected on-chain. Waiting for required block confirmations.

settled

Confirmed on-chain with sufficient confirmations. Settlement record created.

failed

Transaction failed, was not found, or was reverted. Create a new intent to retry.

canceled

Canceled before execution. No on-chain activity occurred.

---

Settlement verification

After a transaction hash is submitted, the chain-watcher automatically:

1. Detects the transaction

   Monitors the blockchain for the submitted hash. Payout moves to verifying.

2. Counts confirmations

   Tracks block confirmations until the required threshold is met.

3. Creates settlement record

   Records block number, confirmation count, atomic amount, and timestamps.

4. Updates payout intent

   Status moves to settled. A revenue event is created for the settlement.

---

Reconciliation

Reconciliation matches payout intents to their on-chain settlements. billing.io reconciles automatically, and provides a view for auditing.

Category	Description
Matched	Intent has a corresponding settlement with matching amount and recipient
Unmatched	Intent exists but no settlement recorded yet
Discrepancy	Settlement exists but amount or details do not match the original intent

Discrepancies can occur due to token transfer fees on certain chains. Review discrepancies in the dashboard under Payouts > Reconciliation.

---

Code examples

See the Payout Orchestration guide for complete step-by-step implementation with code in cURL, Node.js, and Python.

Create a payout intent

curl

curl -X POST https://api.billing.io/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_address": "TXyz1234567890abcdef",
    "chain": "tron",
    "token": "USDT",
    "amount": 500.00,
    "currency": "USD",
    "reference_type": "invoice",
    "reference_id": "inv_abc123"
  }'

For high-volume operations, create payout intents in bulk via the API and batch your on-chain transactions. Submit each tx hash individually to maintain a clean 1:1 mapping between intents and settlements.