Cara Mencegah Pembayaran Ganda di Next.js Server Actions dengan Transaksi MySQL (SELECT ... FOR UPDATE)
Bayangkan bendahara TK menekan tombol Terima pembayaran dua kali karena internet sekolah lambat. Atau dua petugas membuka halaman siswa yang sama lalu mencatat pembayaran hampir bersamaan. Kalau kodenya hanya "cek sisa tagihan lalu simpan", hasilnya bisa fatal: kuitansi dobel, kas tercatat lebih besar dari uang yang diterima, atau saldo tabungan anak terpotong dua kali.
Di tutorial ini kita lihat kenapa masalah itu terjadi di Next.js Server Actions dan cara mencegahnya dengan transaksi MySQL + SELECT ... FOR UPDATE. Contohnya diambil dari Aplikasi SPP & Tabungan TK yang bisa kamu download gratis di Papicode (link di akhir artikel).
1. Kode yang kelihatannya benar
Server Action pembayaran yang paling sederhana biasanya seperti ini:
"use server";
export async function bayar(tagihanId: number, jumlah: number) {
const t = await row("SELECT nominal, terbayar FROM tagihan WHERE id = ?", [tagihanId]);
const sisa = t.nominal - t.terbayar;
if (jumlah > sisa) throw new Error("Melebihi sisa tagihan");
await exec("INSERT INTO pembayaran (tagihan_id, jumlah) VALUES (?, ?)", [tagihanId, jumlah]);
await exec("UPDATE tagihan SET terbayar = terbayar + ? WHERE id = ?", [jumlah, tagihanId]);
}
Masalahnya ada di jarak antara membaca (SELECT) dan menulis (UPDATE). Dua request yang datang bersamaan sama-sama membaca terbayar = 0, sama-sama lolos pengecekan, lalu sama-sama menyimpan. SPP Rp175.000 akhirnya tercatat dibayar Rp350.000.
Menonaktifkan tombol di sisi browser membantu, tapi tidak cukup: request kedua bisa datang dari tab lain, HP lain, atau petugas lain. Penjaganya harus ada di database.
2. Siapkan helper transaksi
Dengan mysql2/promise, satu transaksi harus memakai satu koneksi yang sama dari awal sampai COMMIT. Buat helper kecil supaya tidak lupa rollback dan release:
// src/lib/db.ts
import mysql, { type PoolConnection } from "mysql2/promise";
const pool = mysql.createPool({ host: "127.0.0.1", user: "root", database: "spp_tk", connectionLimit: 8 });
export async function tx<T>(fn: (c: PoolConnection) => Promise<T>): Promise<T> {
const c = await pool.getConnection();
try {
await c.beginTransaction();
const hasil = await fn(c);
await c.commit();
return hasil;
} catch (e) {
await c.rollback();
throw e;
} finally {
c.release();
}
}
Semua query di dalam fn wajib memakai koneksi c, bukan pool. Kalau memakai pool, query itu berjalan di koneksi lain dan berada di luar transaksi.
3. Kunci baris dengan FOR UPDATE
SELECT ... FOR UPDATE membaca baris sekaligus menguncinya sampai transaksi selesai. Transaksi lain yang mencoba mengunci baris yang sama akan menunggu, lalu membaca data yang sudah diperbarui.
Di aplikasi SPP, yang dikunci adalah baris siswa. Satu siswa bisa punya beberapa tagihan dan juga saldo tabungan, jadi mengunci siswa membuat semua pembayaran untuk anak itu berjalan bergantian:
export async function bayar(siswaId: number, tagihanIds: number[], jumlah: number, metode: "tunai" | "transfer" | "tabungan") {
return tx(async (c) => {
// 1) Kunci siswa: pembayaran lain untuk anak ini menunggu di sini
const [[s]] = await c.query<any[]>("SELECT id, saldo_tabungan FROM siswa WHERE id = ? FOR UPDATE", [siswaId]);
// 2) Baca ulang tagihan SETELAH terkunci, hanya yang belum lunas
const [tg] = await c.query<any[]>(
`SELECT id, (nominal - potongan - terbayar) sisa FROM tagihan
WHERE siswa_id = ? AND id IN (?) AND status IN ('belum','sebagian')
ORDER BY jatuh_tempo FOR UPDATE`, [siswaId, tagihanIds]);
const sisaTotal = tg.reduce((a, t) => a + Number(t.sisa), 0);
if (!tg.length) throw new Gagal("Tagihan sudah lunas.");
if (jumlah > sisaTotal) throw new Gagal("Jumlah melebihi sisa tagihan.");
(metode === && s. < jumlah) ();
});
}
Sekarang urutannya aman:
- Request A mengunci siswa, membaca sisa Rp175.000, menyimpan, lalu
COMMIT. - Request B yang sejak tadi menunggu baru bisa membaca, dan melihat tagihan sudah
lunas, sehingga ditolak dengan pesan "Tagihan sudah lunas".
Perhatikan bahwa pengecekan dilakukan setelah baris terkunci. Kalau sisa tagihan dibaca dulu lalu baru dikunci, kita kembali ke masalah semula.
4. Status dihitung di dalam UPDATE
Saat menambah terbayar, status tagihan dihitung langsung oleh MySQL di query yang sama:
UPDATE tagihan
SET terbayar = terbayar + ?,
status = IF(terbayar >= nominal - potongan, 'lunas', 'sebagian')
WHERE id = ?
Pada UPDATE satu tabel, MySQL memproses SET dari kiri ke kanan, jadi status sudah memakai nilai terbayar yang baru. Tidak ada lagi jarak antara menghitung di JavaScript dan menyimpan ke database.
5. Nomor kuitansi yang tidak bisa bentrok
Cara populer SELECT MAX(no) + 1 juga rawan dobel bila dua kasir mencatat pembayaran untuk siswa berbeda (yang tidak saling mengunci). Solusi paling sederhana: turunkan nomor dari AUTO_INCREMENT, yang dijamin unik oleh MySQL.
const [ins] = await c.query<any>(
"INSERT INTO pembayaran (no_kuitansi, siswa_id, tanggal, total, metode) VALUES (?, ?, NOW(), ?, ?)",
["TMP-" + crypto.randomUUID().slice(0, 8), siswaId, jumlah, metode]);
const no = "KW-" + String(ins.insertId).padStart(5, "0"); // KW-00412
await c.query("UPDATE pembayaran SET no_kuitansi = ? WHERE id = ?", [no, ins.insertId]);
Kolom no_kuitansi tetap diberi UNIQUE sebagai pengaman terakhir.
6. Hindari deadlock saat mengunci banyak baris
Fitur setoran hari menabung menyimpan setoran satu kelas sekaligus, jadi banyak baris siswa dikunci dalam satu transaksi. Kalau dua guru menyimpan setoran kelas yang sama dengan urutan berbeda, keduanya bisa saling menunggu (deadlock). Kuncinya: selalu kunci dengan urutan yang sama, misalnya berdasarkan id.
return tx(async (c) => {
for (const d of [...data].sort((a, b) => a.siswaId - b.siswaId)) {
const [[s]] = await c.query<any[]>("SELECT id, saldo_tabungan FROM siswa WHERE id = ? FOR UPDATE", [d.siswaId]);
const saldo = s.saldo_tabungan + d.jumlah;
await c.query("UPDATE siswa SET saldo_tabungan = ? WHERE id = ?", [saldo, s.id]);
await c.query(
"INSERT INTO tabungan (siswa_id, tanggal, jenis, jumlah, saldo_setelah) VALUES (?, NOW(), 'setor', ?, ?)",
[s.id, d.jumlah, saldo]);
}
});
Karena semuanya dalam satu transaksi, setoran 25 anak masuk semua atau tidak sama sekali. Tidak akan ada kondisi setengah kelas tercatat lalu error di tengah jalan.
7. Pesan galat yang aman di Server Action
Bedakan kesalahan yang memang untuk pengguna dengan error tak terduga. Buat kelas khusus, lalu tangkap di Server Action:
export class Gagal extends Error {}
export async function terimaBayar(fd: FormData) {
let id = 0;
try {
id = await bayar(/* ... */);
} catch (e) {
const pesan = e instanceof Gagal ? e.message : "Terjadi kesalahan di server.";
if (!(e instanceof Gagal)) console.error(e);
redirect(`/siswa/${siswaId}?err=${encodeURIComponent(pesan)}`);
}
redirect(`/kuitansi/${id}`);
}
Ingat bahwa redirect() bekerja dengan melempar exception khusus. Jangan memanggilnya di dalam try yang menangkap semua error, karena redirect-nya ikut tertangkap.
8. Mengujinya
Cara paling jujur untuk menguji adalah benar-benar menekan tombol bayar di dua tab bersamaan. Di aplikasi ini, tes end-to-end memakai Playwright untuk membuka dua tab, mencentang tagihan yang sama, lalu mengklik Terima pembayaran di keduanya dalam waktu yang sama:
await Promise.all([tab1.click("text=Terima pembayaran"), tab2.click("text=Terima pembayaran")]);
// total pembayaran untuk tagihan itu harus tetap = nominal tagihan
Hasilnya, satu kuitansi tercatat dan tab lainnya mendapat pesan "Tagihan sudah lunas".
Ringkasan
- Jangan memisahkan "cek lalu simpan" tanpa penguncian. Validasi di browser saja tidak cukup.
- Bungkus pembayaran dalam transaksi dan pakai satu koneksi yang sama untuk semua query.
- Kunci baris induk (siswa) dengan
SELECT ... FOR UPDATE, lalu baca ulang data setelah terkunci. - Hitung status di dalam
UPDATE, ambil nomor kuitansi dariAUTO_INCREMENT. - Saat mengunci banyak baris, kunci dengan urutan yang sama untuk mencegah deadlock.
Download source code lengkapnya
Semua teknik di atas sudah dipakai di Aplikasi SPP & Tabungan TK (Next.js + MySQL): terbit SPP bulanan sekali klik, pembayaran cicilan dengan kuitansi, pembatalan yang mengembalikan saldo, pengingat WhatsApp otomatis, buku tabungan siswa, setoran hari menabung per kelas, dan portal wali murid. Gratis dan cukup dijalankan dengan Node.js + XAMPP.
Source code lengkapnya gratis
Lihat semua yang dibahas di artikel ini langsung berjalan.