Idempotency

Ada tiga identifier yang ikut dalam create. Hanya yang pertama yang mengubah perilaku; dua lainnya cuma label yang kami simpan, kembalikan, dan bisa Anda pakai untuk filter.

Idempotency-Key

Berupa header, maksimal 255 byte, dan inilah proteksi Anda dari masalah jaringan. Batasnya dihitung dalam byte, bukan karakter, jadi key dari teks non-ASCII lebih cepat habis; UUID aman. Kirim key yang sama lagi dan Anda dapat permintaan pembayaran yang asli dengan status 200, bukan 201, dan tidak ada yang dibuat untuk kedua kalinya.

Jadi 201 berarti baru dibuat, dan 200 berarti sudah ada sebelumnya. Tidak ada cara lain yang mengembalikan permintaan pembayaran yang sudah ada.

Begitu key menempel pada permintaan pembayaran, mengirimnya dengan body berbeda ditolak 409 idempotency_conflict. Key hanya menempel pada permintaan pembayaran yang benar-benar berhasil dibuat: kalau request pertama Anda ditolak — misalnya 422 — tidak ada yang tersimpan dan key-nya bisa dipakai lagi. Yang kami bandingkan adalah hash dari byte persis yang Anda kirim, bukan objek hasil parse, jadi urutan key yang berubah atau spasi yang berbeda pun dihitung sebagai body berbeda. Key berlaku per akun, disimpan permanen, dan tidak pernah expired — retry sejam atau sebulan kemudian sama amannya.

POST /v1/refunds memakai header yang sama, dengan satu perbedaan: key yang sudah menempel pada salah satu refund Anda mengembalikan refund itu lagi, apa pun isi body kali ini. Tidak ada perbandingan body pada refund, jadi tidak ada 409 — refund yang asli dikembalikan dan tidak ada dana yang bergerak dua kali.

merchant_ref

Referensi Anda sendiri untuk pembayaran itu, maks 64 karakter, dikembalikan di setiap response dan bisa difilter di endpoint list. Field ini tidak mencegah duplikat. Dua create dengan merchant_ref sama tetap jadi dua permintaan pembayaran.

external_id

Nomor pesanan dari sisi penjual. Sama seperti merchant_ref, hanya disimpan dan bisa difilter — satu pesanan memang bisa saja dibayar dua kali, dan kami tidak memutuskan hal itu untuk Anda.

Sebaiknya pakai apa

Nilai yang unik per permintaan pembayaran — nomor pesanan Anda, atau UUID yang dibuat kode Anda sebelum request pertama lalu dipakai lagi untuk setiap retry-nya. Membuat key baru setiap retry justru membuat mekanismenya tidak berguna, dan tidak ada field lain yang bisa menangkapnya.