Plugging a Payment Gateway into a Multi-Tenant SaaS (Without Losing Sleep)
Why Payments Get Hairy in Multi-Tenant SaaS
In a single-tenant app, you wire Stripe keys, ship, and call it a day. In a multi-tenant world—think platforms like Shopify or Ghost—each merchant needs isolated ledgers, local compliance, and custom payout schedules. One mis-routed webhook can credit the wrong store and trigger a chargeback circus.
I recently integrated CC Avenue for a SaaS serving dozens of merchants. This post captures the practical lessons—and how to decide if CC Avenue, Stripe, Razorpay, Adyen, or Braintree fits your roadmap.
1 | Model Choices: Aggregator vs. Platform
| Model | How it works | Pros | Cons |
|---|---|---|---|
| Aggregator | Your SaaS owns the master merchant account; end-users pay you, you settle to sub-wallets. | Simplest onboarding; one KYC. | You hold liability, PCI scope widens; payouts become ops burden. |
| Platform/Connect | Each tenant has its own gateway account (or sub-merchant). Gateway handles KYC, payouts. | Liability & chargebacks isolated; easier compliance. | More onboarding friction; some gateways lack good Connect APIs. |
Rule of thumb: If tenants must handle refunds, taxes, or chargebacks themselves, go platform model. Otherwise start aggregator and migrate later.
2 | Gateway Showdown (2025 Edition)
| Gateway | Coverage | Currencies | Sub-Merchant API? | Best for… |
|---|---|---|---|---|
| Stripe Connect | 46 countries | 135+ | Yes (accounts, payouts) | Global SaaS, subscription heavy |
| CC Avenue | India, GCC | INR + 27 | Partial (split settlement) | Domestic India focus, UPI, net-banking |
| Razorpay Route | India | INR | Yes | India first, instant payouts |
| Adyen for Platforms | 70+ | 150+ | Yes | Enterprise global, in-app POS |
| Braintree Marketplace | US, CA, EU | 130+ | Limited | Simple PayPal/Venmo tie-ins |
Key questions to rank:
- Market expansion: Where will you onboard merchants next 18 mo?
- Payout cadence & fees: Weekly vs. T+2, percentage + fixed fees.
- Payment rails: Cards only, or UPI/ACH/mobile wallets?
- Subscription & metered billing: Native or roll-your-own?
- Compliance: PCI-DSS SAQ A vs. SAQ D, PSD2 SCA, RBI e-mandate.
3 | High-Level Architecture
- TenantPaymentCfg table stores gateway keys, payout prefs.
- Webhooks land at /gateway/${tenantId}/callback → queue for idempotent processing.
- Retry with exponential back-off; poison queue alerts PagerDuty.
4 | Security & Compliance Checkpoints
| Area | Must-do |
|---|---|
| PCI scope | Use gateway-hosted fields or drop-in UI → SAQ-A. |
| Idempotency | Pass Idempotency-Key (UUID v4) on create-charge, log in DB. |
| Webhook auth | HMAC SHA-256 with shared secret; verify timestamp ±5 min. |
| Tenant isolation | Row-level RLS or tenant_id PK/FK in every payment table. |
| Payout fraud | Dual-control on payout preference changes; notify merchant email. |
5 | Rollout Plan
- Sandbox first – spin test tenants, simulate success/fail webhooks.
- Feature flag by tenant – new merchants go live gateway-X; existing stay gateway-Y.
- Audit logs – every webhook → hash → append-only store (S3 + Object Lock).
- Progressive batching – start with 5 % production traffic, monitor refund flow, then ramp.
6 | Post-Integration Metrics
| Metric (90 days) | Before (manual invoices) | After gateway |
|---|---|---|
| Avg. payment settlement | 4.7 days | 1.2 days |
| Support tickets (payment) | 31 / month | 6 / month |
| Churn tied to payment failures | 4.5 % | 2.1 % |
Takeaways
- Pick your gateway like you pick a co-founder—coverage, roadmap, and support culture matter as much as API docs.
- In multi-tenant SaaS, isolation > convenience. Platform models scale better than aggregators once chargebacks appear.
- Secure webhooks, use idempotency keys, and store every event—payments are write-once, audit-forever.
- Roll out behind flags, watch metrics, and remember: the best payment flow is the one users forget ever happened.
Next on my radar: adding real-time FX quotes so merchants can price in buyers' local currency without shrinking their margins.