Idempotency (Pencegahan Duplikasi)

Network error dapat terjadi kapan saja. Klien mungkin mengirim request POST /v1/payments/create, namun koneksi internet terputus sebelum server sempat merespons. Dalam situasi ini, klien tidak tahu apakah tagihan sudah terbentuk atau belum.

Jika klien mengulang kembali (retry) request yang sama, ada risiko terbentuk dua tagihan ganda untuk satu pesanan yang sama.

Untuk mencegah masalah ini, Gerbang Pay mengimplementasikan mekanisme Idempotency.

Cara Kerja Idempotency

Endpoint POST /v1/payments/create mewajibkan Anda untuk mengirimkan HTTP Header bernama X-Idempotency-Key.

Key ini adalah string unik yang Anda buat sendiri. Praktik terbaiknya adalah menggunakan Order ID internal atau keranjang belanja dari database aplikasi Anda (maksimal 255 karakter).

X-Idempotency-Key: order-abc-12345

Ketika Gerbang Pay menerima request:

1. Sistem akan mengecek apakah X-Idempotency-Key ini sudah pernah diterima dalam 24 jam terakhir.
2. Key Baru: Jika belum pernah diterima, Gerbang Pay memprosesnya seperti biasa sebagai transaksi baru.
3. Sama Key, Sama Payload: Jika key tersebut sudah pernah diproses dan body JSON request-nya persis sama dengan sebelumnya, Gerbang Pay akan mengabaikan request baru dan seketika mengembalikan response JSON asli yang sama persis seperti request pertama (dengan status 200 OK). Ini membuat proses retry menjadi 100% aman.
4. Sama Key, Beda Payload: Jika key tersebut sudah ada tetapi isi request (misal amount atau method_type) berbeda dengan aslinya, maka sistem akan langsung menolaknya. Klien akan menerima HTTP status 409 Conflict dengan error IDEMPOTENCY_CONFLICT.

Time to Live (TTL)

Cache idempotency disimpan di sistem in-memory kami (Valkey) dengan TTL (Time-To-Live) selama 24 Jam.

Ini berarti, jika Anda mengirimkan request dengan key "A" hari ini, dan mengirim "A" lagi dua hari kemudian, sistem akan memperlakukannya sebagai request yang sama sekali baru.

Contoh Skenario

1. Klien checkout pesanan ORD-001, seharga Rp 100.000.
2. Klien mengirim ke Gerbang Pay: X-Idempotency-Key: ORD-001, amount: 10000000.
3. Server Gerbang Pay berhasil membuat tagihan, tapi koneksi putus saat mengirim response.
4. Klien aplikasi (menyangka gagal), lalu mengklik "Bayar" lagi.
5. Klien mengirim retry otomatis: X-Idempotency-Key: ORD-001, amount: 10000000.
6. Gerbang Pay menyadari ID tersebut sudah ada. Alih-alih membuat ke provider (Winpay/Midtrans) lagi, sistem langsung mengembalikan objek payment pertama yang sudah ada di database. TIDAK ADA tagihan ganda.

Skenario Gagal (Conflict)

Klien mengirim X-Idempotency-Key: ORD-001 dengan amount: 10000000.

Lalu klien mengubah pikiran (atau keranjang belanja berubah menjadi Rp 150.000), tapi klien tidak sengaja mengirimkan X-Idempotency-Key: ORD-001 lagi (key tidak di-generate ulang).

Sistem Gerbang Pay mendeteksi perbedaan nominal, lalu mengembalikan:

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "idempotency conflict: Same key submitted with different payload"
  }
}

Solusi untuk Klien: Jika parameter bisnis pesanan berubah, klien wajib mengirim request dengan Idempotency Key yang benar-benar baru, misal: ORD-001-v2.