Session Lifecycle

Every Croissant Pay transaction is represented by a session that moves through a series of states from creation to settlement.

State Machine

CREATED ──→ APPLIED ──→ AUTHORIZED ──→ CHARGED │ │ │ │ ▼ ▼ ▼ ▼ EXPIRED APPLY_FAILED AUTHORIZE_FAILED CHARGE_FAILED │ ▼ VOIDED

States

Created

A session is created when the customer clicks the Croissant Pay button on your site. The session contains the checkout URL, line items, available credit, and eligible incentives.

At this stage, the customer is on the Croissant hosted checkout and can choose their payment option — redeem credit, apply an incentive, or maximize earn-back.

Applied

After the customer selects a payment option, the discount amounts are applied to the session: credit amount, cash amount (what they pay via card), and any incentive amount.

A Stripe PaymentIntent is created to authorize the customer's card for the cash amount. The customer sees the Stripe payment form.

Authorized

The customer's card has been authorized (a hold, not a charge). The customer is redirected back to your checkout URL with the session in AUTHORIZED state.

For Shopify integrations, the checkout extension reads the session and applies discount functions automatically.

For custom integrations, this is when the customer returns to your site. You should display a confirmation/success state while waiting for the webhook.

Charged

The payment is captured and the session is complete. Croissant notifies your system via webhook (custom) or Shopify order flow.

Expired

Sessions have a TTL. If the customer does not complete the checkout flow before expiresAt, the session moves to EXPIRED. No payment is captured.

Voided

A session can be voided if the authorized payment needs to be released before capture — for example, if the customer cancels before the order is fulfilled. The card hold is released.

Failed States

Failure states indicate a problem at a specific step: card authorization failure, discount application error, or charge capture failure. These are terminal — the customer would need to start a new session.

Info

If a customer already has an active session, creating a new session returns a reference to the existing one along with its expiration time. The customer must complete or wait for the existing session to expire.

Session Data

Each session contains:

Field	Description
`id`	Unique session identifier
`status`	Current lifecycle state
`checkoutUrl`	URL to redirect the customer back to your site
`lineItems`	Products in the cart
`cashAmount`	Amount charged to card (cents)
`creditAmount`	Croissant credit applied (cents)
`incentiveAmount`	Incentive discount applied (cents)
`currency`	ISO currency code (e.g., USD)
`createdAt`	Session creation timestamp
`expiresAt`	Session expiration timestamp

Next: Shopify Integration →