Concepts

High-level explanation of basic Web3 Payment concepts.

Attempt

The (payment) attempt starts as soon a user clicks something which will lead to a payment screen or opens the payment widget.

The attempt is supposed to carry the secret_id. The secret_id is needed to track and validate a payment.

Each attempt needs to have its own secret_id.

If a payment fails, a new attempt needs to be created, including assigning a new secret_id to the new attempt.

Trace

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.

Payment

The actual payment will be tracked as soon as:

1. The user's wallet reports the submitted transaction_id back to the payment widget which will report it to your app which will need to send it to the DePay API.

2. The payment trace (recorded prior to submitting the payment) finds a matching payment on the blockchain and converts it to a tracked payment.

Flow

Succesfull 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:

Failed 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.