Checkout flow

vantezzen/pay keeps checkout wiring small in your app.

The user flow

1. The user clicks PurchaseButton.
2. PurchaseDialog lists the matching prices configured in vantezzen/pay.
3. The user picks a package.
4. The client calls createCheckout(priceId).
5. vantezzen/pay creates a Stripe or Polar checkout and returns the checkout URL.
6. Desktop users complete checkout in a popup; mobile/touch users redirect.
7. The provider sends a webhook to vantezzen/pay after payment.
8. vantezzen/pay credits the wallet.
9. The original page or returning page refreshes the balance.

Why webhooks matter

The webhook is the source of truth for payment. Do not grant credits just because a browser returns from checkout. A user can close the tab, refresh the page, or return before the provider has fully settled the payment.

vantezzen/pay verifies the provider webhook, finds the order, and grants credits idempotently. Retried webhooks do not duplicate credits.

Checkout return handling

The default components handle the return path:

• PurchaseDialog stores the pending order id in localStorage.
• Popup checkout keeps your page mounted and polls the order while the customer pays.
• Redirect checkout is resumed by PayProvider when the user returns.
• The provider context polls until the order is paid, failed, refunded, or the popup is closed.
• When the order is paid, it stores the issued code and refreshes balances.

That means most apps do not need a custom checkout callback page. If your server needs to react to payments, use consumer webhooks.

Refunds and subscriptions

Refund events reverse the original credit grant. Subscription renewals grant the same number of credits as the original subscription price. Cancellation events are recorded but do not remove credits already granted for paid periods.