Payment Methods

Configure how you receive crypto payments

A payment method is the receiving rail for your crypto payments. It tells billing.io which blockchain, token, and wallet to use when a customer pays you.

billing.io applies sensible, chain-specific defaults. Most users never need to change advanced settings.

Funds go directly to your wallet. billing.io is non-custodial — it monitors the blockchain and confirms payments, but never holds your crypto.

---

How it works

A payment method combines three things into a single resource:

1. Chain — which blockchain network (Tron, Arbitrum, or Base)
2. Token — which stablecoin (USDT or USDC)
3. Wallet — which receiving address on that chain

When a customer pays, billing.io routes the payment to the wallet defined by the payment method and monitors the blockchain until the transaction is confirmed.

---

Configuration

Field	Type	Description
chain	string	Blockchain network: tron, arbitrum, or base
token	string	Stablecoin: USDT or USDC
wallet_id	string	Reference to your registered wallet
display_name	string	Human-readable label (e.g., “USDT on Tron”)
min_amount_usd	number	Minimum payment amount in USD (optional)
max_amount_usd	number	Maximum payment amount in USD (optional)
is_default	boolean	Whether this is the default payment method
status	string	active or disabled

---

Default payment method

One payment method can be marked as the default. It is used automatically when a checkout, payment link, or subscription does not specify a payment_method_id.

Setting a new default unsets the previous one.

---

Wallets vs. payment methods

A wallet is a blockchain address you own — register it once under Settings > Wallets. A payment method is a configured receiving rail built on top of a wallet.

One wallet can back multiple payment methods. For example, a single Tron wallet could have one payment method for USDT and another for USDC, each with different amount limits.

---

Status lifecycle

Status	Behavior
active	Available for new checkouts and subscriptions
disabled	Cannot be used for new checkouts. In-flight payments continue to settle normally.

---

Advanced Security & Finality Settings

The fields below control blockchain-level confirmation behavior. billing.io sets safe defaults per chain — most integrations do not need to change these.

required_confirmations

The number of block confirmations billing.io waits before marking a payment as final. Higher values reduce the risk of chain reorganizations reversing a transaction.

Chain	Default	Approximate Time
Tron	20 blocks	~60 seconds
Arbitrum	12 blocks	~3 seconds
Base	12 blocks	~24 seconds

Lowering required_confirmations increases speed but reduces finality assurance. Transactions with fewer confirmations have a higher probability of being reversed during a chain reorganization. Only change this if you understand the trade-off between speed and settlement safety.

Chain reorganization risk

A chain reorganization (re-org) occurs when the blockchain rewrites recent history, potentially reversing confirmed transactions. The default confirmation thresholds are set to make re-org risk negligible for each supported chain.

• Tron: Delegated Proof of Stake with 27 super representatives. 20 confirmations provides strong finality.
• Arbitrum: Optimistic rollup anchored to Ethereum. 12 L2 confirmations is conservative for typical transactions.
• Base: Optimistic rollup anchored to Ethereum. Same model as Arbitrum.

If your use case involves high-value transactions and you want maximum safety, you can increase the confirmation threshold above the default.

---

Code examples

Create a payment method

curl

curl -X POST https://api.billing.io/v1/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "token": "USDT",
    "wallet_id": "wal_abc123",
    "display_name": "USDT on Tron",
    "is_default": true
  }'

List payment methods

curl

curl https://api.billing.io/v1/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY"

Set as default

curl

curl -X POST https://api.billing.io/v1/payment-methods/pm_a1b2c3d4e5f6/default \
  -H "Authorization: Bearer YOUR_API_KEY"

Disable a payment method

curl

curl -X PATCH https://api.billing.io/v1/payment-methods/pm_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Best practices

One method per chain-token pair

Keep your configuration clean with one payment method per chain and token combination.

Set amount limits

Use min_amount_usd to avoid dust payments and max_amount_usd to limit exposure per transaction.

Always have a default

A default payment method prevents errors when checkouts or subscriptions are created without specifying one.

Use display names

Clear display_name values help your team identify payment methods in the dashboard.