Stripe integration

2. Connection and account boundary

Before saving a connection, Seedling retrieves the supplied account directly, verifies the exact account and environment, and runs a bounded probe for every required read capability. An authorized empty result is valid; a wrong account, wrong mode, broad key, or missing required capability rejects the installation.

Customer-managed restricted key

A current Seedling workspace administrator supplies the exact Stripe account ID, chooses live, test, or sandbox, acknowledges restricted billing-data use, and enters the key once. Live requires rk_live_; test requires rk_test_; sandbox requires Stripe's documented restricted-key prefix for that environment. Broad sk_ secret keys and publishable, OAuth, or webhook-signing secrets are rejected.

Seedling-managed Marketplace app

The planned public Stripe App will use OAuth and the same verified account, data, access, synchronization, and purge contracts. OAuth, rotating refresh, signed app-event intake, provider configuration, and Marketplace approval remain gated and are not presented as available setup today.

Workspace only

Personal Stripe connections are disabled. A workspace has at most one active Stripe workspace connection, and Seedling never traverses Stripe Connect child accounts or uses an account ID as a public tenant selector.

3. Stripe data Seedling accesses

Transactional history defaults to the previous 365 days. Seedling fully reconciles the product and price catalog and retained active subscriptions; an older related record may be fetched only when an included record references it.

Customers and catalog

Minimized customer identity and lifecycle plus the full current product and active/inactive price catalog. Customer identity is limited to supported name and email context.

Subscriptions and invoices

Subscription and item lifecycle, invoices and lines, amounts, currency, collection state, timing, and related customer and product references.

Payments and adjustments

PaymentIntent and charge outcomes without payment instruments, plus refunds, credit notes, amounts, state, reason, and supported relationships.

Disputes and payouts

Dispute workflow without evidence or files, and payout state, arrival timing, balance-transaction amount, fee, net, and reporting-category context without payout destinations or source expansion.

Lifecycle provenance

The verified account, exact connection and source identity, typed provider staging, bounded capability results, synchronization cursors, and allowlisted event identity needed for reconciliation and deletion.

4. Data and capabilities Seedling excludes

• Payment instruments and card, bank, wallet, PaymentMethod, Source, SetupIntent, mandate, token, confirmation-token, or payout-destination data.
• Customer addresses, phone numbers, shipping details, tax IDs, arbitrary metadata values, dispute evidence, Files, identity files, raw client_secret values, and hosted invoice, PDF, receipt, or file URLs.
• Stripe Connect child-account traversal, Accounts v2, Tax, Radar Reviews, Checkout, Reporting, Transfers, Application Fees, Top-ups, Capital, Treasury, Issuing, Terminal, and Data Pipeline resources.
• Full Stripe response envelopes, provider error bodies, and webhook bodies in durable storage. Only typed supported fields and bounded reason codes are retained.
• Every write permission and every operation that creates, updates, refunds, exports, or deletes a Stripe record.

5. Restricted-key read-permission contract

Create the restricted key in the exact Stripe account and set only the following required resource families to Read. Leave unrelated resources at None. Seedling probes every required family before accepting the encrypted key.

• Account read — verify that the supplied account ID and selected environment are exact.
• Customers read — customer lifecycle.
• Products read and Prices read — current product and active/inactive price catalog.
• Subscriptions read — subscriptions and subscription items.
• Invoices read — invoices and complete invoice lines.
• PaymentIntents read — payment lifecycle after prohibited secret and instrument fields are stripped.
• Charges and refunds read — charge outcomes and refund lifecycle.
• Disputes read — dispute state without evidence, files, or payment details.
• Credit notes read — credit notes and complete credit-note lines.
• Payouts read — payout lifecycle without bank or card destinations.
• Balance read — balance transactions without source expansion.
• Events read — bounded, allowlisted incremental change recovery.
• Do not grant balance_transaction_source_read. If ordinary Balance read is insufficient in live proof, Seedling will omit balance transactions from phase 1 instead of broadening the key.

6. Steward-controlled human access and model use

• Every Stripe object starts with no human audience. Workspace membership, administrator or steward status, installer identity, customer email, and Stripe Dashboard roles do not grant raw reads.
• A current workspace owner or source steward must explicitly assign Seedling-defined Customers, Product catalog, Subscriptions, Invoices, Payments, Adjustments, Disputes, or Payouts scopes to each active member on the exact Stripe connection.
• Those grants do not mirror Stripe Dashboard roles. An owner or steward who needs raw data must also receive the applicable scope; stewardship itself is never a content bypass.
• Seedling reapplies the member's source-read policy to browse, search, retrieval, chat, citations, export, MCP, discovery, and evidence. Removing a grant removes access without deleting the source.
• Trusted exploration is separate system authority. External-model input minimizes and pseudonymizes customer identity and excludes prohibited fields; that authority never transfers to a member session.
• Stripe-derived DeepWiki publication remains blocked until a product/privacy owner defines and tests the anonymity threshold. Any later publication must be sanitized, aggregated or coarsened, immutable, and explicitly steward-approved; evidence still reapplies the reader's source policy.

7. Synchronization, retention, and deletion

Synchronization

The implemented path uses page-bounded typed staging and deterministic projection, six-hour event polling with overlapping closed windows, and weekly deep reconciliation. Failed or partial work advances no affected watermark and performs no deletion by omission.

Active-source retention

Typed staging and projected records remain only for the configured history and active relationships while the exact source is active. Minimized Marketplace webhook receipt metadata, once that mode is released, has a stricter 30-day maximum; raw webhook bodies are never retained.

Disconnect and purge

Local disconnect immediately fences new calls, deletes credentials and routing, revokes declared grants, and starts exact-source purge even if Stripe is unavailable. Marketplace users will also need to uninstall the app in Stripe when that mode is released.

8. Public-launch gates

The guide is implemented, but the connector stays muted and new installs remain disabled until every gate below has recorded evidence and approval. Repository implementation alone does not satisfy a live or public-release gate.

Deterministic product evidence

The common customer-managed pipeline, exact-source purge enumeration, declared-access isolation, targeted checks, architecture boundaries, replay pack, evaluation validation, and responsive/state frontend review must pass. Loading, empty, error, disabled, missing-permission, wrong-mode, syncing, partial, stale, reauthorization, disconnecting, and purging states must be verified.

Restricted-key live proof

A synthetic live-shaped restricted-key sandbox must confirm every required endpoint against pinned API version 2026-07-29.dahlia, exact key prefix and environment, headers, response shape, pagination behavior, empty-account behavior, prohibited-field absence, and Balance read without balance-transaction source expansion. Any failed required assumption keeps the connector muted.

Marketplace live proof

A separate synthetic managed sandbox must verify the exact app manifest and permissions, OAuth authorization and rotating refresh concurrency, event availability and routing, signed webhook validation and signing-secret rotation, duplicate and out-of-order delivery, deauthorization and uninstall behavior, and no forbidden stored fields. Marketplace code and provider configuration must exist before this gate can pass.

Production security and operations

Separate development, test/sandbox, and production app IDs, keys, install links, callback routes, signing secrets, and environment-qualified routes must be verified. Dependency, container, and secret scanning; production TLS and domain validation; secret-manager and KMS posture; credential and webhook-secret rotation; egress and stable-IP review; rate/read-budget controls; real alert destinations; backup and purge validation; access-log review; threat modeling; penetration testing; incident response, on-call ownership, and rollback must all pass.

Privacy, legal, and publication safety

Current privacy policy, terms, DPA, subprocessors, PCI position, data-locality compatibility, AI-use disclosure, minimized data contract, and final DeepWiki anonymity threshold require privacy, legal, security, and product review. No residency claim or Stripe-derived publication is allowed before its specific decision is recorded and tested.

Public disclosures and Stripe review

The in-product notice and public integration, support, deletion, privacy, security, and contact pages must match the released data contract. Stripe listing assets, exact permission-purpose copy, reviewer instructions, synthetic credentials, App review, Marketplace approval, and confirmation of the uninstall/revocation procedure are required before publication.

Explicit owner approval

Provider, integration, production, security, privacy, legal, product/data, and publication owners must approve the recorded evidence for the environments and modes being enabled. A later scope, history, metadata, account-cardinality, Connect, or write expansion requires its own reviewed capability release.

9. Setup, help, and removal