# Payment flow

A card-on-file subscription starts when a buyer enters their card at checkout, on
the payment provider's hosted card window ([Stripe Connect or OnPay/Nets-Dankort](/guides/card-payments#the-two-rails)).
Your page never touches card data. Two facts shape the flow: the card is **saved
first, not charged**, and the subscription goes live only once the **first
payment clears**. The payment provider stores the card and moves the money;
LedgerBee's billing engine decides the amount, runs the charge, and sends every
buyer email.

This is the signup path, from card entry to a new live subscription. For ongoing
cycle billing, retries, dunning, and the full set of buyer emails, see
[Card payments](/guides/card-payments). For how the card is captured in an iframe
on your own site, see [Embedded Checkout](/guides/embedded-checkout/overview).

## The sequence

1. **The buyer enters their card.** It opens on the provider's hosted window
   inside the checkout. The card is saved, not charged — no money moves and no
   hold is placed. American Express is rejected here; it cannot back a
   subscription on either rail.
2. **The provider confirms the card is stored.** LedgerBee holds the saved card
   against the pending purchase. No customer or subscription exists yet for an
   anonymous checkout — the buyer has not confirmed.
3. **The buyer confirms the purchase** — by clicking the magic-link email
   (anonymous checkout) or directly if they are already signed in. This is the
   point the purchase becomes real.
4. **LedgerBee finalizes and charges.** It creates the customer and attaches the
   saved card, creates the subscription in a **pending-payment** state that
   grants no access yet, cuts the first invoice, and charges the saved card
   off-session for the exact first-period amount. A built-in guard ensures the
   card is charged once, even if the step is retried.

## If the first charge clears

- The subscription flips to **active** (or to a trial, if the plan has trial
  days) and access is granted.
- The invoice is marked paid and a receipt is produced.
- The buyer receives the enrollment confirmation and the paid receipt (the
  receipt rides on the invoice email). See [Card payments](/guides/card-payments#buyer-emails)
  for every email and its timing.
- A charge-cleared subscription webhook fires — the signal to grant or confirm
  access in your own system. Fulfill on the webhook, not the browser redirect;
  see [Fulfillment](/guides/embedded-checkout/fulfillment).

## If the first charge fails

- The subscription stays in pending-payment and no access is granted.
- When a signup's first charge never clears, the checkout never became a live
  subscription, so a cleanup job cancels the stranded record after a grace
  period. Nothing was granted, so nothing is revoked.
- The buyer gets a failed-charge email and the charge retries automatically. The
  retry-and-dunning sequence is identical on both rails — see
  [Failed charges & the grace window](/guides/card-payments#failed-charges--the-grace-window).

## Who does what

| The payment provider (Stripe / OnPay) | LedgerBee |
| --- | --- |
| Hosts the card window and stores the saved card. | Decides when and how much to charge. |
| Moves the money on each off-session charge. | Cuts invoices, produces receipts, and activates the subscription on a cleared payment. |
| Sends no buyer emails. | Sends every buyer email (enrollment, receipt, failed-charge, dunning, cancellation). |

Because LedgerBee sends every buyer email, keep any provider-side customer-email
setting off so the buyer is not sent a duplicate.

The subscription this flow creates is an ordinary LedgerBee subscription — read,
update, and cancel it on its stable id, and mirror its lifecycle through
[subscription webhooks](/guides/webhooks). See [Subscriptions](/guides/subscriptions/overview)
for the underlying model.