integration.provider-payments
Payments provider implementations for ContractSpec.
@lssm-tech/integration.provider-paymentsbun add @lssm-tech/integration.provider-paymentsManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Website: https://contractspec.io
Server-side Stripe and PayPal payment-platform implementations for ContractSpec.
Usage
Import the root entrypoint for provider-neutral contracts, or import a concrete server implementation from ./impls/stripe-payments or ./impls/paypal-payments.
Both providers expose explicit capabilities for customers, saved payment methods, checkout, payments, subscriptions, invoices, disputes, payouts, marketplaces, and verified webhooks. Call discoverCapabilities() before using account- or region-dependent operations.
All mutations fail closed unless the host supplies a tenant-scoped actor, idempotency key, and unexpired authorization decision scoped to the exact operation, resource, amount, environment, and provider account. An injected authorizer can impose additional vertical policy; it cannot weaken or broaden the per-call decision.
The default test suite is credential-free. Opt-in sandbox smoke tests reject live credentials and production endpoints.
Canonical creator settlement
./creator-settlement bridges existing Stripe/PayPal marketplace capabilities to the canonical creator wallet. The host resolves scoped destinations and independent payment authorization, persists provider receipts, and supplies verified webhook or manual settlement evidence. Accepted or pending transfers remain unresolved. Micro-unit conversion is exact; fractional minor units and unsafe numeric ranges are rejected rather than rounded away. Existing Stripe API defaults are preserved.
Subscription state (test and live mode)
./impls/stripe-subscription-webhooks, ./impls/stripe-subscription-snapshot and ./impls/stripe-subscription-mapping map Stripe subscription facts of ONE mode onto @lssm-tech/lib.billing-spec/subscriptions events and reconcile snapshots for the BillingOS subscription engines; this package calls no Stripe API for them.
receiveStripeSubscriptionWebhook(request, { mode, ... })verifies the signature on the raw body with the Stripe SDK and accepts only events of itsmode('test'or'live'). The event'slivemodemust be a boolean equal to the mode, and so must the event object'slivemodewhen present; anything else ismode_mismatch, as is an unknown mode. The emitted event carries the mode, so the BillingOS store also refuses to apply it to a binding of the other mode (SUBSCRIPTION_MODE_CONFLICT).receiveStripeTestModeSubscriptionWebhookandreceiveStripeLiveModeSubscriptionWebhookfix the mode. The secret is the signing secret of that mode's endpoint, read explicitly fromSTRIPE_TEST_WEBHOOK_SECRET(readStripeTestWebhookSecret) orSTRIPE_LIVE_WEBHOOK_SECRET(readStripeLiveWebhookSecret); when it is absent every request is refused. The host decides which mode a request runs in; this package never picks one.customer.subscription.*events become a status observation (period,cancel_at_period_end,mode);invoice.*payment events become anunknownoutcome that flags the subscription for reconciliation. A redelivery yields the same event id and digest, so the store treats it as a duplicate.occurredAtis the Stripe event'screatedtime.stripeSubscriptionSnapshot(input, mapping, mode)(and the fixed-modestripeTestModeSubscriptionSnapshot/stripeLiveModeSubscriptionSnapshot) builds a reconcile snapshot from subscription listings the host fetched; any unmappable object, or one whoselivemodeis not the mode, refuses the whole snapshot.- Refusal reasons (nothing is guessed):
webhook_secret_missing,signature_missing,signature_invalid,mode_mismatch,unsupported_event_type,malformed_payload,multiple_items_unsupported,price_unbound,interval_mismatch,unsupported_status,unsupported_cancel_at,scope_unresolvedandsubscription_unresolved. - The host configures price bindings (Stripe price id to plan key, version and interval), scope resolution and the event source; brand plans and prices are brand data, never code here.
Subscription catalog provisioning (operator CLI)
src/cli/stripe-catalog-provision.ts provisions the Stripe products, prices and subscription webhook endpoint for one product's plans in a BillingOS subscription plan catalog (for example packages/platform/governance/lssm-os-spec/catalog/billing-plans.career.v1.json). It is an operator tool, not a package entrypoint; plans and prices stay catalog data.
--dry-runis the default: it prints the exact products (one per tier, with a deterministic custom id), prices (one per tier, interval and selected price book, lookup key<productKey>.<planKey>.v<version>), metadata, webhook events and capability map. It reads only the catalog file and makes no network call.--verifyreads Stripe and exits 4 on any missing or drifted object.--applywrites only what differs; a second run is all no-ops.--archivedeactivates prices and products and keeps the webhook endpoint unless--disable-webhookis given. Nothing is deleted. After writing, apply and archive read everything back and reportok(exit 0) only when the readback is all no-ops; otherwise they exit 4.- Create idempotency keys are deterministic. Update keys include a per-run nonce (
runNoncein the report) and the observed record, because Stripe replays a repeated key with identical parameters from its 24h cache without running it (archive, re-enable, archive would otherwise leave prices active). - Ownership fails closed. Only objects whose metadata carries
contractspec_managed=truefor the sameproduct_key(and, for the webhook, the sameendpoint_key) are adopted. An endpoint that only shares the URL, a hand-made price with a colliding lookup key, a lookup key held by other price terms, an object in the other mode or an unexpected account all refuse before the first write. - The key is read only from
STRIPE_LIVE_SECRET_KEY(--mode live) orSTRIPE_TEST_SECRET_KEY(--mode test), named by--api-key-env. A key-shaped value anywhere on the command line is refused without being echoed. Live--apply/--archivealso need--confirm-liveand--expect-account acct_...; live--verifyneeds--expect-accounttoo, because itsbindingsbecome the host's live price bindings. - A plan with issues is refused (exit 3,
refusal: plan_issues) before the key is read or any client exists. Webhook URLs must behttpswithout credentials, query or fragment; in live mode the host must be a production host: a loopback or IP literal,*.localhost,*.local,*.test,*.internal,*.vercel.app,*.up.railway.app, or a first labelbeta,qa,staging,stage,preview,dev,test,sandboxordemois refused, so live events never go to a host that runs in test mode. - Plans must be
activeunless--allow-plan-statusnames other statuses. - The report maps each Stripe price id to its plan binding, exactly the
pricesinput ofStripeSubscriptionMappingConfig. The webhook signing secret is never read into the report. - Stripe metadata is descriptive; entitlements still come from the plan the bound price sells.
Compatibility
This package owns the payments implementation slice split out of @lssm-tech/integration.providers-impls. The legacy package continues to re-export these subpaths for existing consumers.
This release intentionally replaces the previous Stripe-shaped method surface. See MIGRATION.md for the operation and money-field mappings.
When apiVersion is omitted, the Stripe adapter uses the version pinned by the installed SDK, matching its generated types. The current locked Stripe 22.6.1 SDK uses 2026-08-26.dahlia; this replaces the stale July 2026 fallback. Explicit SDK-supported apiVersion options and injected Stripe clients remain supported. Review Stripe API compatibility when updating the SDK lockfile.
The explicit catalog version 2026-07-29.dahlia remains accepted and is passed unchanged to Stripe. This prevents an SDK typing update from silently changing the version selected by the integration factory. The compatibility assertion is confined to SDK construction, following Stripe's documented older API version support. It does not claim complete live payment-flow qualification for both versions.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
5 declarations
@lssm-tech/integration.runtimeworkspace:^
Read the package manual ↗@lssm-tech/lib.billing-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗stripe^22.6.2
@lssm-tech/lib.creator-operations-specworkspace:^
Read the package manual ↗
Declared capabilities
Payments provider implementations for ContractSpec.
Scripts
buildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolint:checknode ../../../scripts/biome.cjs check .lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit