Payment Confirmation Policies for Blockchain Apps
Choose blockchain payment confirmation rules with network finality, event validation and workflow states, instead of treating submission as settlement.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A payment workflow needs more than a transaction hash. It must establish that the intended asset reached the intended recipient and that the accepted chain evidence meets the chosen settlement policy.
Define the acceptance contract
Validate network, asset, recipient and amount before applying confirmations. State whether settlement uses a block-depth rule, a consensus checkpoint or another network-specific policy. Do not copy one chain’s confirmation count to every network. Submission, inclusion and settlement should appear as separate workflow states.
Worked example: inclusion without settlement
A monitor finds a valid transfer in the latest block and marks the invoice observed. Its policy waits for a chosen checkpoint before marking it settled. If the transfer leaves the accepted chain before then, the invoice returns to an unresolved state rather than retaining an unsupported paid label.
Make transitions idempotent
Use durable payment and event identities, and avoid issuing duplicate fulfilment when a webhook repeats. Test wrong-network transfers, partial amounts and reorganisation rollback. A timeout is not proof of failure or refund. Preserve manual-review paths for ambiguous evidence instead of automatically repeating irreversible fulfilment.
A practical acceptance test
Provide a valid token transfer below the chosen settlement boundary, then advance the accepted checkpoint. Assert observed before settled and fulfilment only once. Replace the provisional block before settlement in a second case. The invoice should return to unresolved without inventing a refund or repeating an external action automatically.
Questions about the topic
Frequently asked questions
Is a submitted hash a settled payment?
No. Submission does not establish accepted execution.
Should every network use the same confirmation count?
No. Settlement assumptions are network-specific.
Standards & technical documentation
