Idempotensi & notifikasi yang datang tidak berurutan

Midtrans menyatakan sendiri bahwa notifikasi bisa terkirim ganda dan bisa tiba tidak berurutan. Kode yang tidak menyiapkan keduanya akan salah menghitung uang.

Jurnal notifikasi

CREATE TABLE notifikasi_pembayaran (
  id             BIGINT AUTO_INCREMENT PRIMARY KEY,
  transaction_id VARCHAR(64)  NOT NULL,
  order_id       VARCHAR(100) NOT NULL,
  status         VARCHAR(32)  NOT NULL,
  isi            JSON         NOT NULL,
  diterima_pada  DATETIME     NOT NULL,
  UNIQUE KEY uq_notif (transaction_id, status),
  INDEX idx_order (order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

UNIQUE (transaction_id, status) yang melakukan pekerjaan berat. Notifikasi yang sama persis tidak bisa masuk dua kali; perubahan status yang sah tetap bisa.

Pemrosesan yang idempoten

// src/lib/pembayaran.ts
export async function prosesNotifikasi(n: Notifikasi) {
  await dbTulis.transaction().execute(async (trx) => {
    // 1. Catat. Kalau duplikat, berhenti di sini.
    const catat = await trx
      .insertInto("notifikasi_pembayaran")
      .values({
        transaction_id: n.transaction_id,
        order_id: n.order_id,
        status: n.transaction_status,
        isi: JSON.stringify(n),
        diterima_pada: new Date(),
      })
      .ignore()                       // MySQL: INSERT IGNORE
      .executeTakeFirstOrThrow();

    if (catat.numInsertedOrUpdatedRows === 0n) {
      return;                          // sudah pernah diproses
    }

    // 2. Ambil langganannya dan KUNCI barisnya.
    const lgn = await trx
      .selectFrom("langganan")
      .selectAll()
      .where("order_id", "=", n.order_id)
      .forUpdate()
      .executeTakeFirst();

    if (!lgn) {
      console.warn(JSON.stringify({ level: "warn", pesan: "order tidak dikenal", order_id: n.order_id }));
      return;                          // tetap 200: mengulanginya tidak akan menolong
    }

    // 3. Jangan turunkan status yang sudah final.
    if (FINAL.has(lgn.status) && n.transaction_status === "pending") {
      return;
    }

    // 4. Terapkan.
    if (pembayaranBerhasil(n)) {
      await aktifkan(trx, lgn);
    } else if (["deny", "cancel", "expire"].includes(n.transaction_status)) {
      await trx.updateTable("langganan")
        .set({ status: "gagal", diperbarui_pada: new Date() })
        .where("id", "=", lgn.id).execute();
    } else if (["refund", "partial_refund", "chargeback"].includes(n.transaction_status)) {
      await cabutAkses(trx, lgn);
    }
  });
}

const FINAL = new Set(["aktif", "gagal", "dibatalkan"]);

Perpanjangan yang benar

async function aktifkan(trx: Trx, lgn: Langganan) {
  const paket = await ambilPaket(lgn.paket, trx);

  // Perpanjang dari tanggal berakhir yang ADA kalau masih berlaku,
  // bukan dari hari ini. Kalau tidak, pelanggan yang memperpanjang
  // lebih awal kehilangan sisa waktunya.
  const m = await trx.selectFrom("member")
    .select("langganan_sampai")
    .where("id", "=", lgn.member_id)
    .executeTakeFirstOrThrow();

  const mulai =
    m.langganan_sampai && m.langganan_sampai > new Date()
      ? m.langganan_sampai
      : new Date();

  const sampai = new Date(mulai);
  sampai.setDate(sampai.getDate() + paket.durasiHari);

  await trx.updateTable("member")
    .set({ tier: paket.tier, langganan_sampai: sampai })
    .where("id", "=", lgn.member_id)
    .execute();

  await trx.updateTable("langganan")
    .set({ status: "aktif", aktif_pada: new Date(), berlaku_sampai: sampai })
    .where("id", "=", lgn.id)
    .execute();
}

Notifikasi yang tiba tidak berurutan

Yang seharusnya:  pending → settlement
Yang bisa terjadi: settlement → pending

Midtrans menyatakan ini terjadi dalam kasus yang sangat jarang. Kalau kodemu memproses apa adanya, status langganan akan turun dari "aktif" ke "menunggu" — dan pelanggan yang sudah membayar tiba-tiba melihat paywall lagi.

Dua pertahanan, dipakai bersamaan: jangan pernah menurunkan status final (langkah 3 di kode di atas), dan kalau ragu, tanya.

GET Status API sebagai wasit

export async function statusSebenarnya(orderId: string) {
  const basis = env.MIDTRANS_PRODUKSI
    ? "https://api.midtrans.com/v2"
    : "https://api.sandbox.midtrans.com/v2";

  const res = await fetch(`${basis}/${encodeURIComponent(orderId)}/status`, {
    headers: { Accept: "application/json", Authorization: otorisasi() },
    signal: AbortSignal.timeout(8000),
  });

  if (!res.ok) throw new Error(`status API: ${res.status}`);
  return res.json();
}

Panggil ini dalam tiga situasi: saat notifikasi tiba tidak berurutan, saat pelanggan melapor sudah membayar tapi belum aktif, dan sebagai penyapu berkala untuk pesanan yang menggantung. Jangan memanggilnya di dalam handler webhook — itu melanggar anggaran 5 detik.

Penyapu berkala

// Dijalankan tiap 15 menit sebagai tugas terjadwal (Fase 10)
export async function sapuPesananMenggantung() {
  const menggantung = await dbBaca
    .selectFrom("langganan")
    .select(["id", "order_id"])
    .where("status", "=", "menunggu")
    .where("dibuat_pada", "<", new Date(Date.now() - 20 * 60 * 1000))
    .where("dibuat_pada", ">", new Date(Date.now() - 48 * 60 * 60 * 1000))
    .limit(100)
    .execute();

  for (const l of menggantung) {
    try {
      const s = await statusSebenarnya(l.order_id);
      await prosesNotifikasi(s);       // idempoten — aman dipanggil ulang
    } catch (e) {
      console.error(JSON.stringify({ level: "error", order_id: l.order_id, e: String(e) }));
    }
  }
}

Yang harus bisa kamu jawab