Payment lifecycle

A one-time checkout involves three records. The checkout session is the payment link your server creates. The order is what your server asked the payer to pay, keyed by your order_id. A payment is one transaction the payer signed, which Fianto broadcasts to Solana and follows until it is final. Each has its own statuses, and they move together only at a few points.

Scroll sideways to see the whole diagram →

Show as text

1. Order: `PENDING` → `PAID` at finalized, or `PENDING` → `EXPIRED` when its session expires.
2. `EXPIRED` → `PAID` when a late payment still settles.
3. `EXPIRED` → `PENDING` when you create a new session with the same `order_id`.
4. A cancelled session leaves the order `PENDING`. An order is never `CANCELED`.
5. Payment: `PROCESSING` → `CONFIRMED` → `SUCCEEDED` at finalized.
6. A payment can fail from `PROCESSING` or `CONFIRMED`, and `FAILED` → `PROCESSING` if the transfer lands after all.
7. A payment whose session was superseded (a newer session for the order, or changed order terms) is recorded `FAILED` at finalized, even though its funds landed. It never shows as `SUCCEEDED` first.
8. Payments found by the reference sweep start at `CONFIRMED`.
9. `SUCCEEDED` is final. `EXPIRED` and `FAILED` are not.

Checkout sessionCopy Anchor Link

Sessions of both modes, payment and subscription, use these statuses. A session starts OPEN and leaves it once.

A session can be cancelled only while it is OPEN with no live payment. Fianto also cancels an OPEN subscription session itself when its link is outdated, because your receiving wallet or the treasury changed since the session took its snapshot of the plan: the payer's attempt is refused with checkout_link_outdated, and checkout.session.canceled is sent.

OrderCopy Anchor Link

A subscription session creates no order; only payment-mode sessions have one.

The moves are:

• PENDING → PAID when a payment finalizes.
• PENDING → EXPIRED when its session expires.
• EXPIRED → PAID when a late payment still settles.
• EXPIRED → PENDING when your server creates a new session with the same order_id. The order takes the new request's terms. A cancelled session's order is reused the same way.

Only a PAID order refuses a new session, with 409 order_already_paid. No status is ever written to an order for a cancel: the order simply stays PENDING.

PaymentCopy Anchor Link

The moves are:

• PROCESSING → CONFIRMED → SUCCEEDED.
• PROCESSING or CONFIRMED → FAILED.
• FAILED → PROCESSING when the transfer lands after all.

A payment whose session was superseded, by a newer session for the same order or by changed order terms, is recorded FAILED at finalized, even though its funds landed. It is never shown as SUCCEEDED first: Fianto decides this in the same step that settles the payment. SUCCEEDED is final.

Neither EXPIRED (order) nor FAILED (payment) is final, so keep your webhook route listening after each of them.

Where the three meetCopy Anchor Link

• At finalized. The payment becomes SUCCEEDED and the order PAID, and Fianto sends order.paid. When the session was still OPEN, it becomes COMPLETED and Fianto also sends checkout.session.completed. Nothing of this happens at confirmed; see Finality.
• A payment for a closed session. A payment that finalizes after its session EXPIRED or was CANCELED still pays the order: PAID and order.paid, but no checkout.session.completed. If a newer session was opened for the order in the meantime, the payment is FAILED instead, with its funds landed.

The expiry sweepCopy Anchor Link

Every 30 seconds Fianto expires OPEN sessions whose time has run out. A payment in flight keeps a session from expiring. An expired session sends checkout.session.expired, and its order becomes EXPIRED and sends order.expired.

A session can also lapse without the sweep having reached it. When your server then creates a new session for the same order_id, the lapsed one is expired and replaced: it still sends checkout.session.expired, but there is no order.expired, because the order is reopened for the new session.

The reference sweepCopy Anchor Link

Every session has a reference, and the transfer of the price carries it. Every 60 seconds Fianto looks for transfers with the reference of each open session, and keeps looking for 24 hours after a session closes. This catches transfers that Fianto did not broadcast itself. A payment found this way starts at CONFIRMED.

A transfer that carries a session's reference but is not that session's payment is recorded on the order. Every such transfer is recorded as an unmatched transfer; Fianto also sends order.duplicate_payment when the order is already PAID or has another payment that has not failed. Its duplicate names that transfer's signature and amount. Otherwise no webhook is sent. Fianto records up to 20 unmatched transfers per session and ignores any beyond that.

See alsoCopy Anchor Link