Architecting Multi-Tenant Payments: Why Your 'Clever' Card Validation Isn't Enough

The Requirements: Where Things Got Real

To keep this system secure and scalable, we had four non-negotiable architectural constraints:

Multi-Tenant Payments: The Gateway Credentials Setup

Each tenant configures their own merchant gateway. For example, if a tenant connects Cashfree, we store their merchant identifiers and encrypted secrets so our backend can process orders and subscriptions directly on their behalf.

What We Store in the Database

{
  "tenant_id": "tenant_123",
  "provider": "cashfree", // or "razorpay" | "stripe"
  "app_id": "CF_PROD_AX2",
  "secret_key": "AES_256_ENCRYPTED_BLOB", // Decrypted only in backend memory
  "environment": "production",
  "created_at": "2026-01-26T10:00:00Z"
}

How It Works

import { Cashfree } from "cashfree-pg"

export async function createTenantOrder(tenantId: string, orderData: OrderData) {
  // 1. Fetch and decrypt credentials
  const tenant = await getTenantCredentials(tenantId)
  const secretKey = decrypt(tenant.secret_key)
  
  // 2. Initialize provider instance for this specific tenant request
  const cashfree = new Cashfree({
    mode: tenant.environment,
    appId: tenant.app_id,
    secretKey: secretKey,
  })

  // 3. Create order with tenant routing context in notify_url
  const response = await cashfree.PGCreateOrder({
    order_id: `order_${Date.now()}`,
    order_amount: orderData.amount,
    order_currency: "INR",
    customer_details: {
      customer_id: orderData.customerId,
      customer_email: orderData.customerEmail,
      customer_phone: orderData.customerPhone,
    },
    order_meta: {
      return_url: `https://app.com/orders/{order_id}`,
      notify_url: `https://api.com/webhooks/cashfree/${tenantId}`,
    },
  })

  return response.data
}

Saving Cards for Recurring Payments

Managing auto-debit for subscriptions required a secure mechanism to “remember” cards without increasing our regulatory liability.

What We Do Instead: Provider-Side Tokenization

{
  "customer_id": "cust_789",
  "tenant_id": "tenant_123",
  "card_token": "tok_xxxxx",  // Returned by the payment provider
  "last4": "4242",
  "card_type": "VISA",
  "expiry_month": "08",
  "expiry_year": "2028"
}

The Rabbit Hole: “Can I Validate Cards Without APIs?”

While optimizing the checkout experience, I wanted instant feedback for users typing card details without hitting network round-trips on every keystroke. I wondered:

“Do I really need to hit a payment API over the network just to check if a card number is formatted correctly?”

That's when I discovered the Luhn Algorithm (also known as the Mod 10 check). And for a moment… it felt like an ingenious shortcut.

Luhn Algorithm Visualization

Explaining Luhn Like You're 5

Let's trace an example card number: 5555 5555 5555 4444

Clean JavaScript Implementation

Here is a production-friendly version that is clean, readable, and performant:

/**
 * Validates a card number using the Luhn Algorithm (Mod 10).
 * Note: Checks mathematical checksum format, NOT active funds or account existence.
 */
function luhnCheck(cardNumber) {
  const digits = cardNumber
    .replace(/\D/g, '')  // Remove spaces, hyphens, and non-digits
    .split('')
    .reverse()
    .map(Number);

  let sum = 0;

  for (let i = 0; i < digits.length; i++) {
    let digit = digits[i];

    // Double every second digit
    if (i % 2 === 1) {
      digit *= 2;
      // If greater than 9, subtract 9 (equivalent to summing the two digits)
      if (digit > 9) {
        digit -= 9;
      }
    }

    sum += digit;
  }

  return sum % 10 === 0;
}

// Examples
console.log(luhnCheck("5555555555554444")); // true
console.log(luhnCheck("1234567890123456")); // false

Where I Was Wrong (An Important Engineering Lesson)

For a brief moment, I thought:

“This means I can validate cards on my own without relying on any payment gateway API calls.”

Nope.

Luhn checks syntax, not semantics. A mathematically valid card number could be expired, stolen, cancelled, or completely fabricated. It is the equivalent of checking whether a phone number has 10 digits versus checking whether someone actually answers when you dial.

The Final Architecture: How It Actually Flows

Payment Flow Architecture

Complete Multi-Tenant Payment Flow

Summary of Engineering Choices

Key Takeaways (From an Engineer Who Almost Over-Engineered This)