Integrasi Payment Gateway Indonesia: Menangani Webhook Midtrans dan Xendit dengan Jaminan Idempoten

Alur Penanganan Webhook Idempoten Payment Gateway:
[Penyedia Payment Gateway (Midtrans / Xendit)]
               │
               ▼ POST /api/webhooks/payment (Membawa Signature Hash)
┌─────────────────────────────────────────────────────────────┐
│  API Gateway / HTTP Controller                              │
│  1. Verifikasi Signature Kriptografis (SHA-512 / HMAC)      │
│  2. Jika Signature Tidak Cocok ────> [Tolak: HTTP 401/403]  │
│  3. Simpan Payload ke Antrean Redis Message Queue           │
│  4. Balas Segera ke Gateway: HTTP 200 OK (< 200 milidetik)  │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼ (Asynchronous Processing)
┌─────────────────────────────────────────────────────────────┐
│  Background Worker (NestJS / BullMQ / Go Worker)            │
│  1. Buka PostgreSQL Transaction dengan Lock Eksklusif       │
│  2. Cek Tabel Idempotency: Apakah Transaction ID sudah ada? │
│     ├── SUDAH PROSES  ──> Abaikan Payload Duplikat          │
│     └── BELUM PROSES ──> Perbarui Status Pesanan ke PAID    │
│  3. Terbitkan Faktur Pajak & Kirim Email Notifikasi         │
└─────────────────────────────────────────────────────────────┘

import crypto from 'crypto';

export function verifyMidtransSignature(payload: {
  order_id: string;
  status_code: string;
  gross_amount: string;
  signature_key: string;
}, serverKey: string): boolean {
  const rawString = `${payload.order_id}${payload.status_code}${payload.gross_amount}${serverKey}`;
  const calculatedHash = crypto.createHash('sha512').update(rawString).digest('hex');

  // Gunakan timingSafeEqual untuk mencegah serangan timing-attack
  return crypto.timingSafeEqual(
    Buffer.from(calculatedHash),
    Buffer.from(payload.signature_key)
  );
}

export function verifyXenditCallbackToken(
  incomingToken: string | undefined,
  expectedToken: string
): boolean {
  if (!incomingToken) return false;
  return crypto.timingSafeEqual(
    Buffer.from(incomingToken),
    Buffer.from(expectedToken)
  );
}

// app/api/webhooks/midtrans/route.ts
import { NextResponse } from 'next/server';
import { paymentQueue } from '@/lib/queue';
import { verifyMidtransSignature } from '@/lib/payment-security';

export async function POST(request: Request) {
  const payload = await request.json();

  // 1. Validasi Tanda Tangan Kriptografis
  const isValid = verifyMidtransSignature(payload, process.env.MIDTRANS_SERVER_KEY!);
  if (!isValid) {
    return NextResponse.json({ error: 'Invalid Signature Key' }, { status: 403 });
  }

  // 2. Masukkan ke BullMQ Queue untuk diproses di latar belakang
  await paymentQueue.add('process_payment_status', payload, {
    attempts: 5,
    backoff: { type: 'exponential', delay: 2000 },
    removeOnComplete: true,
  });

  // 3. Konfirmasi penerimaan segera ke Payment Gateway
  return NextResponse.json({ status: 'OK', message: 'Webhook received' });
}

-- Skema Tabel Idempotency Ledger
CREATE TABLE payment_webhook_logs (
    id SERIAL PRIMARY KEY,
    transaction_id VARCHAR(100) NOT NULL UNIQUE,
    order_id VARCHAR(100) NOT NULL,
    payment_status VARCHAR(50) NOT NULL,
    payload JSONB NOT NULL,
    processed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

// workers/payment.worker.ts
import { pool } from '@/lib/db';

export async function processPaymentTransaction(payload: any) {
  const client = await pool.connect();

  try {
    await client.query('BEGIN');

    // 1. Kunci baris pesanan untuk mencegah proses paralel
    const orderRes = await client.query(
      'SELECT id, status, total_amount FROM orders WHERE id = $1 FOR UPDATE',
      [payload.order_id]
    );

    if (orderRes.rows.length === 0) {
      await client.query('ROLLBACK');
      return;
    }

    const currentOrder = orderRes.rows[0];

    // Jika pesanan sudah berstatus PAID sebelumnya, abaikan webhook ini (Idempoten)
    if (currentOrder.status === 'PAID') {
      await client.query('ROLLBACK');
      console.log(`[Idempotent Skip] Pesanan ${payload.order_id} sudah pernah dibayar.`);
      return;
    }

    // 2. Evaluasi status transaksi dari gateway
    if (payload.transaction_status === 'settlement' || payload.transaction_status === 'capture') {
      // Perbarui status pesanan menjadi LUNAS
      await client.query(
        'UPDATE orders SET status = $1, payment_method = $2, paid_at = NOW() WHERE id = $3',
        ['PAID', payload.payment_type, payload.order_id]
      );

      // Catat ke log idempotensi
      await client.query(
        'INSERT INTO payment_webhook_logs (transaction_id, order_id, payment_status, payload) VALUES ($1, $2, $3, $4)',
        [payload.transaction_id, payload.order_id, 'PAID', JSON.stringify(payload)]
      );
    }

    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err; // Memicu retry otomatis BullMQ
  } finally {
    client.release();
  }
}