Claude Cursor Skill

saas-billing

Implement and audit SaaS billing systems, subscription state machines, secure webhooks, and local database synchronization / Implementasi dan audit sistem billing SaaS, state machine langganan, webhook aman, dan sinkronisasi database lokal.

LLM Mart · 0 points · 4 views 0 listing impressions 0 install-command copies
Download roedyrustam-vibes-plug-skills_saas-billing-83218ab.zip · 9 KB

Install

skills CLI npx skills add https://github.com/roedyrustam/vibes-plug/tree/main/skills/saas-billing
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install roedyrustam-vibes-plug@llmmart
Git git clone https://github.com/roedyrustam/vibes-plug.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole roedyrustam/vibes-plug collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

SaaS Billing Expert (2026 Edition)

English | Bahasa Indonesia


English

Orchestration & Integration

  • Payment Gateways & Providers: payment-gateway-expert, doku-payment-gateway, agentic-m2m-settlement, agentic-micro-economy-architect
  • Database & Subscription State: database-orm-expert, saas-multi-tenant, saas-architect
  • Security & Post-Quantum Crypto: post-quantum-crypto-migrator, zero-trust-secret-vault, autonomous-red-teamer
  • Background Queues & Notifications: async-queue-temporal-expert, email-notification-expert, sse-websocket-streaming-expert, pdf-document-generation-expert (automated tax invoice & receipt PDF generation)
  • Lifecycle & Governance: production-ready-hardener, brainstorming, zero-to-prod-orchestrator, session-memory-manager
  • Cross-Domain Synergy & Subagent Swarm Integration: double-entry-ledger-fintech-expert, ecommerce-expert, feature-flag-analytics-expert

Description

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

Trigger Conditions

  • Integrating any payment gateway (Stripe, Polar.sh, LemonSqueezy, DOKU Checkout / SNAP BI, 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 atomic 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

Provider Best For Open Source Merchant of Record
Stripe Enterprise, global, complex billing ❌ ❌
Polar.sh Developer-first, open-source products ✅ ✅ (optional)
LemonSqueezy Indie hackers, simple pricing, global ❌ ✅
Paddle B2B SaaS, EU VAT compliance ❌ ✅
DOKU (Checkout & SNAP BI) Indonesia & SE Asia enterprise, QRIS, VA, Multi-channel ❌ ❌
Midtrans Southeast Asia / Indonesia ❌ ❌
PayPal Global, consumer trust ❌ ❌

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 (Race Condition Prevention)

// 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(); // Raw body is mandatory
  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: Atomic insert on unique constraint to guarantee zero race conditions
  try {
    await db.webhookEvent.create({
      data: {
        stripeEventId: event.id,
        eventType: event.type,
        processedAt: new Date(),
      },
    });
  } catch (err: any) {
    // Unique violation (e.g. Prisma code P2002) means this event is ALREADY processed or currently processing
    return new Response(JSON.stringify({ message: 'Event already received' }), { status: 200 });
  }

  // Process event safely knowing this invocation is guaranteed unique
  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;
    }
  }

  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)

import crypto from 'node:crypto';

// Add a cryptographically random 3-digit code (1..999) to the base price
export async function createQrisTransaction(userId: string, basePrice: number) {
  const uniqueCode = crypto.randomInt(1, 1000);
  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 crypto from 'node:crypto';
import { db } from '@/lib/db';
import { pusherServer } from '@/lib/pusher';

function verifyMutationSignature(received: string | null, expectedSecret: string | undefined): boolean {
  if (!received || !expectedSecret) return false;
  const a = Buffer.from(received, 'utf8');
  const b = Buffer.from(expectedSecret, 'utf8');
  return a.byteLength === b.byteLength && crypto.timingSafeEqual(a, b);
}

export async function POST(req: Request) {
  const signature = req.headers.get("signature");
  if (!verifyMutationSignature(signature, process.env.BANK_MUTATION_SECRET)) {
    return Response.json({ error: "Unauthorized: Invalid signature" }, { status: 401 });
  }
  
  const mutations = await req.json();
  
  for (const mutation of mutations) {
    if (mutation.type === 'CR' && mutation.amount > 0) {
      // Atomic Update: Only update if still pending
      const updateResult = await db.transaction.updateMany({
        where: {
          totalAmount: mutation.amount,
          status: 'pending',
          provider: 'qris_static',
          expiresAt: { gt: new Date() }
        },
        data: { status: 'paid' }
      });
      
      if (updateResult.count > 0) {
        const tx = await db.transaction.findFirst({ where: { totalAmount: mutation.amount, status: 'paid' } });
        if (tx) {
          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, DOKU, 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' | 'doku' | '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(),
});

Proration-Aware Subscription Upgrade/Downgrade & Grace-Period Entitlement Guard

Calculate exact integer-minor-unit proration credits when switching plans mid-cycle and enforce a deterministic grace period (past_due) before revoking workspace access:

export type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused';

export interface WorkspaceEntitlementState {
  status: SubscriptionStatus;
  plan: 'free' | 'pro' | 'enterprise';
  currentPeriodStartMs: number;
  currentPeriodEndMs: number;
  gracePeriodHours: number;
}

export function hasActivePaidEntitlement(state: WorkspaceEntitlementState, nowMs = Date.now()): boolean {
  if (state.status === 'active' || state.status === 'trialing') {
    return nowMs <= state.currentPeriodEndMs;
  }
  if (state.status === 'past_due') {
    const graceDeadlineMs = state.currentPeriodEndMs + state.gracePeriodHours * 3600_000;
    return nowMs <= graceDeadlineMs;
  }
  return false;
}

export function calculateMidCycleProrationCents(params: {
  currentPlanPriceCents: number;
  targetPlanPriceCents: number;
  periodStartMs: number;
  periodEndMs: number;
  changeTimestampMs: number;
}): { unusedCreditCents: number; newPlanChargeCents: number; netDeltaCents: number } {
  const totalDurationMs = Math.max(1, params.periodEndMs - params.periodStartMs);
  const remainingMs = Math.max(0, Math.min(totalDurationMs, params.periodEndMs - params.changeTimestampMs));
  const remainingFraction = remainingMs / totalDurationMs;

  const unusedCreditCents = Math.round(params.currentPlanPriceCents * remainingFraction);
  const newPlanChargeCents = Math.round(params.targetPlanPriceCents * remainingFraction);

  return {
    unusedCreditCents,
    newPlanChargeCents,
    netDeltaCents: newPlanChargeCents - unusedCreditCents,
  };
}

Hard Guardrails (Declarative Invariants)

  • Raw Body Cryptographic Webhook Verification: MUST read the unparsed raw request body (await req.text()) and verify provider signatures (stripe.webhooks.constructEvent, Polar validateEvent, or crypto.timingSafeEqual) before parsing JSON.
  • Database-Backed Event Idempotency: MUST insert event.id into a unique processed_webhooks table (ON CONFLICT DO NOTHING) inside the transaction before mutating subscription state.
  • CSPRNG Unique Payment Codes: MUST use crypto.randomInt(1, 1000) instead of Math.random() when generating unique static-to-dynamic QRIS payment suffixes.
  • Grace-Period Dunning State Machine: MUST transition failed renewals to past_due with a bounded grace window rather than immediately deleting user workspaces.
  • Integer Minor-Unit Proration: MUST compute plan upgrades, downgrades, and usage billing in integer minor units (cents/sen) with Math.round to eliminate IEEE-754 floating-point drift.

Billing Security Checklist

  • Webhook signature verified on every request — reject without valid signature.
  • Webhook idempotency implemented with Atomic Lock — 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.

Blue-Ocean Synergy & Anti-Commodity Protocol

  • Mandatory Blue-Ocean Pairing: Always compose saas-billing with autonomous-tdd-debugger, autonomous-red-teamer, ephemeral-wasm-sandbox-executor, prompt-injection-firewall, anti-slop so commodity boilerplate is elevated into verified, self-healing production architecture.
  • Anti-Commodity Mandate: Elevate routine tests into continuous self-healing: validate candidate patches in vibes sandbox --verify, fuzz OWASP/injection vectors, and gate commits via vibes skill auto-diff.
  • Pre-Disk Gate: Run vibes verify-gate and vibes skill auto-diff --json to inject <350-token slices and eliminate placeholder slop.

Sovereign Execution, Token Efficiency & Invariants

Dimension Sovereign Mandate & Deterministic Contract
Frontier Model Cascade High Fast / High (Gemini 4 Carbon, Gemini 4 Neon, Grok 4.7 High Fast, Claude Sonnet 5.5 High, Gemini 4 Pro)
Availability Fallback Gemini 4 (Carbon/Hydrogen/Neon/Argon/Pro) -> Gemini 3.8 Flash; Claude Opus 5.5 -> Claude Opus 4.6; Grok 4.7 -> Grok 4.6 High Fast (Zero unhandled missing-model errors)
KV-Cache & Token Protocol Pin static instructions & schemas at prompt prefix (kv-cache-prefix-optimizer); pass surgical CONTEXT_MAP.md slices (<250 tokens/call) during Swarm Fan-Out
SaaT CLI & MCP Dispatch CLI: vibes skill exec saas-billing <audit\|eval\|verify\|generate\|blueprint> / MCP: vibes_skill_dispatch, vibes_critic_validate, vibes_self_heal, vibes_eval_sandbox, vibes_verify_invariants
NFR & Anti-Slop Invariants Zero OWASP Top 10 vectors, 0 hardcoded secrets, >= 90% branch coverage on domain logic, 0 Anti-Slop violations; 100% complete zero-placeholder output verified via node scripts/check-anti-slop.js --strict


Bahasa Indonesia

Integrasi Orkestrasi

  • Payment Gateway & Provider: payment-gateway-expert, doku-payment-gateway, agentic-m2m-settlement, agentic-micro-economy-architect
  • Database & Status Langganan: database-orm-expert, saas-multi-tenant, saas-architect
  • Keamanan & Kriptografi Pasca-Kuantum: post-quantum-crypto-migrator, zero-trust-secret-vault, autonomous-red-teamer
  • Antrean Latar Belakang & Notifikasi: async-queue-temporal-expert, email-notification-expert, sse-websocket-streaming-expert
  • Siklus Hidup & Tata Kelola: production-ready-hardener, brainstorming, zero-to-prod-orchestrator, session-memory-manager
  • Sinergi Lintas Domain & Integrasi Swarm Subagent: double-entry-ledger-fintech-expert, ecommerce-expert, feature-flag-analytics-expert

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, Paddle, DOKU (Checkout & SNAP BI), dan Midtrans (untuk Asia Tenggara).

Kondisi Pemicu

  • Mengintegrasikan payment gateway (Stripe, Polar.sh, LemonSqueezy, DOKU Checkout / SNAP BI, 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 berbasis atomic lock.
  • 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

Provider Terbaik Untuk Open Source Merchant of Record
Stripe Enterprise, global, billing kompleks ❌ ❌
Polar.sh Developer-first, produk open-source ✅ ✅ (opsional)
LemonSqueezy Indie hackers, harga sederhana ❌ ✅
Paddle B2B SaaS, kepatuhan PPN EU ❌ ✅
DOKU (Checkout & SNAP BI) Indonesia & Asia Tenggara, QRIS, Virtual Account, Multi-kanal ❌ ❌
Midtrans Asia Tenggara / Indonesia ❌ ❌
PayPal Global, kepercayaan konsumen (consumer trust) ❌ ❌

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 (Pencegahan Race Condition)

Selalu verifikasi tanda tangan webhook dari raw body. Gunakan insert unik atomic di database (bukan sekadar findUnique) agar request retry simultan tidak menyebabkan penambahan saldo atau perpanjangan langganan ganda. Jika terdeteksi duplikat, langsung kembalikan status HTTP 200 OK.

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/DOKU), 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 & Atomic Lock: Saat webhook menerima payload mutasi kredit (CR), sistem memperbarui transaksi pending secara atomik. 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, doku, paypal, qris_static) dengan kolom provider dan ID eksternal yang terpisah.

Checklist Keamanan Billing

  • Tanda tangan webhook diverifikasi pada setiap permintaan menggunakan raw body.
  • Idempotency webhook diimplementasikan dengan penguncian atomic.
  • 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.

Sinergi Blue-Ocean & Protokol Anti-Komoditas

  • Pasangan Wajib Blue-Ocean: Selalu komposisikan saas-billing bersama autonomous-tdd-debugger, autonomous-red-teamer, ephemeral-wasm-sandbox-executor, prompt-injection-firewall, anti-slop agar boilerplate standar naik kelas menjadi arsitektur produksi terverifikasi dan self-healing.
  • Mandat Anti-Komoditas: Tingkatkan tes standar menjadi self-healing kontinu: validasi patch di vibes sandbox --verify, fuzzing vektor OWASP/injeksi, dan gerbang commit via vibes skill auto-diff.
  • Gerbang Pra-Disk: Jalankan vibes verify-gate dan vibes skill auto-diff --json untuk menyuntikkan slice <350 token serta mencegah placeholder slop.

Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian

Dimensi Mandat Berdaulat & Kontrak Deterministik
Kaskade Model Frontier High Fast / High (Gemini 4 Carbon, Gemini 4 Neon, Grok 4.7 High Fast, Claude Sonnet 5.5 High, Gemini 4 Pro)
Invarian Fallback Ketersediaan Gemini 4 (Carbon/Hydrogen/Neon/Argon/Pro) -> Gemini 3.8 Flash; Claude Opus 5.5 -> Claude Opus 4.6; Grok 4.7 -> Grok 4.6 High Fast (Bebas gagal saat model belum tersedia/kuota penuh)
Protokol Hemat Token & KV-Cache Kunci instruksi & skema statis di prefix awal (kv-cache-prefix-optimizer); kirim potongan CONTEXT_MAP.md (<250 token/panggilan) saat Fan-Out
Eksekusi SaaT CLI & MCP CLI: vibes skill exec saas-billing <audit\|eval\|verify\|generate\|blueprint> / MCP: vibes_skill_dispatch, vibes_critic_validate, vibes_self_heal, vibes_eval_sandbox, vibes_verify_invariants
Invarian NFR & Anti-Slop Nol celah OWASP Top 10, 0 kredensial hardcoded, cakupan pengujian >= 90% pada logika domain, 0 pelanggaran Anti-Slop; kode 100% tuntas tanpa placeholder diverifikasi melalui node scripts/check-anti-slop.js --strict
Files (vibes-plug)
  • SKILL.md 25.6 KB
    ---
    name: saas-billing
    description: "SaaS billing state machines, subscription lifecycle, and webhooks / State machine billing SaaS, siklus langganan, dan webhook sinkron."
    author: "Roedy Rustam"
    version: "4.8.0"
    
    ---
    
    # SaaS Billing Expert (2026 Edition)
    
    [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
    
    ---
    
    <a name="english"></a>
    ## English
    
    ### Orchestration & Integration
    - **Payment Gateways & Providers**: `payment-gateway-expert`, `doku-payment-gateway`, `agentic-m2m-settlement`, `agentic-micro-economy-architect`
    - **Database & Subscription State**: `database-orm-expert`, `saas-multi-tenant`, `saas-architect`
    - **Security & Post-Quantum Crypto**: `post-quantum-crypto-migrator`, `zero-trust-secret-vault`, `autonomous-red-teamer`
    - **Background Queues & Notifications**: `async-queue-temporal-expert`, `email-notification-expert`, `sse-websocket-streaming-expert`, `pdf-document-generation-expert` (automated tax invoice & receipt PDF generation)
    - **Lifecycle & Governance**: `production-ready-hardener`, `brainstorming`, `zero-to-prod-orchestrator`, `session-memory-manager`
    - **Cross-Domain Synergy & Subagent Swarm Integration**: `double-entry-ledger-fintech-expert`, `ecommerce-expert`, `feature-flag-analytics-expert`
    
    ### Description
    Expert guide for implementing and auditing SaaS billing systems. Covers subscription state machines, secure webhook handling, atomic database synchronization, and the 2026 billing landscape including Stripe, **Polar.sh** (open-source, developer-first), **LemonSqueezy**, Paddle, DOKU (Checkout & SNAP BI), and Midtrans (for Southeast Asia).
    
    ### Trigger Conditions
    - Integrating any payment gateway (Stripe, Polar.sh, LemonSqueezy, DOKU Checkout / SNAP BI, 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 atomic 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
    
    | Provider | Best For | Open Source | Merchant of Record |
    |---|---|---|---|
    | **Stripe** | Enterprise, global, complex billing | ❌ | ❌ |
    | **Polar.sh** | Developer-first, open-source products | ✅ | ✅ (optional) |
    | **LemonSqueezy** | Indie hackers, simple pricing, global | ❌ | ✅ |
    | **Paddle** | B2B SaaS, EU VAT compliance | ❌ | ✅ |
    | **DOKU (Checkout & SNAP BI)** | Indonesia & SE Asia enterprise, QRIS, VA, Multi-channel | ❌ | ❌ |
    | **Midtrans** | Southeast Asia / Indonesia | ❌ | ❌ |
    | **PayPal** | Global, consumer trust | ❌ | ❌ |
    
    > **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:
    ```typescript
    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);
    ```
    
    ```typescript
    // 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 (Race Condition Prevention)
    ```typescript
    // 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(); // Raw body is mandatory
      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: Atomic insert on unique constraint to guarantee zero race conditions
      try {
        await db.webhookEvent.create({
          data: {
            stripeEventId: event.id,
            eventType: event.type,
            processedAt: new Date(),
          },
        });
      } catch (err: any) {
        // Unique violation (e.g. Prisma code P2002) means this event is ALREADY processed or currently processing
        return new Response(JSON.stringify({ message: 'Event already received' }), { status: 200 });
      }
    
      // Process event safely knowing this invocation is guaranteed unique
      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;
        }
      }
    
      return new Response(null, { status: 200 });
    }
    ```
    
    #### Usage-Based Billing (Metered)
    ```typescript
    // 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)
    ```typescript
    // 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)
    ```typescript
    // 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)
    ```typescript
    import crypto from 'node:crypto';
    
    // Add a cryptographically random 3-digit code (1..999) to the base price
    export async function createQrisTransaction(userId: string, basePrice: number) {
      const uniqueCode = crypto.randomInt(1, 1000);
      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
    ```typescript
    // app/api/webhooks/mutation/route.ts
    import crypto from 'node:crypto';
    import { db } from '@/lib/db';
    import { pusherServer } from '@/lib/pusher';
    
    function verifyMutationSignature(received: string | null, expectedSecret: string | undefined): boolean {
      if (!received || !expectedSecret) return false;
      const a = Buffer.from(received, 'utf8');
      const b = Buffer.from(expectedSecret, 'utf8');
      return a.byteLength === b.byteLength && crypto.timingSafeEqual(a, b);
    }
    
    export async function POST(req: Request) {
      const signature = req.headers.get("signature");
      if (!verifyMutationSignature(signature, process.env.BANK_MUTATION_SECRET)) {
        return Response.json({ error: "Unauthorized: Invalid signature" }, { status: 401 });
      }
      
      const mutations = await req.json();
      
      for (const mutation of mutations) {
        if (mutation.type === 'CR' && mutation.amount > 0) {
          // Atomic Update: Only update if still pending
          const updateResult = await db.transaction.updateMany({
            where: {
              totalAmount: mutation.amount,
              status: 'pending',
              provider: 'qris_static',
              expiresAt: { gt: new Date() }
            },
            data: { status: 'paid' }
          });
          
          if (updateResult.count > 0) {
            const tx = await db.transaction.findFirst({ where: { totalAmount: mutation.amount, status: 'paid' } });
            if (tx) {
              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
    ```typescript
    // Drizzle ORM — supports Stripe, Polar, LemonSqueezy, PayPal, DOKU, 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' | 'doku' | '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(),
    });
    ```
    
    ### Proration-Aware Subscription Upgrade/Downgrade & Grace-Period Entitlement Guard
    Calculate exact integer-minor-unit proration credits when switching plans mid-cycle and enforce a deterministic grace period (`past_due`) before revoking workspace access:
    
    ```typescript
    export type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused';
    
    export interface WorkspaceEntitlementState {
      status: SubscriptionStatus;
      plan: 'free' | 'pro' | 'enterprise';
      currentPeriodStartMs: number;
      currentPeriodEndMs: number;
      gracePeriodHours: number;
    }
    
    export function hasActivePaidEntitlement(state: WorkspaceEntitlementState, nowMs = Date.now()): boolean {
      if (state.status === 'active' || state.status === 'trialing') {
        return nowMs <= state.currentPeriodEndMs;
      }
      if (state.status === 'past_due') {
        const graceDeadlineMs = state.currentPeriodEndMs + state.gracePeriodHours * 3600_000;
        return nowMs <= graceDeadlineMs;
      }
      return false;
    }
    
    export function calculateMidCycleProrationCents(params: {
      currentPlanPriceCents: number;
      targetPlanPriceCents: number;
      periodStartMs: number;
      periodEndMs: number;
      changeTimestampMs: number;
    }): { unusedCreditCents: number; newPlanChargeCents: number; netDeltaCents: number } {
      const totalDurationMs = Math.max(1, params.periodEndMs - params.periodStartMs);
      const remainingMs = Math.max(0, Math.min(totalDurationMs, params.periodEndMs - params.changeTimestampMs));
      const remainingFraction = remainingMs / totalDurationMs;
    
      const unusedCreditCents = Math.round(params.currentPlanPriceCents * remainingFraction);
      const newPlanChargeCents = Math.round(params.targetPlanPriceCents * remainingFraction);
    
      return {
        unusedCreditCents,
        newPlanChargeCents,
        netDeltaCents: newPlanChargeCents - unusedCreditCents,
      };
    }
    ```
    
    ### Hard Guardrails (Declarative Invariants)
    - **Raw Body Cryptographic Webhook Verification**: MUST read the unparsed raw request body (`await req.text()`) and verify provider signatures (`stripe.webhooks.constructEvent`, Polar `validateEvent`, or `crypto.timingSafeEqual`) before parsing JSON.
    - **Database-Backed Event Idempotency**: MUST insert `event.id` into a unique `processed_webhooks` table (`ON CONFLICT DO NOTHING`) inside the transaction before mutating subscription state.
    - **CSPRNG Unique Payment Codes**: MUST use `crypto.randomInt(1, 1000)` instead of `Math.random()` when generating unique static-to-dynamic QRIS payment suffixes.
    - **Grace-Period Dunning State Machine**: MUST transition failed renewals to `past_due` with a bounded grace window rather than immediately deleting user workspaces.
    - **Integer Minor-Unit Proration**: MUST compute plan upgrades, downgrades, and usage billing in integer minor units (cents/sen) with `Math.round` to eliminate IEEE-754 floating-point drift.
    
    ### Billing Security Checklist
    - [ ] Webhook signature verified on every request — reject without valid signature.
    - [ ] Webhook idempotency implemented with Atomic Lock — 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.
    
    ### Blue-Ocean Synergy & Anti-Commodity Protocol
    - **Mandatory Blue-Ocean Pairing**: Always compose `saas-billing` with `autonomous-tdd-debugger`, `autonomous-red-teamer`, `ephemeral-wasm-sandbox-executor`, `prompt-injection-firewall`, `anti-slop` so commodity boilerplate is elevated into verified, self-healing production architecture.
    - **Anti-Commodity Mandate**: Elevate routine tests into continuous self-healing: validate candidate patches in `vibes sandbox --verify`, fuzz OWASP/injection vectors, and gate commits via `vibes skill auto-diff`.
    - **Pre-Disk Gate**: Run `vibes verify-gate` and `vibes skill auto-diff --json` to inject <350-token slices and eliminate placeholder slop.
    
    ### Sovereign Execution, Token Efficiency & Invariants
    | Dimension | Sovereign Mandate & Deterministic Contract |
    | :--- | :--- |
    | **Frontier Model Cascade** | High Fast / High (`Gemini 4 Carbon`, `Gemini 4 Neon`, `Grok 4.7 High Fast`, `Claude Sonnet 5.5 High`, `Gemini 4 Pro`) |
    | **Availability Fallback** | `Gemini 4 (Carbon/Hydrogen/Neon/Argon/Pro)` -> `Gemini 3.8 Flash`; `Claude Opus 5.5` -> `Claude Opus 4.6`; `Grok 4.7` -> `Grok 4.6 High Fast` (Zero unhandled missing-model errors) |
    | **KV-Cache & Token Protocol** | Pin static instructions & schemas at prompt prefix (`kv-cache-prefix-optimizer`); pass surgical `CONTEXT_MAP.md` slices (<250 tokens/call) during Swarm Fan-Out |
    | **SaaT CLI & MCP Dispatch** | CLI: `vibes skill exec saas-billing <audit\|eval\|verify\|generate\|blueprint>` / MCP: `vibes_skill_dispatch`, `vibes_critic_validate`, `vibes_self_heal`, `vibes_eval_sandbox`, `vibes_verify_invariants` |
    | **NFR & Anti-Slop Invariants** | Zero OWASP Top 10 vectors, 0 hardcoded secrets, >= 90% branch coverage on domain logic, 0 Anti-Slop violations; 100% complete zero-placeholder output verified via `node scripts/check-anti-slop.js --strict` |
    
    ---
    
    
    ---
    
    <a name="bahasa-indonesia"></a>
    ## Bahasa Indonesia
    
    ### Integrasi Orkestrasi
    - **Payment Gateway & Provider**: `payment-gateway-expert`, `doku-payment-gateway`, `agentic-m2m-settlement`, `agentic-micro-economy-architect`
    - **Database & Status Langganan**: `database-orm-expert`, `saas-multi-tenant`, `saas-architect`
    - **Keamanan & Kriptografi Pasca-Kuantum**: `post-quantum-crypto-migrator`, `zero-trust-secret-vault`, `autonomous-red-teamer`
    - **Antrean Latar Belakang & Notifikasi**: `async-queue-temporal-expert`, `email-notification-expert`, `sse-websocket-streaming-expert`
    - **Siklus Hidup & Tata Kelola**: `production-ready-hardener`, `brainstorming`, `zero-to-prod-orchestrator`, `session-memory-manager`
    - **Sinergi Lintas Domain & Integrasi Swarm Subagent**: `double-entry-ledger-fintech-expert`, `ecommerce-expert`, `feature-flag-analytics-expert`
    
    ### 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**, Paddle, DOKU (Checkout & SNAP BI), dan Midtrans (untuk Asia Tenggara).
    
    ### Kondisi Pemicu
    - Mengintegrasikan payment gateway (Stripe, Polar.sh, LemonSqueezy, DOKU Checkout / SNAP BI, 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 berbasis atomic lock.
    - 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
    
    | Provider | Terbaik Untuk | Open Source | Merchant of Record |
    |---|---|---|---|
    | **Stripe** | Enterprise, global, billing kompleks | ❌ | ❌ |
    | **Polar.sh** | Developer-first, produk open-source | ✅ | ✅ (opsional) |
    | **LemonSqueezy** | Indie hackers, harga sederhana | ❌ | ✅ |
    | **Paddle** | B2B SaaS, kepatuhan PPN EU | ❌ | ✅ |
    | **DOKU (Checkout & SNAP BI)** | Indonesia & Asia Tenggara, QRIS, Virtual Account, Multi-kanal | ❌ | ❌ |
    | **Midtrans** | Asia Tenggara / Indonesia | ❌ | ❌ |
    | **PayPal** | Global, kepercayaan konsumen (consumer trust) | ❌ | ❌ |
    
    > **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 (Pencegahan Race Condition)
    Selalu verifikasi tanda tangan webhook dari raw body. Gunakan insert unik atomic di database (bukan sekadar `findUnique`) agar request retry simultan tidak menyebabkan penambahan saldo atau perpanjangan langganan ganda. Jika terdeteksi duplikat, langsung kembalikan status HTTP `200 OK`.
    
    #### 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/DOKU), 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 & Atomic Lock**: Saat webhook menerima payload mutasi kredit (`CR`), sistem memperbarui transaksi pending secara atomik. 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`, `doku`, `paypal`, `qris_static`) dengan kolom `provider` dan ID eksternal yang terpisah.
    
    ### Checklist Keamanan Billing
    - [ ] Tanda tangan webhook diverifikasi pada setiap permintaan menggunakan raw body.
    - [ ] Idempotency webhook diimplementasikan dengan penguncian atomic.
    - [ ] 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.
    
    ### Sinergi Blue-Ocean & Protokol Anti-Komoditas
    - **Pasangan Wajib Blue-Ocean**: Selalu komposisikan `saas-billing` bersama `autonomous-tdd-debugger`, `autonomous-red-teamer`, `ephemeral-wasm-sandbox-executor`, `prompt-injection-firewall`, `anti-slop` agar boilerplate standar naik kelas menjadi arsitektur produksi terverifikasi dan *self-healing*.
    - **Mandat Anti-Komoditas**: Tingkatkan tes standar menjadi self-healing kontinu: validasi patch di `vibes sandbox --verify`, fuzzing vektor OWASP/injeksi, dan gerbang commit via `vibes skill auto-diff`.
    - **Gerbang Pra-Disk**: Jalankan `vibes verify-gate` dan `vibes skill auto-diff --json` untuk menyuntikkan slice <350 token serta mencegah placeholder slop.
    
    ### Matriks Eksekusi Berdaulat, Efisiensi Token & Invarian
    | Dimensi | Mandat Berdaulat & Kontrak Deterministik |
    | :--- | :--- |
    | **Kaskade Model Frontier** | High Fast / High (`Gemini 4 Carbon`, `Gemini 4 Neon`, `Grok 4.7 High Fast`, `Claude Sonnet 5.5 High`, `Gemini 4 Pro`) |
    | **Invarian Fallback Ketersediaan** | `Gemini 4 (Carbon/Hydrogen/Neon/Argon/Pro)` -> `Gemini 3.8 Flash`; `Claude Opus 5.5` -> `Claude Opus 4.6`; `Grok 4.7` -> `Grok 4.6 High Fast` (Bebas gagal saat model belum tersedia/kuota penuh) |
    | **Protokol Hemat Token & KV-Cache** | Kunci instruksi & skema statis di prefix awal (`kv-cache-prefix-optimizer`); kirim potongan `CONTEXT_MAP.md` (<250 token/panggilan) saat Fan-Out |
    | **Eksekusi SaaT CLI & MCP** | CLI: `vibes skill exec saas-billing <audit\|eval\|verify\|generate\|blueprint>` / MCP: `vibes_skill_dispatch`, `vibes_critic_validate`, `vibes_self_heal`, `vibes_eval_sandbox`, `vibes_verify_invariants` |
    | **Invarian NFR & Anti-Slop** | Nol celah OWASP Top 10, 0 kredensial hardcoded, cakupan pengujian >= 90% pada logika domain, 0 pelanggaran Anti-Slop; kode 100% tuntas tanpa placeholder diverifikasi melalui `node scripts/check-anti-slop.js --strict` |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.