Payments behind a swappable boundary

Card payments run through a provider-neutral contract — checkout, settled-payment listing, single-payment lookup and webhook verification — so a second processor is a registry row, not a rewrite.

What it is

A port defining createCheckout, listSettledPayments, getPayment, listEnabledOrgIds, isConfigured and verifyWebhook. Payments are single-provider per account (one merchant account) rather than a fallback chain: the first active binding wins, defaulting to Stripe. The platform's own subscription billing is deliberately a separate flow behind its own named boundary.

Also called: payment provider · second processor · PaymentsPort

See it
Payments behind a swappable boundary
Prepared for
Ronan Petsch
1140 Ridge Line Rd · Fair Play
Shell package$37,405
Concrete & site$10,859
Doors & windows$7,240
Trim & finish$4,826
Total
$60,330
Signature
A boundary diagram: invoice routes → PaymentsPort → adapters, with a greyed-out slot for a future second processor. Sample data — no customer information appears here.
How it works
  1. 1paymentsFor(orgId) reads the account's payments binding and returns the adapter, defaulting to Stripe.
  2. 2Routes call the port rather than the vendor SDK.
  3. 3allPaymentAdapters() lets the reconcile sweep cover every provider.
  4. 4The platform-level subscription Stripe is exported under its own boundary name so the two are never confused.
Why we built it

The registry states the modelling decision: 'Payments is single-provider per org (one merchant account), not a fallback chain: the first active binding wins, defaulting to Stripe. A second processor becomes selectable per tenant via a registry row.' The platform boundary exists because 'This is the OTHER Stripe: subscriptions charged on the PLATFORM's account, entirely separate from the org-merchant PaymentsPort', and the separation is made greppable on purpose.

The problem
  • Payment vendor choice was hard-coded.
  • The platform's own billing and the builder's customer payments were easy to conflate.
Sound familiar?
What you get
A second processor can be added without touching the invoice flow.
The reconcile sweep automatically covers any new processor.
Agency billing and customer payments cannot be mixed up.
What's inside

See it on your own jobs

Twenty minutes, your numbers, no slide deck. We’ll build one of your real buildings in front of you and send you the estimate link at the end — yours to keep either way.

or keep browsing features →