Claude Cursor Skill

payment-gateway-expert

Expert guide for integrating payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) and secure webhooks into SaaS platforms / Panduan ahli integrasi payment gateway dan webhook aman.

LLM Mart · 0 points · 4 views 0 listing impressions 0 install-command copies
Download roedyrustam-vibes-plug-skills_payment-gateway-expert-83218ab.zip · 6 KB

Install

skills CLI npx skills add https://github.com/roedyrustam/vibes-plug/tree/main/skills/payment-gateway-expert
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

Payment Gateway Expert / Ahli Payment Gateway

English | Bahasa Indonesia


English

Orchestration & Integration

  • Gateways & Payment Integrations: doku-payment-gateway, saas-billing, agentic-m2m-settlement, agentic-micro-economy-architect
  • AI Agentic Commerce & MCP: doku-mcp-server, mcp-server-architect, ai-llm-integration-expert
  • Database & Atomic Idempotency: database-orm-expert, saas-multi-tenant
  • Security & Post-Quantum Crypto: post-quantum-crypto-migrator, zero-trust-secret-vault, autonomous-red-teamer
  • Background Jobs & Observability: async-queue-temporal-expert, data-telemetry-expert
  • Lifecycle & Governance: brainstorming, zero-to-prod-orchestrator, session-memory-manager, anti-slop
  • Cross-Domain Synergy & Subagent Swarm Integration: double-entry-ledger-fintech-expert, ecommerce-expert

Description

Expert guide for integrating major payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) into modern SaaS platforms. Covers checkout flows, secure raw-body webhook handling, atomic idempotency to prevent race conditions, subscription state machines, and local database synchronization.

Core Principles

  • Security First: Always validate webhook signatures using the raw, unparsed request body before processing any payment event. Never trust client-side data for prices or payment status. For Indonesian gateways (DOKU, Midtrans, Xendit), accurately apply the required signature protocol: DOKU Checkout uses HMAC-SHA256 with body Digest, while SNAP BI Direct APIs enforce HMAC-SHA512 with ISO8601 timestamps.
  • Idempotency & Race Condition Prevention: Implement idempotency keys for all payment creation requests. For webhook ingestion, DO NOT rely solely on findUnique checks, as concurrent webhook retries cause race conditions. Always use Atomic Updates (UPDATE ... WHERE status = 'PENDING') or database pessimistic locks (SELECT ... FOR UPDATE).
  • Raw Body Ingestion: Webhook signature verification fails if JSON is parsed or re-serialized with modified key ordering. Extract the exact raw string buffer (req.text() in Fetch API or express.raw({ type: 'application/json' }) in Express).
  • Early 200 OK Acknowledgment: If a webhook event is verified but already processed, immediately return 200 OK so the payment gateway halts retries.
  • State Synchronization: Ensure the local database (e.g., PostgreSQL, Supabase via Drizzle/Prisma) is updated transactionally upon receiving successful webhook events.
  • Subscription Management: Map provider subscription statuses (trialing, active, past_due, canceled) accurately to internal SaaS state machines.

Implementation Checklist

  • Create dedicated raw Webhook endpoint (e.g., /api/webhooks/stripe, /api/webhooks/doku/checkout).
  • Use raw request body string for signature verification (never parsed JSON).
  • Verify signature using proper algorithm (HMAC-SHA256 + Digest for DOKU Checkout, Stripe, PayPal; HMAC-SHA512 for SNAP BI Direct API).
  • Implement Atomic Update idempotency (WHERE status = 'PENDING') to eliminate race conditions.
  • Acknowledge duplicate webhooks immediately with HTTP 200 OK.
  • Offload heavy post-payment operations (invoicing, emails, webhooks) to background job queues (BullMQ/Temporal).

Example: SNAP BI Webhook & Atomic Idempotency (Next.js App Router)

import { headers } from 'next/headers';
import crypto from 'crypto';
import { db } from '@/lib/db';

export async function POST(req: Request) {
  const rawBody = await req.text(); // Raw body is mandatory
  const headerList = await headers();
  
  const timestamp = headerList.get('x-timestamp') || '';
  const receivedSig = headerList.get('x-signature') || '';
  const authHeader = headerList.get('authorization') || '';
  const token = authHeader.replace(/^Bearer\s+/i, '');
  const path = new URL(req.url).pathname;

  // 1. SNAP BI Body Hash & Signature Verification (HMAC-SHA512)
  const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex').toLowerCase();
  const stringToSign = `POST:${path}:${token}:${bodyHash}:${timestamp}`;
  const calculatedSig = crypto
    .createHmac('sha512', process.env.DOKU_SECRET_KEY!)
    .update(stringToSign, 'utf8')
    .digest('base64');

  const isValid = crypto.timingSafeEqual(Buffer.from(receivedSig), Buffer.from(calculatedSig));
  if (!isValid) {
    return new Response('Invalid Signature', { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  const invoiceNumber = payload.order?.invoice_number;

  // 2. Atomic Update: Eliminates Race Conditions by locking on 'PENDING' status
  const updated = await db.transaction.updateMany({
    where: {
      invoiceNumber: invoiceNumber,
      status: 'PENDING', // Key race condition prevention gate
    },
    data: {
      status: 'PAID',
      paidAt: new Date(),
      externalReference: payload.transaction?.original_reference_no,
    },
  });

  // 3. Duplicate Webhook Handling (Idempotency)
  if (updated.count === 0) {
    // Already processed or invalid invoice — return 200 to halt gateway retry spam
    return new Response(JSON.stringify({ status: 'ALREADY_PROCESSED' }), { status: 200 });
  }

  // 4. Fulfillment (Execute only once)
  await grantUserSubscription(invoiceNumber);

  return new Response(JSON.stringify({ status: 'SUCCESS' }), { status: 200 });
}

async function grantUserSubscription(invoiceNumber: string) {
  // Safe business logic execution
}

Example 2: Multi-Provider Timing-Safe Webhook Signature Verifier (Stripe + DOKU Checkout + Midtrans)

import crypto from 'node:crypto';

export type PaymentProvider = 'stripe' | 'doku-checkout' | 'midtrans';

export function verifyGatewayWebhookSignature(params: {
  readonly provider: PaymentProvider;
  readonly rawBody: string;
  readonly signatureHeader: string;
  readonly secret: string;
  readonly clientId?: string;
  readonly requestId?: string;
  readonly requestTimestamp?: string;
  readonly requestTarget?: string;
}): boolean {
  let expected = '';

  if (params.provider === 'stripe') {
    expected = crypto.createHmac('sha256', params.secret).update(params.rawBody, 'utf8').digest('hex');
  } else if (params.provider === 'doku-checkout') {
    const digest = crypto.createHash('sha256').update(params.rawBody, 'utf8').digest('base64');
    const component = [
      `Client-Id:${params.clientId ?? ''}`,
      `Request-Id:${params.requestId ?? ''}`,
      `Request-Timestamp:${params.requestTimestamp ?? ''}`,
      `Request-Target:${params.requestTarget ?? ''}`,
      `Digest:${digest}`
    ].join('\n');
    const hmac = crypto.createHmac('sha256', params.secret).update(component, 'utf8').digest('base64');
    expected = `HMACSHA256=${hmac}`;
  } else {
    expected = crypto.createHash('sha512').update(params.rawBody + params.secret, 'utf8').digest('hex');
  }

  const a = Buffer.from(params.signatureHeader, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  if (a.byteLength !== b.byteLength) {
    return false;
  }
  return crypto.timingSafeEqual(a, b);
}

Example 3: PostgreSQL Atomic Webhook Inbox & Outbox Locking DDL (SKIP LOCKED)

CREATE TABLE IF NOT EXISTS payment_webhook_inbox (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL,
  provider VARCHAR(32) NOT NULL,
  idempotency_key VARCHAR(128) NOT NULL UNIQUE,
  raw_payload JSONB NOT NULL,
  status VARCHAR(24) NOT NULL DEFAULT 'PENDING',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  processed_at TIMESTAMPTZ
);

CREATE INDEX IF NOT EXISTS idx_webhook_inbox_pending
  ON payment_webhook_inbox (status, created_at)
  WHERE status = 'PENDING';

ALTER TABLE payment_webhook_inbox ENABLE ROW LEVEL SECURITY;

Trigger Conditions

Active whenever the user is working on billing integration, payment checkout, webhook handling, or integrating platforms like PayPal, Stripe, Xendit, Midtrans, or DOKU SNAP BI.

Hard Guardrails (Declarative Invariants)

  1. Mandatory Raw-Body Webhook Signature Verification:
    • Webhook endpoints processing payment callbacks (Stripe, Midtrans, Xendit, DOKU) MUST verify cryptographic signatures against unparsed raw body buffers using crypto.timingSafeEqual. Parsing JSON prior to signature calculation or skipping signature checks is strictly prohibited.
  2. Atomic Idempotent Mutation Invariant:
    • Payment status transitions (e.g. PENDING \(\to\) PAID) MUST execute via atomic database updates with status condition guards (WHERE status = 'PENDING') or idempotent inbox tables (payment_webhook_inbox). Non-atomic read-then-write updates causing double fulfillment are strictly prohibited.
  3. Deterministic Idempotency Key Dispatch:
    • Outbound payment intent creation and charges MUST supply a deterministic Idempotency-Key (UUID derived from order ID or tenant transaction key). Retrying payment requests without idempotency keys is strictly prohibited.
  4. Zero Client-Side Secret Key Exposure:
    • Private payment gateway secret keys (STRIPE_SECRET_KEY, DOKU_SECRET_KEY) MUST NEVER be prefixed with public env tags (NEXT_PUBLIC_, VITE_) or referenced in client-side code.

Blue-Ocean Synergy & Anti-Commodity Protocol

  • Mandatory Blue-Ocean Pairing: Always compose payment-gateway-expert 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 payment-gateway-expert <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 100% cryptographic webhook signature verification, 0 double-spending or race condition fulfillments via atomic inbox locks, 100% idempotency key coverage; 100% complete zero-placeholder output verified via node scripts/check-anti-slop.js --strict


Bahasa Indonesia

Integrasi Orkestrasi

  • Gateway & Integrasi Pembayaran: doku-payment-gateway, saas-billing, agentic-m2m-settlement, agentic-micro-economy-architect
  • AI Agentic Commerce & MCP: doku-mcp-server, mcp-server-architect, ai-llm-integration-expert
  • Database & Idempotensi Atomik: database-orm-expert, saas-multi-tenant
  • Keamanan & Kriptografi Pasca-Kuantum: post-quantum-crypto-migrator, zero-trust-secret-vault, autonomous-red-teamer
  • Antrean Latar Belakang & Observabilitas: async-queue-temporal-expert, data-telemetry-expert
  • Siklus Hidup & Tata Kelola: brainstorming, zero-to-prod-orchestrator, session-memory-manager, anti-slop
  • Sinergi Lintas Domain & Integrasi Swarm Subagent: double-entry-ledger-fintech-expert, ecommerce-expert

Deskripsi

Panduan ahli untuk mengintegrasikan payment gateway utama (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) ke platform SaaS modern. Mencakup alur checkout, penanganan webhook raw-body aman, pencegahan race condition melalui atomic update, state machine langganan, dan sinkronisasi database lokal.

Kondisi Pemicu

Aktif setiap kali pengguna sedang mengerjakan integrasi billing, checkout pembayaran, penanganan webhook, atau mengintegrasikan platform seperti PayPal, Stripe, Xendit, Midtrans, atau DOKU SNAP BI.


Prinsip Utama & Kode Implementasi Webhook Idempoten (TypeScript)

import { headers } from 'next/headers';
import crypto from 'crypto';
import { db } from '@/lib/db';

export async function POST(req: Request) {
  const rawBody = await req.text(); // Wajib membaca raw body mentah sebelum diparse
  const headerList = await headers();

  const timestamp = headerList.get('x-timestamp') || '';
  const signatureDiterima = headerList.get('x-signature') || '';
  const authHeader = headerList.get('authorization') || '';
  const token = authHeader.replace(/^Bearer\s+/i, '');
  const path = new URL(req.url).pathname;

  // 1. Verifikasi Signature HMAC-SHA512 SNAP BI
  const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex').toLowerCase();
  const stringToSign = `POST:${path}:${token}:${bodyHash}:${timestamp}`;
  const signatureDihitung = crypto
    .createHmac('sha512', process.env.DOKU_SECRET_KEY!)
    .update(stringToSign, 'utf8')
    .digest('base64');

  if (!crypto.timingSafeEqual(Buffer.from(signatureDiterima), Buffer.from(signatureDihitung))) {
    return new Response('Tanda Tangan Tidak Valid', { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  const nomorInvoice = payload.order?.invoice_number;

  // 2. Atomic Update: Kunci hanya baris dengan status 'PENDING' untuk mencegah race condition
  const diperbarui = await db.transaksi.updateMany({
    where: { nomorInvoice, status: 'PENDING' },
    data: { status: 'PAID', dibayarPada: new Date() },
  });

  // 3. Penanganan Webhook Duplikat (Idempotensi)
  if (diperbarui.count === 0) {
    return new Response(JSON.stringify({ status: 'SUDAH_DIPROSES' }), { status: 200 });
  }

  // 4. Aktivasi Layanan Pengguna (Hanya dieksekusi 1 kali)
  await aktifkanLangganan(nomorInvoice);
  return new Response(JSON.stringify({ status: 'BERHASIL' }), { status: 200 });
}

Sinergi Blue-Ocean & Protokol Anti-Komoditas

  • Pasangan Wajib Blue-Ocean: Selalu komposisikan payment-gateway-expert 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 payment-gateway-expert <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 100% verifikasi signature webhook kriptografis, 0 double-spending atau pemenuhan ganda via lock inbox atomik, 100% cakupan idempotency key; kode 100% tuntas tanpa placeholder diverifikasi melalui node scripts/check-anti-slop.js --strict
Files (vibes-plug)
  • SKILL.md 16.4 KB
    ---
    name: payment-gateway-expert
    description: "Payment gateways integration (Stripe, Midtrans) and secure webhooks / Integrasi payment gateway (Stripe, Midtrans) dan webhook aman."
    author: "Roedy Rustam"
    version: "4.8.0"
    
    ---
    
    # Payment Gateway Expert / Ahli Payment Gateway
    
    [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
    
    ---
    
    <a name="english"></a>
    ## English
    
    ### Orchestration & Integration
    - **Gateways & Payment Integrations**: `doku-payment-gateway`, `saas-billing`, `agentic-m2m-settlement`, `agentic-micro-economy-architect`
    - **AI Agentic Commerce & MCP**: `doku-mcp-server`, `mcp-server-architect`, `ai-llm-integration-expert`
    - **Database & Atomic Idempotency**: `database-orm-expert`, `saas-multi-tenant`
    - **Security & Post-Quantum Crypto**: `post-quantum-crypto-migrator`, `zero-trust-secret-vault`, `autonomous-red-teamer`
    - **Background Jobs & Observability**: `async-queue-temporal-expert`, `data-telemetry-expert`
    - **Lifecycle & Governance**: `brainstorming`, `zero-to-prod-orchestrator`, `session-memory-manager`, `anti-slop`
    - **Cross-Domain Synergy & Subagent Swarm Integration**: `double-entry-ledger-fintech-expert`, `ecommerce-expert`
    
    ### Description
    Expert guide for integrating major payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) into modern SaaS platforms. Covers checkout flows, secure raw-body webhook handling, atomic idempotency to prevent race conditions, subscription state machines, and local database synchronization.
    
    ### Core Principles
    - **Security First**: Always validate webhook signatures using the raw, unparsed request body before processing any payment event. Never trust client-side data for prices or payment status. For Indonesian gateways (DOKU, Midtrans, Xendit), accurately apply the required signature protocol: **DOKU Checkout** uses **HMAC-SHA256 with body Digest**, while **SNAP BI Direct APIs** enforce **HMAC-SHA512** with ISO8601 timestamps.
    - **Idempotency & Race Condition Prevention**: Implement idempotency keys for all payment creation requests. For webhook ingestion, **DO NOT rely solely on `findUnique` checks**, as concurrent webhook retries cause race conditions. Always use **Atomic Updates** (`UPDATE ... WHERE status = 'PENDING'`) or database pessimistic locks (`SELECT ... FOR UPDATE`).
    - **Raw Body Ingestion**: Webhook signature verification fails if JSON is parsed or re-serialized with modified key ordering. Extract the exact raw string buffer (`req.text()` in Fetch API or `express.raw({ type: 'application/json' })` in Express).
    - **Early 200 OK Acknowledgment**: If a webhook event is verified but already processed, immediately return `200 OK` so the payment gateway halts retries.
    - **State Synchronization**: Ensure the local database (e.g., PostgreSQL, Supabase via Drizzle/Prisma) is updated transactionally upon receiving successful webhook events.
    - **Subscription Management**: Map provider subscription statuses (`trialing`, `active`, `past_due`, `canceled`) accurately to internal SaaS state machines.
    
    ### Implementation Checklist
    - [ ] Create dedicated raw Webhook endpoint (e.g., `/api/webhooks/stripe`, `/api/webhooks/doku/checkout`).
    - [ ] Use raw request body string for signature verification (never parsed JSON).
    - [ ] Verify signature using proper algorithm (HMAC-SHA256 + Digest for DOKU Checkout, Stripe, PayPal; HMAC-SHA512 for SNAP BI Direct API).
    - [ ] Implement Atomic Update idempotency (`WHERE status = 'PENDING'`) to eliminate race conditions.
    - [ ] Acknowledge duplicate webhooks immediately with HTTP `200 OK`.
    - [ ] Offload heavy post-payment operations (invoicing, emails, webhooks) to background job queues (BullMQ/Temporal).
    
    ### Example: SNAP BI Webhook & Atomic Idempotency (Next.js App Router)
    ```typescript
    import { headers } from 'next/headers';
    import crypto from 'crypto';
    import { db } from '@/lib/db';
    
    export async function POST(req: Request) {
      const rawBody = await req.text(); // Raw body is mandatory
      const headerList = await headers();
      
      const timestamp = headerList.get('x-timestamp') || '';
      const receivedSig = headerList.get('x-signature') || '';
      const authHeader = headerList.get('authorization') || '';
      const token = authHeader.replace(/^Bearer\s+/i, '');
      const path = new URL(req.url).pathname;
    
      // 1. SNAP BI Body Hash & Signature Verification (HMAC-SHA512)
      const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex').toLowerCase();
      const stringToSign = `POST:${path}:${token}:${bodyHash}:${timestamp}`;
      const calculatedSig = crypto
        .createHmac('sha512', process.env.DOKU_SECRET_KEY!)
        .update(stringToSign, 'utf8')
        .digest('base64');
    
      const isValid = crypto.timingSafeEqual(Buffer.from(receivedSig), Buffer.from(calculatedSig));
      if (!isValid) {
        return new Response('Invalid Signature', { status: 401 });
      }
    
      const payload = JSON.parse(rawBody);
      const invoiceNumber = payload.order?.invoice_number;
    
      // 2. Atomic Update: Eliminates Race Conditions by locking on 'PENDING' status
      const updated = await db.transaction.updateMany({
        where: {
          invoiceNumber: invoiceNumber,
          status: 'PENDING', // Key race condition prevention gate
        },
        data: {
          status: 'PAID',
          paidAt: new Date(),
          externalReference: payload.transaction?.original_reference_no,
        },
      });
    
      // 3. Duplicate Webhook Handling (Idempotency)
      if (updated.count === 0) {
        // Already processed or invalid invoice — return 200 to halt gateway retry spam
        return new Response(JSON.stringify({ status: 'ALREADY_PROCESSED' }), { status: 200 });
      }
    
      // 4. Fulfillment (Execute only once)
      await grantUserSubscription(invoiceNumber);
    
      return new Response(JSON.stringify({ status: 'SUCCESS' }), { status: 200 });
    }
    
    async function grantUserSubscription(invoiceNumber: string) {
      // Safe business logic execution
    }
    ```
    
    ### Example 2: Multi-Provider Timing-Safe Webhook Signature Verifier (Stripe + DOKU Checkout + Midtrans)
    ```typescript
    import crypto from 'node:crypto';
    
    export type PaymentProvider = 'stripe' | 'doku-checkout' | 'midtrans';
    
    export function verifyGatewayWebhookSignature(params: {
      readonly provider: PaymentProvider;
      readonly rawBody: string;
      readonly signatureHeader: string;
      readonly secret: string;
      readonly clientId?: string;
      readonly requestId?: string;
      readonly requestTimestamp?: string;
      readonly requestTarget?: string;
    }): boolean {
      let expected = '';
    
      if (params.provider === 'stripe') {
        expected = crypto.createHmac('sha256', params.secret).update(params.rawBody, 'utf8').digest('hex');
      } else if (params.provider === 'doku-checkout') {
        const digest = crypto.createHash('sha256').update(params.rawBody, 'utf8').digest('base64');
        const component = [
          `Client-Id:${params.clientId ?? ''}`,
          `Request-Id:${params.requestId ?? ''}`,
          `Request-Timestamp:${params.requestTimestamp ?? ''}`,
          `Request-Target:${params.requestTarget ?? ''}`,
          `Digest:${digest}`
        ].join('\n');
        const hmac = crypto.createHmac('sha256', params.secret).update(component, 'utf8').digest('base64');
        expected = `HMACSHA256=${hmac}`;
      } else {
        expected = crypto.createHash('sha512').update(params.rawBody + params.secret, 'utf8').digest('hex');
      }
    
      const a = Buffer.from(params.signatureHeader, 'utf8');
      const b = Buffer.from(expected, 'utf8');
      if (a.byteLength !== b.byteLength) {
        return false;
      }
      return crypto.timingSafeEqual(a, b);
    }
    ```
    
    ### Example 3: PostgreSQL Atomic Webhook Inbox & Outbox Locking DDL (`SKIP LOCKED`)
    ```sql
    CREATE TABLE IF NOT EXISTS payment_webhook_inbox (
      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
      tenant_id UUID NOT NULL,
      provider VARCHAR(32) NOT NULL,
      idempotency_key VARCHAR(128) NOT NULL UNIQUE,
      raw_payload JSONB NOT NULL,
      status VARCHAR(24) NOT NULL DEFAULT 'PENDING',
      attempt_count INTEGER NOT NULL DEFAULT 0,
      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
      processed_at TIMESTAMPTZ
    );
    
    CREATE INDEX IF NOT EXISTS idx_webhook_inbox_pending
      ON payment_webhook_inbox (status, created_at)
      WHERE status = 'PENDING';
    
    ALTER TABLE payment_webhook_inbox ENABLE ROW LEVEL SECURITY;
    ```
    
    ### Trigger Conditions
    Active whenever the user is working on billing integration, payment checkout, webhook handling, or integrating platforms like PayPal, Stripe, Xendit, Midtrans, or DOKU SNAP BI.
    
    ### Hard Guardrails (Declarative Invariants)
    1. **Mandatory Raw-Body Webhook Signature Verification**:
       - Webhook endpoints processing payment callbacks (Stripe, Midtrans, Xendit, DOKU) MUST verify cryptographic signatures against unparsed raw body buffers using `crypto.timingSafeEqual`. Parsing JSON prior to signature calculation or skipping signature checks is strictly prohibited.
    2. **Atomic Idempotent Mutation Invariant**:
       - Payment status transitions (e.g. `PENDING` $\to$ `PAID`) MUST execute via atomic database updates with status condition guards (`WHERE status = 'PENDING'`) or idempotent inbox tables (`payment_webhook_inbox`). Non-atomic read-then-write updates causing double fulfillment are strictly prohibited.
    3. **Deterministic Idempotency Key Dispatch**:
       - Outbound payment intent creation and charges MUST supply a deterministic `Idempotency-Key` (UUID derived from order ID or tenant transaction key). Retrying payment requests without idempotency keys is strictly prohibited.
    4. **Zero Client-Side Secret Key Exposure**:
       - Private payment gateway secret keys (`STRIPE_SECRET_KEY`, `DOKU_SECRET_KEY`) MUST NEVER be prefixed with public env tags (`NEXT_PUBLIC_`, `VITE_`) or referenced in client-side code.
    
    ### Blue-Ocean Synergy & Anti-Commodity Protocol
    - **Mandatory Blue-Ocean Pairing**: Always compose `payment-gateway-expert` 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 payment-gateway-expert <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** | 100% cryptographic webhook signature verification, 0 double-spending or race condition fulfillments via atomic inbox locks, 100% idempotency key coverage; 100% complete zero-placeholder output verified via `node scripts/check-anti-slop.js --strict` |
    
    ---
    
    
    ---
    
    <a name="bahasa-indonesia"></a>
    ## Bahasa Indonesia
    
    ### Integrasi Orkestrasi
    - **Gateway & Integrasi Pembayaran**: `doku-payment-gateway`, `saas-billing`, `agentic-m2m-settlement`, `agentic-micro-economy-architect`
    - **AI Agentic Commerce & MCP**: `doku-mcp-server`, `mcp-server-architect`, `ai-llm-integration-expert`
    - **Database & Idempotensi Atomik**: `database-orm-expert`, `saas-multi-tenant`
    - **Keamanan & Kriptografi Pasca-Kuantum**: `post-quantum-crypto-migrator`, `zero-trust-secret-vault`, `autonomous-red-teamer`
    - **Antrean Latar Belakang & Observabilitas**: `async-queue-temporal-expert`, `data-telemetry-expert`
    - **Siklus Hidup & Tata Kelola**: `brainstorming`, `zero-to-prod-orchestrator`, `session-memory-manager`, `anti-slop`
    - **Sinergi Lintas Domain & Integrasi Swarm Subagent**: `double-entry-ledger-fintech-expert`, `ecommerce-expert`
    
    ### Deskripsi
    Panduan ahli untuk mengintegrasikan payment gateway utama (Stripe, PayPal, Xendit, Midtrans, DOKU SNAP BI) ke platform SaaS modern. Mencakup alur checkout, penanganan webhook raw-body aman, pencegahan race condition melalui atomic update, state machine langganan, dan sinkronisasi database lokal.
    
    ### Kondisi Pemicu
    Aktif setiap kali pengguna sedang mengerjakan integrasi billing, checkout pembayaran, penanganan webhook, atau mengintegrasikan platform seperti PayPal, Stripe, Xendit, Midtrans, atau DOKU SNAP BI.
    
    ---
    
    ### Prinsip Utama & Kode Implementasi Webhook Idempoten (TypeScript)
    
    ```typescript
    import { headers } from 'next/headers';
    import crypto from 'crypto';
    import { db } from '@/lib/db';
    
    export async function POST(req: Request) {
      const rawBody = await req.text(); // Wajib membaca raw body mentah sebelum diparse
      const headerList = await headers();
    
      const timestamp = headerList.get('x-timestamp') || '';
      const signatureDiterima = headerList.get('x-signature') || '';
      const authHeader = headerList.get('authorization') || '';
      const token = authHeader.replace(/^Bearer\s+/i, '');
      const path = new URL(req.url).pathname;
    
      // 1. Verifikasi Signature HMAC-SHA512 SNAP BI
      const bodyHash = crypto.createHash('sha256').update(rawBody, 'utf8').digest('hex').toLowerCase();
      const stringToSign = `POST:${path}:${token}:${bodyHash}:${timestamp}`;
      const signatureDihitung = crypto
        .createHmac('sha512', process.env.DOKU_SECRET_KEY!)
        .update(stringToSign, 'utf8')
        .digest('base64');
    
      if (!crypto.timingSafeEqual(Buffer.from(signatureDiterima), Buffer.from(signatureDihitung))) {
        return new Response('Tanda Tangan Tidak Valid', { status: 401 });
      }
    
      const payload = JSON.parse(rawBody);
      const nomorInvoice = payload.order?.invoice_number;
    
      // 2. Atomic Update: Kunci hanya baris dengan status 'PENDING' untuk mencegah race condition
      const diperbarui = await db.transaksi.updateMany({
        where: { nomorInvoice, status: 'PENDING' },
        data: { status: 'PAID', dibayarPada: new Date() },
      });
    
      // 3. Penanganan Webhook Duplikat (Idempotensi)
      if (diperbarui.count === 0) {
        return new Response(JSON.stringify({ status: 'SUDAH_DIPROSES' }), { status: 200 });
      }
    
      // 4. Aktivasi Layanan Pengguna (Hanya dieksekusi 1 kali)
      await aktifkanLangganan(nomorInvoice);
      return new Response(JSON.stringify({ status: 'BERHASIL' }), { status: 200 });
    }
    ```
    
    ### Sinergi Blue-Ocean & Protokol Anti-Komoditas
    - **Pasangan Wajib Blue-Ocean**: Selalu komposisikan `payment-gateway-expert` 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 payment-gateway-expert <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** | 100% verifikasi signature webhook kriptografis, 0 double-spending atau pemenuhan ganda via lock inbox atomik, 100% cakupan idempotency key; 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.