Checkout

Consumes the session and writes everything, transactionally: the customer (created, or your existingCustomerId reused), the consent evidence (recorded against the SESSION's pinned versions with PARTNER_ASSERTED provenance), the subscription, and the first charge. Synchronous — the subscription id is in the response.

x-api-idempotency-key is REQUIRED (400 IDEMPOTENCY_KEY_REQUIRED without it). A retry with the same key replays the full original response; a concurrent duplicate answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS; the same key reused for a DIFFERENT session answers 422 IDEMPOTENCY_KEY_REUSED.

Consent is assertion (you presented the pinned documents in your UI): termsAccepted: true is required, and recurringConsentAccepted: true on the CARD rail. On CARD, confirm requires the session's card to be CARD_READY — or a cardHandoffToken carried from an expired session.

Refusals to build the retry loop around: a 410 means the pinned plan/terms changed or the session expired (re-mint); PORTAL_CHECKOUT_AUTHORIZED_AMOUNT_CHANGED means the engine re-run no longer matches the pinned amount (card-release → re-quote → re-mint → re-confirm).

Invoice rail: the first invoice is billed asynchronously (billingPending: true). A tenant that serves no hosted portal sends invoice emails WITHOUT an online pay-now link — payment instructions ride the invoice document itself.

Required Scope

• checkout

Pure read: first-period pricing including exact VAT for the buyer you describe, the terms bodies and recurring-billing disclosure context, start-date rules, allowedPaymentMethods, and cardPaymentsEnabled — which is chargeability-aware, so a card step is never offered in a currency the window would refuse. firstPeriodChargeable: false means a zero first period (free trial / 100% discount): adapt your copy ("no charge today"); the card window still opens save-only.

country is required so VAT resolves exactly; consumer-facing prices MUST be displayed including VAT (render the gross figures). A vatNumber is accepted for BUSINESS buyers only and is checked against the country's published format.

A STRIPE_CROSS_CURRENCY_NOT_ENABLED refusal later in the flow is a configuration issue on your Stripe account (enable cross-currency charges or add a bank account in that currency on Stripe), never a buyer error — cardPaymentsEnabled: false here is how you avoid offering that dead end.

Required Scope

• checkout

One object, a machine-readable state per tenant precondition — the "am I integrated?" preflight, replacing error-by-error discovery. Make this the first call of your integration.

Preconditions for a working checkout: the Subscription license, at least one published plan with a sellable item, and — for the card rail — an active Stripe Connect account. Hosted card windows additionally need your return origin on your embeddableOrigins allowlist. LedgerBee-hosted terms are NOT a precondition: generalTermsPublished is informational — when you host terms in LedgerBee they ride the quote/session and confirm records per-version acceptance; when you don't, you host your own terms and confirm records your acceptance assertion.

Customer groups are NOT a readiness item: they are per-request data. Discover them via GET /v1/customers/groups.

Required Scope

• checkout

Mints the single-use session the rest of the flow runs against, PINNING what your buyer was shown: the plan version, the terms + disclosure versions, the resolved pricing and currency, quantities, VAT inputs and start date. Confirm re-runs the billing engine against those pinned inputs and refuses a drifted amount — you never bill a number the engine wouldn't produce, and a tenant republish affects new sessions only.

The buyer is plain request data — no tokens, no buyer verification. customerGroupId is REQUIRED (discover groups via GET /v1/customers/groups). Pass existingCustomerId for a returning buyer so they keep one customer record. Pass reference (your order/cart id) and every checkout.* webhook echoes it back.

The session expires after expiresInMinutes (default 30). An expired session answers 410 — re-mint and, if a card was already captured, carry its cardHandoffToken into the fresh session's confirm so the buyer never re-enters card details.

Required Scope

• checkout

PEEK a live session after a partner-side reload: the buyer payload, the pinned quote summary, your reference, and whether a card window was opened. 410 when expired or already consumed.

Required Scope

• checkout

The edit-after-card loop's first step: when the buyer changes quantities, start date or VAT inputs AFTER the card step, confirm refuses the now-stale pinned amount — call this, then re-quote, re-mint and re-confirm.

SAVE_ONLY: the captured card SURVIVES (carry its cardHandoffToken into the fresh session's confirm — the buyer never re-enters card details; the first charge is sized at billing). RECAPTURE_REQUIRED: the card could not be preserved — discard it and open a fresh card window.

Required Scope

• checkout

Poll after the buyer completes the card form: PENDING → keep polling, CARD_READY → confirm may proceed (the captured card's display details are included — show the buyer WHICH card will be charged), EXPIRED → the window lapsed, open a fresh one. The checkout.card_ready webhook is the push alternative; this poll stays authoritative.

Required Scope

• checkout

Opens the Stripe card surface for the session — the ONLY place a card is ever entered (your systems never touch card data). The tenant's active Stripe Connect account is the card rail; there is no provider selection. Refused with CARD_PROVIDER_NOT_CONNECTED when Stripe isn't connected.

uiMode: 'embedded' (default) returns a clientSecret — mount Stripe's embedded Checkout on your page with Stripe.js (loadStripe(publishableKey, { stripeAccount })). uiMode: 'hosted' returns a redirectUrl to checkout.stripe.com; returnUrl is then REQUIRED and its origin must be on your embeddableOrigins allowlist. The flow is identical either way: the card lands asynchronously — poll card-status (or listen for checkout.card_ready), then confirm.

A zero first period still opens the window SAVE-ONLY: the card is stored for the first real charge and nothing is authorized ("no charge today").

Required Scope

• checkout

The partner-UI path for updating the card on an EXISTING subscription — same uiMode contract as the checkout card window, rendered to the buyer in your page. The window is save-only and binds to the buyer's stored payment profile; when the new card lands (Stripe webhook), it REPLACES the card on file for that subscription. The buyer's emailed manage link remains the compliance floor and keeps working unchanged.

Required Scope

• checkout