Home / Artikel / Web Development
Web Development

Klik Dua Kali, Pesanan Dua Kali? Mencegah Transaksi Ganda dengan Idempotency Key

Jaringan lambat, tombol pembayaran ditekan berulang, atau respons API hilang bisa membuat satu pesanan tercatat dua kali. Idempotency key membantu aplikasi mengenali bahwa beberapa request sebenarnya adalah percobaan ya…

Klik Dua Kali, Pesanan Dua Kali? Mencegah Transaksi Ganda dengan Idempotency Key

Pernah menekan tombol “Bayar” lalu halaman berhenti beberapa detik? Karena takut gagal, tombol itu ditekan lagi. Beberapa saat kemudian, dua pesanan masuk atau saldo terpotong dua kali.

Masalah seperti ini bukan selalu akibat pengguna ceroboh. Dalam aplikasi web, request bisa sudah diproses server ketika koneksi terputus sebelum browser menerima jawabannya. Dari sisi pengguna, transaksi terlihat gagal. Dari sisi server, transaksi mungkin sebenarnya sudah berhasil.

Di sinilah idempotency key berguna. Sederhananya, idempotency key adalah nomor unik untuk menandai satu operasi. Jika request yang sama dikirim ulang dengan nomor tersebut, server tidak membuat transaksi baru. Server cukup mengembalikan hasil dari proses pertama.

Memahami masalahnya: request bisa berhasil tanpa respons sampai ke browser

Bayangkan aplikasi kasir mengirim request untuk membuat pesanan. Alurnya terlihat sederhana:

  1. Browser mengirim request ke server.
  2. Server menyimpan pesanan ke database.
  3. Server mengirim respons sukses.
  4. Browser menampilkan nomor pesanan.

Gangguan bisa terjadi di antara langkah kedua dan ketiga. Database sudah menyimpan pesanan, tetapi koneksi terputus sebelum respons diterima browser. Browser lalu menganggap proses gagal dan mengirim request baru.

Jika endpoint tersebut menggunakan POST biasa tanpa perlindungan, server tidak tahu bahwa request kedua adalah pengulangan. Akibatnya, dua baris pesanan dapat tercipta.

Menurut spesifikasi HTTP, metode seperti PUT dan DELETE bersifat idempoten: mengirim request yang sama beberapa kali seharusnya memiliki efek yang sama seperti mengirimkannya sekali. Sementara itu, POST tidak otomatis memiliki sifat tersebut. Penjelasan lengkapnya tersedia dalam RFC 9110.

Idempotency key bekerja seperti nomor antrean unik

Untuk operasi yang membuat efek baru—misalnya membuat pesanan, mengirim uang, atau mengajukan pembayaran—client membuat sebuah key unik. Key ini dikirim melalui header:

POST /api/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: 6f7c2f93-3d8c-4f44-a0db-1e3a2c0f4c11

Server kemudian menyimpan hubungan antara key, isi request, status proses, dan responsnya. Jika key yang sama datang lagi, server memeriksa catatan tersebut.

  • Jika key belum ada, request diproses.
  • Jika key sudah selesai diproses, respons lama dikembalikan.
  • Jika key masih berstatus diproses, server tidak boleh membuat transaksi kedua.
  • Jika key yang sama digunakan untuk isi request berbeda, server sebaiknya menolak request tersebut.

Pola serupa digunakan oleh penyedia API pembayaran. Stripe, misalnya, menjelaskan bahwa idempotency key memungkinkan client mengulangi request setelah kegagalan jaringan tanpa membuat biaya atau operasi ganda. Ini bukan berarti semua sistem otomatis aman; perilaku tersebut harus dirancang di sisi server.

Contoh desain tabel di MySQL

Untuk aplikasi PHP dan MySQL, key dapat disimpan dalam tabel khusus. Kolom idempotency_key harus memiliki indeks unik agar dua request bersamaan tidak lolos sebagai transaksi baru.

CREATE TABLE api_idempotency_keys (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT UNSIGNED NOT NULL,
    idempotency_key VARCHAR(100) NOT NULL,
    request_hash CHAR(64) NOT NULL,
    status ENUM('processing', 'completed', 'failed') NOT NULL,
    response_code SMALLINT NULL,
    response_body JSON NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uq_user_key (user_id, idempotency_key)
);

request_hash digunakan untuk memastikan key tidak dipakai ulang dengan data berbeda. Contohnya, key yang awalnya digunakan untuk membeli produk A tidak boleh tiba-tiba digunakan untuk produk B.

Alur implementasi di PHP

Berikut gambaran sederhana alurnya. Contoh ini bukan library siap produksi, tetapi cukup untuk memahami pembagian tanggung jawabnya.

$key = $_SERVER['HTTP_IDEMPOTENCY_KEY'] ?? null;
$body = file_get_contents('php://input');
$hash = hash('sha256', $body);

if (!$key) {
    http_response_code(400);
    echo json_encode(['error' => 'Idempotency-Key wajib diisi']);
    exit;
}

$db->beginTransaction();

$stmt = $db->prepare(
    'SELECT * FROM api_idempotency_keys
     WHERE user_id = ? AND idempotency_key = ?
     FOR UPDATE'
);
$stmt->execute([$userId, $key]);
$record = $stmt->fetch();

if ($record) {
    if (!hash_equals($record['request_hash'], $hash)) {
        $db->rollBack();
        http_response_code(409);
        echo json_encode(['error' => 'Key digunakan dengan data berbeda']);
        exit;
    }

    if ($record['status'] === 'completed') {
        $db->commit();
        http_response_code($record['response_code']);
        echo $record['response_body'];
        exit;
    }
}

// Simpan status processing, buat pesanan, lalu simpan respons.
// Seluruh operasi penting dilakukan dalam transaksi database.

Dalam implementasi nyata, bagian pentingnya bukan sekadar mengecek key. Pemeriksaan, pembuatan catatan, dan pembuatan pesanan harus dilindungi transaksi database. Jika dua request identik tiba hampir bersamaan, constraint unik dan mekanisme locking membantu memastikan hanya satu request yang menjadi pemilik operasi.

Jangan menyamakan idempotency dengan tombol yang dinonaktifkan

Menonaktifkan tombol setelah diklik tetap berguna untuk pengalaman pengguna. Namun, itu hanya perlindungan di sisi browser. Request bisa datang dari mobile app, script, retry otomatis, atau pengguna yang membuka beberapa tab.

Idempotency harus diterapkan di server karena server adalah tempat keputusan akhir dibuat. Tombol yang dinonaktifkan mencegah sebagian klik berulang; idempotency key menangani ketidakpastian komunikasi dan request duplikat.

Berapa lama key harus disimpan?

Key tidak selalu perlu disimpan selamanya. Masa simpan bergantung pada jenis operasi. Untuk pembayaran, periode beberapa jam atau hari mungkin diperlukan agar retry yang terlambat tetap aman. Untuk proses internal yang selesai dalam hitungan detik, masa simpan dapat lebih pendek.

Yang penting, aturan kedaluwarsa harus jelas. Jika key lama sudah dihapus lalu dikirim ulang, server mungkin menganggapnya sebagai operasi baru. Karena itu, client sebaiknya membuat key baru hanya ketika memang memulai operasi baru, bukan setiap kali melakukan retry.

Checklist sebelum menerapkannya

  • Gunakan key acak yang sulit bertabrakan, misalnya UUID.
  • Hubungkan key dengan identitas pengguna atau akun.
  • Simpan hash payload dan tolak penggunaan key untuk data berbeda.
  • Gunakan indeks unik di database.
  • Simpan status processing dan completed.
  • Simpan respons yang relevan agar retry menghasilkan jawaban konsisten.
  • Uji skenario koneksi terputus setelah database commit.
  • Gunakan retry dengan jeda bertahap, bukan mengirim request terus-menerus.

Apa artinya bagi kita?

Idempotency key bukan hanya fitur untuk perusahaan pembayaran besar. Toko online kecil, sistem booking, aplikasi donasi, dan dashboard internal juga bisa mengalami request ganda.

Mulailah dari endpoint yang memiliki dampak nyata jika dijalankan dua kali: membuat pesanan, mengurangi saldo, mengirim email penting, menerbitkan invoice, atau mengubah status pembayaran. Tambahkan perlindungan di server, pastikan database memiliki constraint yang tepat, lalu uji dengan simulasi koneksi lambat dan retry.

Dengan begitu, aplikasi tidak hanya terlihat berjalan ketika semuanya normal. Ia juga tetap dapat dipercaya ketika jaringan, browser, atau layanan lain berperilaku tidak sempurna.

Sumber & bacaan lebih lanjut

– Rio Yotto @rioyotto