Docs
PaymentsOverview & why

Unified Payment Orchestration

What this is: Loop’s plan to move money for every brand and every LLC through one configurable payments service — multi-provider, with failover, on a card vault Loop owns — instead of being welded to a single processor.

Who it’s for: anyone building a checkout, a subscription, a payout, or a reorder on any Loop brand; anyone who needs to understand why payments is being re-shaped around entity and a portable token.

What to read next: Architecture · Entity model · Status & roadmap.

⚠️

This system is being built; most of it is not live. The Phase-A foundation (the orchestration primitives, the entity registry, the recon-ready ledger columns, the identity map) is in review (PR #1222, LOO-2182) and inert — the orchestrator and vault are not on the live checkout path yet. Every page in this section labels what is built, stubbed, gated, or planned. Start with Status & roadmap for the honest table.

The problem

Today every Loop entity is on Stripe, with some flows on NMI and some on owned gateways; subscriptions live in several places (custom tools in Loop Bio Labs / Leo Research; Stripe Billing in services/payments). That arrangement has three load-bearing problems:

  1. Off-Stripe is survival, not preference, for high-risk RUO. Stripe’s terms prohibit RUO peptides (research chemicals / nutraceuticals-with-claims). The RUO entities run on Stripe today but are TOS-precarious. This initiative is the planned, deliberate move off Stripe before enforcement — not a scramble after a termination. High-risk processors and vaults freeze or drop accounts with little notice, so survival requires fast provider/MID hot-swap and no single-vendor dependence for processing or card-data custody.
  2. Subscriptions are siloed. Loop Bio Labs and Leo Research each grew their own recurring-billing tools; services/payments uses Stripe Billing. There is no single subscription engine, so a card-on-file, a dunning policy, or a plan change means different code in different places.
  3. There is no ecosystem wallet. A card a customer enters for one brand cannot be reused by another, because each brand’s card data lives in a different processor’s vault. The customer re-enters their card; the business carries N copies of PCI scope; nobody owns the token.

The goals

These six goals come straight from ADR-0093, the architecture source of truth for this work.

  1. One payments service any ecosystem app can configure and consume (eventually via @platform/sdk-payments).
  2. Multi-provider routing with failover — (entity, product, geo, BIN, risk, amount) → MID, cascade on decline/outage, per-MID volume balancing.
  3. A portable vault + network tokens so a card-on-file survives a provider swap, a card reissue, and (eventually) a vault swap.
  4. Entity / LLC as a first-class dimension — entity_id on every payment and every ledger posting.
  5. A provider-agnostic subscription engine (ADR-0084) running on vault tokens; converge Loop Bio / Leo.
  6. SAQ A now, with an option on SAQ D later — and no rewrite to get there.

The one-paragraph mental model

A customer’s card is tokenized once, into a vault Loop owns and can export (Basis Theory today). That portable token can be charged on any processor. A thin Loop routing layer decides, per charge, which of an entity’s merchant accounts (MIDs) to try, and cascades to the next one only on a definitive decline — never on a timeout, so a card is never double-charged. Each entity (LLC) may collect only on the product categories it is underwritten for, and a charge physically cannot route to another entity’s MID — that constraint is the anti-laundering guard. Apps don’t build checkout UI or touch cards: they POST a declarative config (“who pays, which brand, which entity, what intent”) and the service hosts the payment step, so card data only ever meets one PCI environment.

How this section is organised

PageWhat it answers
ArchitectureThe verified shape: vault → routing layer → adapters → own-clock subs → hosted checkout. Why NMI is a gateway, not the brain.
Entity modelThe bidirectional entity registry, the seven concrete entities, route-by-(entity, product), the laundering guard.
The two seamsPaymentProvider (de-Striped) + TokenVault, and how to add a provider.
Routing & failoverThe eligibility-constrained cascade and the NO-DOUBLE-CHARGE invariant.
Vault & tokensBasis Theory, network tokens, owning the TRID, cross-acquirer portability.
SubscriptionsThe own-clock engine vs Stripe Billing; dunning; account-updater.
Hosted checkout-as-a-serviceThe config-push contract; hosted vs embedded; one CDE.
Card migrationZero re-entry: Stripe export + Stripe→Basis Theory forwarding; the ecosystem wallet.
PCI postureSAQ A now, the SAQ-D growth path, trigger-gated.
Operational guardrailsHuman sign-off on money paths, failure-injection discipline, Phase-0 gating.
Status & roadmapWhat’s built vs stubbed vs gated vs planned.

Source material

Related platform concepts

Architecture