Tenant Onboarding & Billing Integration Guide

How a new tenant connects their platform to our multi-tenant billing engine — Stripe setup, catalog configuration, checkout integration, and webhooks — so they can sell subscriptions and one-time products to their own customers.

Prepared from the current backend implementation (Node.js / Express / MongoDB, per-tenant database architecture). Document version 1.0.

1. Architecture at a Glance

This platform is a database-per-tenant billing engine: one Node.js/Express backend serves every tenant, but each tenant's data (catalog, orders, invoices, customers, payment gateway credentials) lives in its own MongoDB database. A request is routed to the correct tenant database by resolving a tenant from the incoming request, then binding that tenant's DB connection for the rest of the request lifecycle.

Important: tenant/database provisioning itself is not exposed through a public signup API today — it's a one-time setup our platform team performs (Section 4). Everything after that (catalog, checkout, self-service, webhooks) is what this guide walks you through.

Stripe model: bring your own account (not Stripe Connect)

Each tenant uses their own standalone Stripe account — you generate your own Stripe secret key and publishable key and hand them to us to store (encrypted) against your tenant. This is not Stripe Connect: we never call Stripe with on_behalf_of, application fees, or connected-account IDs. From Stripe's point of view, charges simply happen on your account, using your keys, initiated by our backend on your behalf.

There are three moving parts to this platform, and this guide covers how your integration touches each:

1. The billing backend — the API described throughout this guide.
2. Your own site — where you'll wire up the Admin API (catalog) and Client Portal API (customer self-service).
3. The Payment App — a pre-built, Stripe-Elements-powered checkout page we host. You don't need to build your own payment form; you link/redirect your customers to it (Section 8.1). It is a separate codebase/deployment from the billing backend.

2. Key Concepts & Glossary

3. Onboarding Checklist (Quick Start)

End-to-end sequence from "we've agreed to onboard you" to "your customers can pay you."

4. Step 1 — Platform Provisioning

This step is performed by our platform/ops team — there is currently no public self-service signup endpoint for creating a new tenant. We will:

1. Create a TenantRegistry entry (your tenant's unique name, display name, and the connection details for your dedicated database).
2. Provision your dedicated MongoDB database.
3. Create your project (projectgeneralsettings) document — the record that will hold your storefront origin, currency, enabled gateway(s), and webhook config from later steps.

5. Step 2 — Connect Your Stripe Account

We charge your customers using your Stripe account. You do not need to give us access to your Stripe dashboard — only two API keys.

We store both keys encrypted in a paymentgateways record (provider: "stripe") inside your tenant database and link it to your project so Plans and Orders resolve back to it automatically at charge time.

Multiple payment methods per project: a project can have more than one active Gateway (e.g. Stripe plus an offline "Bank Transfer" gateway). When a Plan doesn't pin a specific gateway, the resolver prefers, in order: an active Stripe gateway → any active online gateway → any active gateway with a key.

6. Step 3 — Register Your Storefront Origin & Currency

Your public checkout pages (/public-api/*) are resolved to your tenant purely by request origin — no API key is sent on these calls. Tell us the exact domain(s) your storefront runs on (e.g. https://shop.yourcompany.com) so we can register it as your project's origin.

Bootstrapping the tenant ID client-side

GET /public-api/tenant/fetch-tenant?origin=https://shop.yourcompany.com

200 OK
{
  "_id": "6512f...e91",
  "tenant_unique_name": "yourcompany"
}

Also confirm your supported currency list:

GET /public-api/settings/global-settings/general-settings/currency-list?projectId={projectId}

7. Step 4 — Build Your Product & Plan Catalog

Catalog management happens on your Admin API (/admin/*), authenticated as your own staff user (JWT). This is a plain database write on our side — no Stripe Product/Price is created; Stripe only sees a bare amount + currency when a customer actually pays.

Core fields you'll set on a Plan

Where catalog is managed

Discounts. Coupons are entirely first-party (tenant-scoped rules, redemption ledger, usage caps) — never synced to Stripe as coupons or promotion codes. The discount is computed in our database and only the final, already-discounted amount is sent to Stripe as the PaymentIntent amount.

8. Step 5 — Integrate Checkout on Your Site

There are three integration paths, in order of how much frontend work they require. Most tenants should just use the hosted Payment App (8.1) — it's a finished checkout page we already built and host; you generate a link to it, and Stripe Elements/3D Secure/receipt are all handled for you.

8.1 — Recommended: Redirect to the Hosted Payment App (zero frontend code)

1. Create a payment link for a plan from your admin dashboard (or via API):

   POST /public-api/payment-links
   {
     "sourceType": 3,
     "sourceReferenceSlug": "pro-monthly"
   }

2. The backend builds a checkout URL against the Payment App's shared domain, e.g. https://pay.ourdomain.com/pay?payload=<encrypted> — the encrypted payload already carries the plan, price, currency, your productOrigin, and your Stripe publishable key, so the Payment App needs no separate login or tenant lookup to render correctly.
3. Link, email, or button your customer straight to that URL (or open it in an iframe/new tab from your site) — no Stripe.js integration required on your side.
4. The Payment App collects the card with Stripe Elements, calls /public-api/purchase and /public-api/purchase/confirm itself (Section 9), and on success navigates to its own /payment-success?summaryRef=... receipt page.

8.2 — Custom-branded checkout: Payment Links + your own UI

If you want full control over the checkout page's look and feel (rather than the shared Payment App), you can build your own form and still use the same publishable-key lookup:

1. Create the payment link as above, then validate the slug from your own checkout page to get plan details and the Stripe publishable key:

   GET /public-api/payment-links/validate/:slug
   
   200 OK
   {
     "plan": { "...": "..." },
     "provider": "stripe",
     "publicKey": "pk_test_...",
     "gatewayId": "..."
   }

2. Collect the card with your own Stripe Elements integration client-side (card number never touches our servers), then submit the resulting PaymentMethod/token to the Purchase API below.

8.3 — Direct: Purchase API (fully headless / custom checkout UI)

A single unified endpoint handles orders, standalone invoices, and plan purchases, distinguished by sourceType:

POST /public-api/purchase
{
  "productOrigin": "6512f...e91",
  "customerInfo": { "email": "[email protected]", "name": "Jane Doe", "mobile": "+1..." },
  "paymentMethodId": "pm_1P...",
  "planInfo": {
    "paymentSourceDetails": {
      "sourceType": 3,
      "sourceReferenceSlug": "pro-monthly"
    },
    "metadata": { "your_internal_customer_id": "cus_local_123" }
  }
}

// success
200 OK
{ "status": "success", "payment_intent": { "...": "..." }, "receipt": { "summaryRef": "..." } }

// card requires authentication (3D Secure) — see Step 6
200 OK
{ "status": "requires_action", "clientSecret": "pi_..._secret_...", "receipt": { "summaryRef": "..." } }

// card declined
402 { "status": "payment_failed", "message": "..." }

Pre-flight helpers

9. Step 6 — Handle 3D Secure / SCA

When Stripe requires additional authentication, the Purchase API returns status: "requires_action" with a PaymentIntent clientSecret. Your checkout page must:

1. Call stripe.confirmCardPayment(clientSecret) client-side (Stripe.js) to complete the 3DS challenge.
2. Then call our confirm endpoint to finalize the order on our side:

   POST /public-api/purchase/confirm
   { "paymentIntentId": "pi_...", "receiptRef": "..." }

Only after this confirm step succeeds are the Order/Invoice/Subscription records created — a PaymentIntent stuck in requires_action that the customer abandons produces no order.

10. Step 7 — Give Customers Self-Service (Client Portal API)

Once a customer has an account with you, everything under /client/* is scoped to them — authenticated via a JWT (cookie <projectToken>_auth_token, an Authorization / auth-token header, or a ?token= query param).

11. Step 8 — Receive Events From Us (Outbound Webhooks)

Tell us an HTTPS endpoint on your side and we'll POST you an event payload whenever something billing-relevant happens. Delivery is fire-and-forget — a failure on your end never blocks or rolls back the purchase.

Events we can send

Choosing how we authenticate to you

12. Step 9 — Our Inbound Stripe Webhook

Separately from Section 11, our backend itself listens for events coming from Stripe, at a single fixed endpoint: POST /api/stripe/webhook (verified via Stripe-Signature header).

What it actually handles today

Everyday purchase success/failure is not driven by a Stripe webhook at all — the Purchase API (Section 8) confirms the PaymentIntent synchronously in the same request and writes the Order/Invoice/Subscription immediately. The Stripe webhook exists specifically to catch asynchronous events (disputes, refunds initiated from your Stripe dashboard) that can't be observed synchronously.

13. Money Mechanics

Invoices & receipts

Invoices are our own PDF documents (EJS template rendered to PDF via a headless browser), not Stripe Invoice objects — there is no stripe.invoices.* call anywhere in the flow.

Transactions

Every payment attempt (success, failure, refund, chargeback, or a wallet credit/debit) is recorded as a Transaction, carrying the Stripe PaymentIntent ID, Charge ID, and Customer ID for reconciliation against your Stripe dashboard.

Wallet credit

Each customer has one internal wallet (balance / credit balance / hold balance, integer minor units). It's a pure internal ledger — crediting a wallet never calls Stripe. Wallet balance is drawn down automatically before a card is charged where applicable.

Coupons

Entirely first-party — rules, eligibility, usage caps, and redemption tracking live in our database. Stripe is only ever shown the final discounted amount, never a coupon/promotion code object.

Multi-currency

You can charge in a "presentment" currency different from your own base/settlement currency. We persist the exchange rate and its source at the time of charge, and re-verify the PaymentIntent's actual currency/amount server-side before marking anything paid — mismatches are rejected rather than silently accepted. Zero-decimal currencies (e.g. JPY, KRW) and three-decimal currencies (e.g. KWD, BHD, OMR) are handled with Stripe's minor-unit rules in mind; always check /public-api/purchase/stripe-minimum before charging a small amount in an unfamiliar currency.

Recurring billing (subscriptions)

14. API Reference Index

Public Storefront API — /public-api/* (origin-resolved, no token)

Client Portal API — /client/* (customer JWT)

See the full table in Section 10 above.

Payment App (hosted checkout SPA — separate deployment)

Your Admin API — /admin/* (staff JWT / x-tenant-id)

Project settings (origin, gateway selection, outbound webhook config) are currently read-only via API — changes to these go through our platform team until a write endpoint is exposed.

15. Status Code Reference

Order status

Invoice status

Transaction status

16. Known Limitations & Recommendations

This guide reflects the platform's current implementation as of its generation date. Endpoints and behavior may change — contact the platform team for the latest contract before building critical automation against undocumented response fields.