Skip to content
ContractSpec
Start here

Package manual · integrations

·Integrations and provider selection

integration.provider-payments

Payments provider implementations for ContractSpec.

integrationsintegrationv3.1.4stableservernode
@lssm-tech/integration.provider-payments
bun add @lssm-tech/integration.provider-payments
Package source ↗Manifest ↗

Manifest 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 its mode ('test' or 'live'). The event's livemode must be a boolean equal to the mode, and so must the event object's livemode when present; anything else is mode_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).
  • receiveStripeTestModeSubscriptionWebhook and receiveStripeLiveModeSubscriptionWebhook fix the mode. The secret is the signing secret of that mode's endpoint, read explicitly from STRIPE_TEST_WEBHOOK_SECRET (readStripeTestWebhookSecret) or STRIPE_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 an unknown outcome that flags the subscription for reconciliation. A redelivery yields the same event id and digest, so the store treats it as a duplicate. occurredAt is the Stripe event's created time.
  • stripeSubscriptionSnapshot(input, mapping, mode) (and the fixed-mode stripeTestModeSubscriptionSnapshot / stripeLiveModeSubscriptionSnapshot) builds a reconcile snapshot from subscription listings the host fetched; any unmappable object, or one whose livemode is 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_unresolved and subscription_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-run is 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.
  • --verify reads Stripe and exits 4 on any missing or drifted object. --apply writes only what differs; a second run is all no-ops. --archive deactivates prices and products and keeps the webhook endpoint unless --disable-webhook is given. Nothing is deleted. After writing, apply and archive read everything back and report ok (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 (runNonce in 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=true for the same product_key (and, for the webhook, the same endpoint_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) or STRIPE_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/--archive also need --confirm-live and --expect-account acct_...; live --verify needs --expect-account too, because its bindings become 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 be https without 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 label beta, qa, staging, stage, preview, dev, test, sandbox or demo is refused, so live events never go to a host that runs in test mode.
  • Plans must be active unless --allow-plan-status names other statuses.
  • The report maps each Stripe price id to its plan binding, exactly the prices input of StripeSubscriptionMappingConfig. 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

THIS PACKAGEintegration.provider-payments37 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

5 declarations

Declared capabilities

Integration Provider Payments

Payments provider implementations for ContractSpec.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit