Saas Billing

SaaS Billing Expert (2026 Edition)

English | Bahasa Indonesia

English

Orchestration & Integration

Connects and orchestrates with relevant domain skills like brainstorming, zero-to-prod-orchestrator, and project-context-mapper to ensure cohesive execution.

Description

Expert guide for implementing and auditing SaaS billing systems. Covers subscription state machines, secure webhook handling, database synchronization, and the 2026 billing landscape including Stripe, Polar.sh (open-source, developer-first), LemonSqueezy, PayPal, and Midtrans (for Southeast Asia).

Trigger Conditions

• Integrating any payment gateway (Stripe, Polar.sh, LemonSqueezy, Midtrans, PayPal) into a SaaS application.
• Using a Static-to-Dynamic QRIS alternative (with unique nominals and mutation webhooks) for local developers without PG accounts.
• Implementing subscription state machines (active → past_due → canceled → reactivated).
• Building secure webhook handlers with signature verification and idempotency.
• Syncing external subscription status to a local database.
• Implementing usage-based billing or metered API pricing.
• Building the customer billing portal (manage subscription, download invoices).
• Auditing an existing billing system for security gaps.

2026 Billing Provider Landscape

Merchant of Record (MoR): The provider handles tax compliance (VAT, GST), chargebacks, and legal liability — ideal for small teams without a finance department.

Polar.sh — Developer-First Billing (2026 Rising Star)

Polar.sh is the modern, open-source alternative to Gumroad/LemonSqueezy, purpose-built for developers and open-source projects:

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });

// Create a checkout session
const checkout = await polar.checkouts.custom.create({
  productId: "prod_xxxx",
  successUrl: "https://myapp.com/success?checkout={CHECKOUT_ID}",
  customerEmail: user.email,
  metadata: { userId: user.id },
});

// Redirect to checkout
return redirect(checkout.url);

// Webhook handler (Next.js App Router)
import { validateEvent, WebhookVerificationError } from "@polar-sh/sdk/webhooks";

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get("webhook-signature") ?? "";
  
  try {
    const event = validateEvent(body, req.headers, process.env.POLAR_WEBHOOK_SECRET!);
    
    switch (event.type) {
      case "subscription.created":
      case "subscription.updated":
        await syncSubscription(event.data);
        break;
      case "subscription.canceled":
        await cancelSubscription(event.data.id);
        break;
    }
    return new Response(null, { status: 200 });
  } catch (e) {
    if (e instanceof WebhookVerificationError) {
      return new Response("Invalid signature", { status: 403 });
    }
    throw e;
  }
}

Stripe — Production Patterns

Subscription State Machine

FREE ──subscribe──> TRIALING ──trial_ends──> ACTIVE
                                              │
                              ┌───────────────┤
                              │               │
                         payment fails    cancel
                              │               │
                          PAST_DUE        CANCELED
                              │
                         3 failed retries
                              │
                          CANCELED

Idempotent Webhook Handler

// app/api/webhooks/stripe/route.ts
import Stripe from 'stripe';
import { db } from '@/lib/db';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;
  
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  // Idempotency: skip already-processed events
  const processed = await db.webhookEvent.findUnique({ where: { stripeEventId: event.id } });
  if (processed) return new Response(null, { status: 200 });

  // Process event
  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated': {
      const sub = event.data.object as Stripe.Subscription;
      await db.subscription.upsert({
        where: { stripeSubId: sub.id },
        create: { stripeSubId: sub.id, status: sub.status, userId: sub.metadata.userId },
        update: { status: sub.status, currentPeriodEnd: new Date(sub.current_period_end * 1000) },
      });
      break;
    }
    case 'invoice.payment_failed': {
      const invoice = event.data.object as Stripe.Invoice;
      await sendDunningEmail(invoice.customer_email!);
      break;
    }
  }

  // Mark as processed
  await db.webhookEvent.create({ data: { stripeEventId: event.id } });
  return new Response(null, { status: 200 });
}

Usage-Based Billing (Metered)

// Report usage at end of billing period
await stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
  quantity: apiCallsThisMonth,
  timestamp: Math.floor(Date.now() / 1000),
  action: 'set', // 'set' or 'increment'
});

PayPal — Checkout Integration

PayPal remains a trusted global standard for one-off payments and subscriptions.

Create Order (Server-Side)

// app/api/paypal/create-order/route.ts
import { paypalClient } from '@/lib/paypal';
import paypal from '@paypal/checkout-server-sdk';

export async function POST() {
  const request = new paypal.orders.OrdersCreateRequest();
  request.prefer("return=representation");
  request.requestBody({
    intent: 'CAPTURE',
    purchase_units: [{ amount: { currency_code: 'USD', value: '29.99' } }]
  });

  const response = await paypalClient().execute(request);
  return Response.json({ id: response.result.id });
}

Capture Payment (Server-Side)

// app/api/paypal/capture-order/route.ts
import { db } from '@/lib/db';
import { paypalClient } from '@/lib/paypal';
import paypal from '@paypal/checkout-server-sdk';

export async function POST(req: Request) {
  const { orderID, userId } = await req.json();
  const request = new paypal.orders.OrdersCaptureRequest(orderID);
  request.requestBody({});

  const response = await paypalClient().execute(request);
  if (response.result.status === 'COMPLETED') {
    // Grant access or update subscription in DB
    await db.subscription.create({
      data: { userId, provider: 'paypal', status: 'active' }
    });
    return Response.json({ success: true });
  }
  return Response.json({ success: false }, { status: 400 });
}

QRIS Static-to-Dynamic (Indonesia Alternative)

For Indonesian developers without an official Payment Gateway account, you can create a "Dynamic" QRIS experience using a single Static QRIS combined with unique payment amounts and a bank mutation checking service (e.g., Moota, Cekmutasi) via webhook.

1. Generate Unique Amount (Server-Side)

// Add a unique 3-digit code to the base price
export async function createQrisTransaction(userId: string, basePrice: number) {
  // Generate a random code between 1 and 999
  const uniqueCode = Math.floor(Math.random() * 999) + 1;
  const totalAmount = basePrice + uniqueCode;
  
  const transaction = await db.transaction.create({
    data: {
      userId, basePrice, uniqueCode, totalAmount,
      status: 'pending', provider: 'qris_static',
      expiresAt: new Date(Date.now() + 15 * 60 * 1000) // 15 mins expiry
    }
  });
  
  return {
    transactionId: transaction.id,
    totalAmount,
    qrisUrl: "https://myapp.com/static-qris.png" // User must manually input totalAmount
  };
}

2. Mutation Webhook Handler & Real-Time Notification

// app/api/webhooks/mutation/route.ts
import { db } from '@/lib/db';
import { pusherServer } from '@/lib/pusher';

export async function POST(req: Request) {
  const signature = req.headers.get("signature");
  // TODO: Verify signature from mutation service (e.g., Moota)
  
  const mutations = await req.json();
  
  for (const mutation of mutations) {
    if (mutation.type === 'CR' && mutation.amount > 0) {
      // Find pending transaction matching the exact unique amount
      const tx = await db.transaction.findFirst({
        where: {
          totalAmount: mutation.amount,
          status: 'pending',
          provider: 'qris_static',
          expiresAt: { gt: new Date() }
        }
      });
      
      if (tx) {
        // Mark as paid and activate subscription
        await db.transaction.update({ where: { id: tx.id }, data: { status: 'paid' } });
        await db.subscription.create({
          data: { userId: tx.userId, provider: 'qris_static', status: 'active' }
        });
        
        // Trigger real-time notification to frontend
        await pusherServer.trigger(`payment-${tx.id}`, 'payment-success', { success: true });
      }
    }
  }
  
  return new Response("OK", { status: 200 });
}

Database Schema for Multi-Provider Billing

// Drizzle ORM — supports Stripe, Polar, LemonSqueezy, PayPal, QRIS Static
export const subscriptions = pgTable('subscriptions', {
  id: text('id').primaryKey(),
  workspaceId: text('workspace_id').references(() => workspaces.id).notNull(),
  provider: text('provider').$type<'stripe' | 'polar' | 'lemonsqueezy' | 'paypal' | 'qris_static'>().notNull(),
  externalCustomerId: text('external_customer_id').notNull(),
  externalSubId: text('external_sub_id').notNull().unique(),
  status: text('status').$type<'active' | 'trialing' | 'past_due' | 'canceled' | 'paused'>().notNull(),
  plan: text('plan').$type<'free' | 'pro' | 'enterprise'>().default('free').notNull(),
  currentPeriodEnd: timestamp('current_period_end'),
  cancelAtPeriodEnd: boolean('cancel_at_period_end').default(false),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

Billing Security Checklist

• Webhook signature verified on every request — reject without valid signature.
• Webhook idempotency implemented — never process the same event twice.
• Session Management Optimization: Secure the billing portal route with strict session validation and CSRF protection. Do not cache session-dependent billing states.
• Use Stripe CLI / Polar.sh test webhooks for local development.
• All billing API calls use server-side code only — never expose secret keys to frontend.
• Plan limits enforced on every protected route (not just at checkout).
• Failed payment dunning flow configured (email sequence, grace period).
• Customer portal link available from within the app.

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti brainstorming, zero-to-prod-orchestrator, dan project-context-mapper untuk memastikan eksekusi yang kohesif.

Deskripsi

Panduan ahli untuk mengimplementasikan dan mengaudit sistem billing SaaS. Mencakup state machine langganan, penanganan webhook aman, sinkronisasi database, dan lanskap billing 2026 termasuk Stripe, Polar.sh (open-source, developer-first), LemonSqueezy, PayPal, dan Midtrans (untuk Asia Tenggara).

Kondisi Pemicu

• Mengintegrasikan payment gateway (Stripe, Polar.sh, LemonSqueezy, Midtrans, PayPal) ke aplikasi SaaS.
• Menggunakan alternatif QRIS Statis menjadi Dinamis (dengan nominal unik dan webhook mutasi) untuk developer lokal tanpa akun PG.
• Mengimplementasikan state machine langganan.
• Membangun webhook handler aman dengan verifikasi tanda tangan dan idempotency.
• Menyinkronkan status langganan eksternal ke database lokal.
• Mengimplementasikan billing berbasis penggunaan (metered pricing).
• Membangun portal billing pelanggan.
• Mengaudit sistem billing yang ada untuk celah keamanan.

Lanskap Provider Billing 2026

Merchant of Record (MoR): Provider menangani kepatuhan pajak (PPN, GST), chargeback, dan tanggung jawab hukum — ideal untuk tim kecil tanpa departemen keuangan.

Polar.sh — Billing Developer-First

Polar.sh adalah alternatif open-source modern untuk Gumroad/LemonSqueezy, dirancang khusus untuk developer dan proyek open-source. Mendukung checkout, webhook, dan manajemen langganan dengan SDK TypeScript yang bersih.

PayPal — Integrasi Checkout

PayPal sering digunakan sebagai gateway alternatif atau utama karena tingginya kepercayaan konsumen global.

• Server-Side Checkout: Gunakan create-order dan capture-order di backend (menggunakan @paypal/checkout-server-sdk) untuk memastikan keamanan dan mencegah manipulasi harga di sisi klien.
• Webhook: Verifikasi webhook dari PayPal untuk langganan yang diperbarui atau dibatalkan.

Stripe — Pola Produksi

State Machine Langganan

Kelola transisi status: FREE → TRIALING → ACTIVE → PAST_DUE → CANCELED → (reaktivasi).

Webhook Handler Idempoten

Selalu verifikasi tanda tangan webhook, tandai event sebagai diproses di database untuk mencegah duplikasi.

Billing Berbasis Penggunaan (Metered)

Laporkan penggunaan API dengan stripe.subscriptionItems.createUsageRecord() di akhir periode billing.

Alternatif Lokal: QRIS Statis Rasa Dinamis (Tanpa Akun Payment Gateway)

Bagi pengguna/developer di Indonesia yang belum memiliki Payment Gateway (seperti Midtrans), Anda dapat membuat pengalaman QRIS "Dinamis" menggunakan satu gambar QRIS statis biasa.

• Generate Nominal Unik (Endpoint): Tambahkan angka unik (misalnya 3 digit acak) ke harga dasar (contoh: Rp 100.000 menjadi Rp 100.123). Simpan ke database sebagai transaksi pending dengan batas waktu kadaluarsa (misal 15 menit). Tampilkan gambar QRIS beserta instruksi transfer sesuai nominal unik.
• Webhook Mutasi Bank: Gunakan layanan pihak ketiga (seperti Moota, Cekmutasi) yang mengirimkan notifikasi webhook (ke /api/webhooks/mutation) setiap kali ada uang masuk.
• Validasi Otomatis: Saat webhook menerima payload mutasi kredit (CR), sistem mencari transaksi pending yang jumlahnya sama persis (totalAmount). Jika cocok, sistem menandai tagihan sebagai lunas (paid) dan mengaktifkan langganan.
• Notifikasi Klien: Gunakan WebSocket (seperti Pusher atau Socket.io) di backend untuk melakukan trigger event "pembayaran berhasil". Di frontend, listen ke event tersebut dan tampilkan notifikasi real-time kepada pengguna secara instan tanpa perlu me-refresh halaman.

Skema Database Multi-Provider

Rancang tabel subscriptions yang mendukung beberapa provider (stripe, polar, lemonsqueezy, paypal, qris_static) dengan kolom provider dan ID eksternal yang terpisah.

Checklist Keamanan Billing

• Tanda tangan webhook diverifikasi pada setiap permintaan.
• Idempotency webhook diimplementasikan.
• Optimasi Session Management: Amankan rute portal billing dengan validasi sesi yang ketat dan perlindungan CSRF. Jangan gunakan cache untuk state billing yang bergantung pada sesi pengguna.
• Semua panggilan API billing menggunakan kode sisi server saja.
• Batas plan diterapkan pada setiap rute yang dilindungi.
• Alur dunning pembayaran gagal dikonfigurasi.
• Tautan portal pelanggan tersedia dari dalam aplikasi.