Custom Payment Flow Webhooks (ticker)

Delivery & security

• Webhooks are sent to the callback_url configured for the invoice (or project), with all your original query parameters preserved.
• HTTP method: GET by default, POST when the invoice was created with post=1.
• Content type: application/x-www-form-urlencoded by default, application/json when the invoice was created with json=1.
• Webhooks are signed using HMAC-SHA256 with your project’s ipn_secret. Always verify the signature before trusting the payload.

Behaviour

• payment_status=pending — UTXO, EVM or TRON payment detected, awaiting the required confirmations or execution checks. Reports observed progress; counts may jump.
• payment_status=confirmed — incoming threshold reached. The payment counts toward the invoice.
• payment_status=completed — distribution sent to the network. This does not credit the payment a second time or guarantee outgoing confirmation.
• confirmations is the observed count; required_confirmations is the merchant threshold. A threshold of one can skip pending. Progress updates stop after confirmed.
• Solana sends confirmed and completed only. Both confirmation fields are 1, representing the accepted network stage, not slot depth; custom numeric depth is not enforced. Native SOL uses finalized discovery; SPL uses confirmed discovery.
• TRON credit follows the configured threshold, but distribution waits for the higher of that threshold and 23 confirmations for TRX or 20 for TRC20, plus a successful solidified receipt. Setting 5 therefore credits at 5 and distributes later. Early credit does not guarantee finality or automatic reversal.
• Deduplicate by UUID and handle out-of-order events without regressing state. Missing forwarding amounts and fees in progress events are not zero amounts.
• All custom query parameters you added to callback_url when creating the payment (e.g. ?order_id=123&user_id=456) are echoed back in the webhook payload.

Key fields

• uuid — unique payment identifier. Use for idempotency.
• address_in — payment address the customer paid to.
• address_out — forwarding address(es) and percents.
• txid_in — customer’s blockchain transaction hash.
• txid_out — forwarding transaction hash, available on completed.
• coin — payment coin, e.g. btc, trc20_usdt.
• price — coin price in USD at the time of webhook.
• confirmations — observed incoming confirmation count; on Solana, 1 denotes the accepted network stage.
• payment_status — pending, confirmed, or completed; replaces numeric pending.
• value_coin — paid amount in coin (before fees).
• value_forwarded_coin — amount forwarded after fees.
• fee_coin — service fee in the payment currency (coin or token units), excluding blockchain network fees. network_fee reports the separate network-cost deduction in the payment currency (not necessarily the final on-chain cost); unknown historical values are null.