Finality

A Solana transaction is confirmed first and finalized later. A confirmed block can still be rolled back; a finalized transfer cannot be reversed. Fianto uses both steps, for different readers: the payer is shown success at confirmed, and you are told only at finalized.

Scroll sideways to see the whole diagram →

Show as text

1. From your server, create a session with `POST /v1/checkout-sessions`. The first create returns its `url`; creating again for the same open order returns `url: null`, so reissue the link instead.
2. Send the payer to that `url`: Fianto's hosted checkout page.
3. The payer's wallet signs the transaction. The wallet only signs; it does not send.
4. The checkout page hands the signed transaction to Fianto.
5. Fianto broadcasts it to Solana, and rebroadcasts it when needed.
6. When the transaction is confirmed, Fianto tells the checkout page, which shows the payer success. The order is not `PAID` yet.
7. When it is finalized, the order becomes `PAID`, the payment `SUCCEEDED`, and Fianto sends `order.paid` and `checkout.session.completed` to your webhook endpoint — only at finalized.

What happens at each stepCopy Anchor Link

The payer's wallet only signs. Fianto broadcasts the signed transaction to Solana, rebroadcasts it when needed, and follows it.

At confirmed, the payer's receipt reads "Confirmed on Solana" and says the shop is told once Solana finalizes it. A payment can still fail after it was confirmed, so a CONFIRMED payment is not yet money you can count on.

Why webhooks wait for finalizedCopy Anchor Link

Fianto sends order.paid and checkout.session.completed only once the payment is finalized, because a confirmed block can still be rolled back. So order.paid and checkout.session.completed are always about a transfer that cannot be reversed. The dashboard says the same about a SUCCEEDED payment: "Finalized on Solana. The money is in your wallet and the transfer cannot be reversed."

Subscriptions follow the same rule: Fianto sends subscription.created when the subscribe transaction finalizes.

The payer's success screen is not your proofCopy Anchor Link

None of what the payer's side sees waits for finalized: the success screen, the redirect to your success_url about 3 seconds later, and in popup mode the message the page posts to your success_url origin with status: 'succeeded'. None of them proves you were paid.

A payment can also finalize after its session has closed. See Payment lifecycle for what the order and the webhooks do then.

See alsoCopy Anchor Link