High-level explanation of basic Web3 Payment concepts.
The (payment) attempt starts as soon a user clicks something which will lead to a payment screen or opens the payment widget.
Each attempt needs to have its own
If a payment fails, a new attempt needs to be created, including assigning a new
secret_id to the new attempt.
A trace will be recorded right before the widget hands over the payment transaction to the user's wallet.
A trace makes sure that a payment will be tracked even if the tracking of the payment after payment submission (to the blockchain) should fail.
If a trace is not submitted succesfully, the widget shows an error message and will not allow the user to submit the payment.
The actual payment will be tracked as soon as:
The user's wallet reports the submitted
transaction_idback to the payment widget which will report it to your app which will need to send it to the DePay API.
The payment trace (recorded prior to submitting the payment) finds a matching payment on the blockchain and converts it to a tracked payment.
Trace to Payment Conversion
In case the payment tracking after payment submission (to the blockchain) fails, this is the flow of how a trace is converted to a payment:
As soon as the widget detects a failed transaction it will report the failed transaction to your app via
failed callback, shows the user a "failed transaction" screen, asks the user to retry the payment and releases the users back to your app.
Your app needs to create a new attempt with a new
secret_id if a payment failed. Users can retry the payment without waiting for the previous payment validation to happen. None the less the failed transaction will be reported via callback, and you should change the state of that payment attempt accordingly.