Cegah pembayaran ganda dengan idempotensi
Koneksi dapat terputus setelah Valcentra membuat pembayaran tetapi sebelum backend menerima respons. Tanpa pengenal operasi yang stabil, retry bisa dianggap sebagai permintaan baru.
Pada POST /v1/payments, Idempotency-Key mengidentifikasi satu operasi create payment. Mengulang request dengan API key, idempotency key, dan body yang sama mengembalikan pembayaran yang sama, bukan membuat pembayaran kedua.
Pilih key sebelum mengirim request
Gunakan key yang bisa disimpan dan ditemukan kembali bersama pesanan:
merchant_reference: order-book-1001
Idempotency-Key: order-book-1001-createKey menerima 1–255 karakter. Karakter pertama harus huruf atau angka; sisanya boleh huruf, angka, titik, underscore, atau tanda hubung. Jangan memasukkan secret atau data pribadi.
Simpan key dan body operasi di backend sebelum request dikirim. Membuat timestamp atau UUID baru setiap kali retry menghilangkan manfaat deduplikasi. UUID boleh dipakai jika dibuat sekali untuk operasi tersebut dan digunakan kembali.
Bedakan tiga pengenal
| Pengenal | Pemilik | Fungsi |
|---|---|---|
merchant_reference | Sistem Anda | Referensi bisnis, unik per project dan environment. |
Idempotency-Key | Sistem Anda | Pengenal operasi create yang dapat diulang dengan aman. |
Payment id | Valcentra | Identitas pembayaran yang dipakai saat retrieve atau simulasi. |
Deduplikasi create terikat pada API key yang mengirim request. Jangan menganggap key yang sama akan melanjutkan operasi setelah Anda berganti API key. Keunikan merchant_reference tetap berlaku pada project dan environment.
Apa yang terjadi saat request diulang?
| Request berikutnya | Hasil / tindakan |
|---|---|
| Key dan body sama, memakai API key yang sama | Pembayaran yang sama dikembalikan. |
| Key sama, body berubah | HTTP 409 idempotency_conflict. Periksa data operasi; jangan retry tanpa perubahan. |
Key baru, merchant_reference sudah terpakai | HTTP 409 merchant_reference_conflict. Cari pembayaran pesanan tersebut, bukan membuat referensi acak untuk melewati konflik. |
| Key baru dan referensi baru | Operasi baru yang dapat membuat pembayaran baru. |
Body mencakup jumlah, channel, deskripsi, metadata, dan return URL. Pertahankan semua nilainya pada retry, bukan hanya amount.
Setelah timeout
- Jangan langsung menyimpulkan pembayaran gagal.
- Jika ID sudah tersimpan, ambil status dengan
GET /v1/payments/{payment_id}. - Jika respons create belum diterima, ulang create memakai key dan body yang tersimpan serta API key yang sama.
- Simpan ID dan checkout URL ketika respons diterima.
Terapkan batas percobaan dan jeda retry. Lihat error API untuk menentukan kapan retry masuk akal.
Tidak semua operasi memiliki perilaku idempotensi yang sama
Endpoint simulasi mewajibkan header Idempotency-Key, tetapi tidak mendeduplikasi percobaan simulasi. Deduplikasi webhook juga berbeda:
receiver Anda menggunakan event.id, bukan key request create payment.
Lanjutkan ke: payment dan status, atau webhook untuk mencegah pemrosesan pesanan berulang.