Connecting Stripe
Stripe is the platform’s payment gateway for subscriptions and card payments, and it is also what drives card readers.
Where to find it
Architect Panel → Configuration:
- Instance Configuration Fields — where the secret key lives, per tenant
- Platform Modules — the commerce module
Architect Panel → Subscriptions:
- Subscription Packages — what customers can buy
- Subscribers — who has bought
- Card Readers — Stripe Terminal devices
The keys live in instance configuration
Specifically the secret key, held per tenant and read at runtime. That is deliberate: it means each tenant can have its own Stripe account, and it means the key is encrypted and restricted rather than sitting in a file.
If it is missing, the webhook endpoint refuses the request and writes an explicit error rather than failing quietly.
The webhook signing secret is separate
And equally required. It comes from the endpoint’s settings in your Stripe dashboard, and without it every webhook is rejected — the platform refuses outright rather than letting each request fail as an opaque error.
Settings that shape subscriptions
- Subscriptions enabled — off by default.
- Maximum subscriptions per product — whether a customer can hold more than one of the same package.
- Link subscriptions to tenants — whether a subscription belongs to a tenant rather than a person, which is what makes per-customer billing work in a multi-tenant installation.
- Discounts enabled — whether coupon codes are offered.
- Single card — whether a customer may store more than one card.
Direct Debit runs alongside
Rather than replacing Stripe. It has its own per-tenant credentials, and switching it on takes two deliberate steps — enabling the payment method and ticking it on a plan — so a half-configured gateway can never be advertised at checkout.
Test with test keys first
The obvious advice that gets skipped under deadline. A subscription created against live keys is a real charge, and unpicking one is more work than testing properly would have been.
Who can read the keys
Anybody who can read instance configuration can read your Stripe secret key, which is control of your payment account. Keep that to a very small group, and remember the audit log for that table holds the values too.
Worked example
An installation holds each tenant’s Stripe secret in instance configuration, restricted to two administrators, with subscriptions linked to tenants so billing follows the customer organisation rather than whoever signed up. Test keys were used until a full sign-up, upgrade and cancellation had been exercised.
Recommendations
- Keys in instance configuration, never in a file.
- Set the signing secret or no webhook will be accepted.
- Exercise sign-up, change and cancel on test keys.
- Restrict who can read the configuration and its audit log.