Copy page

Products

Card payments

Card-on-file subscriptions are billed by LedgerBee's own billing engine. It decides when each cycle bills, computes the amount, charges the stored card with an off-session payment, and runs its own retry and dunning schedule. The payment provider only moves the money — it does not run the subscription.

LedgerBee sends every buyer-facing email: the enrollment confirmation, the advance pre-charge notice, the paid receipt, the failed-charge and dunning notices, the card-expiry and card-update notices, and the cancellation confirmation. Each one is transactional and fires only when its trigger applies; the timing of each follows a card-scheme or Danish/EU consumer-law rule, listed per email below. The payment provider sends none of these, so any provider-side customer-email setting should stay off to avoid sending the buyer a duplicate.

Card billing rides on the subscription system. For the underlying model — the stable chain id, versions, timeline, and lifecycle — see Subscriptions and Data model. A card is stored during Embedded Checkout or when an operator assigns a subscription with a saved card. Full request and response schemas live in the API Reference.

The two rails

A card-on-file subscription runs on one of two payment rails. The buyer never picks one; the tenant's connected provider stores the saved card as either a Stripe PaymentMethod or an OnPay/Nets-Dankort subscription token. The buyer emails, the daily card-expiry scan, the dunning and grace handling, and the receipt content are identical on both. Cycle charges are submitted as merchant-initiated recurring transactions on both, so the buyer's issuer sees a subscription payment rather than a one-off. The rails differ on three points an integrator can observe:

Axis	Stripe Connect	OnPay / Nets-Dankort
Statement descriptor	Set per charge (statement_descriptor_suffix, default SUBSCRIPTION). The full descriptor — account prefix plus suffix — is capped at 22 characters.	Derived by Nets and the acquirer from the merchant agreement; not set per charge.
Card-updater detection	Push. The provider sends an event when the card network silently refreshes a stored card; LedgerBee updates the card and emails the buyer in near-real-time.	Pull. LedgerBee re-checks the stored card with the provider after each cleared charge and before the daily expiry scan.
Expiry handling	The stored expiry stays current from the updater events, so the daily expiry scan reads it directly.	The stored expiry can lag a silent network renewal, so the daily scan re-checks with the provider before acting; if that check fails, it takes no expiry action that run.

Amex is blocked

American Express cannot be used for subscription card-on-file on either rail. A buyer who tries to save an Amex card gets a blocked-brand error at checkout and at card save; direct them to a different brand. Amex's recurring-billing rules require the cardholder to re-consent to terms changes, which an automated notice cannot satisfy. A stored card that the network later switches to an Amex number is refused at the next charge rather than billed.

Buyer emails

LedgerBee sends these automated emails to the buyer over the life of a card-on-file subscription. All are transactional — amount, date, subscription reference, a manage/cancel link, and the tenant's logo and name. Tenants cannot add promotional content.

Email	When it sends	Why (real-world rule)	Who receives it
Enrollment confirmation	Once, promptly after a card is stored for automatic billing (including zero-charge trial signups). Not tied to a charge.	Visa Europe recurring-agreement confirmation (within 2 business days); Dankort §29.2 subsequent written confirmation; consumer durable-medium contract confirmation.	All card-on-file buyers. A trial-disclosure block appears only for trial enrollments.
Pre-charge notice	Before an upcoming charge, on the effective charge date (below). One email covers up to four causes: trial conversion (first post-trial charge), infrequent cadence (longer than 6 months), amount change (the charge differs from the steady recurring amount), and terms change (a queued agreement change lands at or before the charge).	Visa Core Rules 7-day agreement-change and trial-conversion advance notice; Mastercard infrequent-transaction (over-6-month) advance reminder (7–30 day window); Danish consumer 8-day variable-amount floor; Visa variable-amount and metered disclosure.	All card-on-file buyers. The amount-change floor is 8 days for B2C (private person), 7 days for B2B. The trial-conversion cause applies only to trial subscriptions.
Paid receipt	At invoice dispatch, immediately after a charge settles. The receipt content rides on the invoice email, with the PDF attached.	Visa Core Rules receipt requirements; Mastercard recurring-receipt rules; Dankort/Nets recurring-receipt rules; Danish consumer-law receipt obligation. The content carries a paid-and-prepayment marker, a recurring-payment marker, the covered service period, the masked card, a portal cancel link, and — on the first paid charge after a free trial — a trial-conversion restatement.	All card-on-file buyers whose settled charge maps to a single subscription. A consolidated multi-subscription invoice gets a plain paid receipt instead.
Failed-charge notice — first decline	Immediately on the first decline of a card charge. Opens the grace and dunning window.	Consumer payment-failure disclosure and the card-scheme expectation that the buyer is told a recurring charge was declined and given a way to fix it.	All card-on-file buyers. The issuer decline reason is included only for trial subscriptions (a declined trial-conversion charge must state why); it is omitted otherwise.
Failed-charge notice — final	Once, when automatic retries are exhausted (after the grace floor — see Failed charges). Not re-sent on later manual retries.	Consumer final-disclosure and the card-scheme expectation that the buyer is told retries have stopped and the amount is now collected the normal way.	All card-on-file buyers whose retries are exhausted. Decline reason still trial-only; no retry is promised.
Card auto-update notice	Near-real-time when the card network's account-updater (or a manual edit at the provider) refreshes a stored card's type, mask, or expiry behind a live subscription. The buyer took no action; billing continues.	Dankort §30 — the cardholder must be told when a stored card is silently refreshed.	Buyers whose stored card backs at least one live subscription. One refresh sends one email even when the card backs several subscriptions; the subscription is named only when exactly one rides the card.
Cancellation confirmation	Immediately when a card-on-file subscription is cancelled.	Mastercard cancellation-acknowledgement (confirm within 7 days).	All card-on-file buyers. Copy differs for immediate versus end-of-cycle cancellation (access-until date). It confirms the card won't be charged again for this subscription; it does not claim the card was deleted.

Invoice-rail (non-card) subscriptions don't get the enrollment, pre-charge, failed-charge, or cancellation emails — those fire only for automatic card billing.

The effective charge date anchor

A pre-charge notice is timed off the effective charge date: the date the charge actually fires, which is nextBillingDate minus the subscription's send-offset days, not the calendar billing date. The send floor counts back from that date. A notice that covers more than one cause uses the latest floor among them — 7 days for trial-conversion and terms-change, a 7-to-30-day window for infrequent cadence, and 7 days (B2B) or 8 days (B2C) for an amount change. When the floor can't be met, such as a trial shorter than the floor, the notice sends as early as possible and a compliance-exception record is written (see Evidence & audit trail).

Failed charges & the grace window

A failed charge does not immediately end a subscription. LedgerBee runs a rail-agnostic dunning sequence with a 7-day grace floor before any adverse action.

1. First decline — the buyer gets the first-decline email with a portal link to update their card, and the subscription moves to AWAITING_PAYMENT.
2. Automatic retries — the charge retries automatically on a backoff schedule across the grace window. Only genuine declines count toward the retry cap; transient errors (5xx, timeouts) are retried without counting against it.
3. Grace floor — no adverse action (the final notice, finalizing the invoice as collectible, stopping retries) happens before a 7-day floor measured from the first failed attempt. Exhaustion requires both the retry cap and the elapsed 7 days, so a buyer who exhausts retries early — repeatedly hitting "pay now" in the portal — still gets the full grace window.
4. Exhaustion — once both hold, the subscription error topic fires once with errorType: dunning_exhausted, the buyer gets the final notice, the invoice is finalized as collectible (booked, numbered, and entered into the normal accounts-receivable flow of aging, payment reminders, and manual payment), and automatic retries stop. The subscription stays AWAITING_PAYMENT.

AWAITING_PAYMENT is a status, not an access cut. For a subscription that has been paid before, LedgerBee never cancels it over a failed charge — it sits in AWAITING_PAYMENT, with the unpaid invoice in accounts-receivable, until the buyer pays or you act. The one case LedgerBee does cancel is a pay-first signup whose first charge never clears: that checkout never became a live subscription, so a cleanup job cancels the stranded record after a grace period. Nothing was granted, so no access is revoked.

Entitlement is yours to control. The subscription error topic gives you two distinct signals to choose between: errorType: charge_failed fires on every decline (act on it to gate access the moment a charge fails), and errorType: dunning_exhausted fires once when retries are exhausted (act on it to keep the buyer in service through the grace window and gate only if payment never recovers). A cleared retry fires the payment-succeeded signal — the cue to restore. See Webhooks.

Retrying a failed charge yourself

The outstanding card invoice can be recharged on demand from three surfaces, all against the same saved card:

• The buyer, from the portal's "Pay now" on the failed subscription.
• An operator, from the subscription's billing documents in the LedgerBee app.
• You, over the API:

Code
curl -X POST "https://api.ledgerbee.com/api/v1/subscriptions/SUBSCRIPTION_ID/retry-payment" \
  -H "x-api-key: YOUR_API_KEY"

The subscription id is the stable id; there is no request body — the retry locates the outstanding unpaid invoice itself. A manual retry ignores the automatic ladder's backoff (it charges immediately) and works after dunning is exhausted, re-opening the exhausted attempt. A cleared retry settles the invoice, resumes the subscription, and fires the payment-succeeded signal. A declined retry returns PORTAL_RETRY_PAYMENT_DECLINED; genuine declines still count toward the retry cap, and the grace floor still applies before exhaustion. PORTAL_RETRY_PAYMENT_NOT_AVAILABLE means there is nothing to retry (the subscription is not awaiting payment, holds no unpaid card invoice, or has automatic billing disabled), and PORTAL_RETRY_PAYMENT_IN_PROGRESS means a concurrent charge holds the claim or the invoice was just paid — re-read the subscription instead of retrying again. All three carry the PORTAL_ prefix on the wire because this endpoint shares its implementation with the buyer portal's own retry.

Recovering a subscription after a failed charge

Two events resume a subscription parked in AWAITING_PAYMENT and re-arm automatic card billing, so the next cycle charges the saved card again. Both flip the subscription back to active and clear the failed-charge state; they differ only in whether the outstanding invoice is settled.

• The invoice is paid. When the outstanding card invoice is fully settled through any channel — a retried charge, a manual payment registered against it, a bank-reconciliation match, or an operator marking it paid — the subscription resumes automatically. This is the same recovery as a cleared card charge, so it fires the payment-succeeded signal: your cue to restore access.
• An operator reactivates it. An operator can resume the subscription directly from its detail page regardless of whether the invoice is paid — for a buyer who paid out of band, or to keep service running while collection continues. The outstanding invoice stays collectible in accounts-receivable; reactivation resumes billing, it does not settle the debt. This fires the subscription-updated signal (a status change), distinct from the payment-driven recovery above, so an integrator that revoked access on dunning_exhausted can restore it.

Recovery always re-arms billing from the next cycle: the spent charge attempt belonged to the old invoice, and the next cycle cuts a fresh invoice with its own charge against the saved card. An operator reactivation does not retry or alter the old invoice — it stays collectible until separately paid or written off.

Evidence & audit trail

Every notice send is recorded as audit evidence — the record set that answers a card dispute and evidences the consumer-law obligations above.

• Each notice is sent at most once per billing cycle. The buyer never receives a duplicate, even when a send is retried after a transient failure.
• Each record is immutable and reproduces the exact message that was sent without storing the email body. Records are kept for the longer of the subscription's life or two years from the last charge — the longest card-scheme dispute window — and survive subscription or customer deletion.

Operators can see every send, suppression, consent record, and compliance exception in the LedgerBee app, on the customer and subscription activity timelines filtered to the Notices category.

Webhooks to mirror payments in your own system

Subscribe to subscription webhooks to mirror these payments and gate access in your own system. See Webhooks for endpoint setup, the signed-envelope format, signature verification, and retries, and Subscription webhooks for the full topic list and error sub-types. The card-relevant signals:

• A charge cleared is the primary positive signal: grant or confirm access, mark the cycle paid, and mirror the receipt into your own records. The payload carries the invoice number, amount, and currency.
• A charge failed fires on every decline while retries run, on the subscription error topic with errorType: charge_failed (distinct from the undeliverable-recipient value). Act on it if you gate access the moment a charge fails. The subscription moves to AWAITING_PAYMENT, and the raw provider decline reason is not on the wire — the message field is a fixed human-readable string.
• Dunning exhausted fires once, on the subscription error topic with errorType: dunning_exhausted, when automatic retries are spent after the 7-day grace window. Act on it if you keep a buyer in service through dunning and revoke only when payment never recovers. After it, no further automatic charges run and the invoice is collectible through accounts-receivable.
• A subscription recovered after dunning is your cue to restore access you revoked on dunning_exhausted. Settling the invoice fires the payment-succeeded signal; an operator reactivation (invoice left unpaid) fires the subscription-updated signal with a status change. Either way the subscription is active again and the next cycle charges the saved card. See Recovering a subscription after a failed charge.
• An invoice was produced (the billed topic) fires once per child subscription when a billing run cuts its invoice, whether or not a charge follows. With pay-first card flows the charge follows immediately, so a billed event is followed by a charge-cleared or charge-failed signal.
• The subscription ended (the churned topic) is the definitive revoke-entitlement signal: stop expecting charges and tear down access. A scheduled cancellation emits a heads-up first (the cancellation-scheduled topic); the subscription keeps charging until the effective date, then churned fires.
• A trial converted (the trial-ended topic) marks the move from free trial to paid billing — the first real card charge follows, with the receipt's trial-conversion restatement.
• Paused and resumed suspend and restart charges. Grant entitlement on the started topic, not on assignment, which can be future-dated.

Reconcile every event on the stable subscriptionId or your own partnerReferenceId (the clientReferenceId you pass at checkout binding), never on the diagnostics-only versionId, which changes on every structural change (see Data model).

Errors & failure states

What you observe	What it means	What to do
Subscription error webhook with errorType: charge_failed; subscription is AWAITING_PAYMENT	A card charge (first or recurring) was declined. Retries and the grace window are running.	Choose your entitlement policy: gate access now, or keep the buyer in service while retries run. The buyer already got the first-decline email; a cleared retry fires the payment-succeeded signal.
Subscription error webhook with errorType: dunning_exhausted; final-notice email sent; invoice now collectible in accounts-receivable	Retries are exhausted — the retry cap and the 7-day grace floor have both elapsed, and automatic retries have stopped.	The terminal signal for automatic collection only: a manual retry (buyer, operator, or API) can still recharge the card. Revoke access now if you kept the buyer in service through dunning. The amount is collected through accounts-receivable, and LedgerBee leaves the subscription in AWAITING_PAYMENT (it doesn't cancel an established subscription over a failed charge). Access can be restored later: settling the invoice or an operator reactivation resumes the subscription and re-arms next-cycle billing (see Recovering a subscription).
Card-expired partner webhook; the card becomes charge-ineligible; buyer got a "card expired" email	The daily expiry scan flipped a stored card to expired (on OnPay, only after re-checking with the provider).	Prompt the buyer to add a new card via the portal before the next charge.
Card auto-update notice sent to the buyer; nothing required from you	The card network silently refreshed the stored card (type, mask, expiry). Billing continues uninterrupted.	Nothing — informational. The subscription keeps charging on the refreshed card.
Subscription error webhook with the undeliverable-recipient errorType	A document recipient for the subscription is undeliverable (for example the email hard-bounced); the document was not delivered.	Correct the recipient's contact details. This is a delivery problem, not a charge problem.
Blocked-card-brand error on checkout or card save	The buyer tried to save an American Express card for subscription card-on-file, which is blocked on both rails.	Ask the buyer to use a different card brand.