Mulai
Idempotency
Retry dengan aman — gangguan jaringan tidak akan pernah membuat tagihan ganda.
Header Idempotency-Key adalah satu-satunya hal yang mencegah pembayaran ganda. Sifatnya opsional — kalau tidak dikirim, setiap percobaan menjadi permintaan pembayaran tersendiri, dan memang itu artinya.
Ada tiga identifier yang ikut dalam sebuah create. Hanya yang pertama yang mengubah perilaku; dua sisanya label yang kami simpan, kembalikan, dan bisa Anda pakai memfilter.
Idempotency-Key
Sebuah header, maksimal 255 byte, dan inilah pelindung Anda dari jaringan. Batasnya menghitung byte, bukan karakter, jadi key yang disusun dari teks non-ASCII habis lebih cepat; UUID tidak terpengaruh. Kirim key yang sama lagi, Anda menerima permintaan pembayaran yang asli dengan status 200, bukan 201, dan tidak ada yang dibuat untuk kedua kalinya.
Jadi 201 berarti ada yang dibuat, dan 200 berarti Anda sudah memilikinya. Tidak ada jalur lain yang mengembalikan permintaan pembayaran yang sudah ada.
Begitu sebuah key menempel pada permintaan pembayaran, mengirimnya dengan body berbeda ditolak 409 idempotency_conflict. Key baru menempel pada permintaan pembayaran yang benar-benar terbuat: kalau percobaan pertama Anda ditolak — misalnya 422 — tidak ada yang tersimpan dan key-nya bebas dipakai lagi. Yang kami bandingkan adalah hash dari byte persis seperti yang Anda kirim, bukan objek hasil parse-nya, jadi urutan key yang bertukar atau spasi yang berubah pun terhitung body berbeda. Key berlaku per akun, disimpan permanen, dan tidak pernah kedaluwarsa — mau retry sejam atau sebulan kemudian, sama amannya.
merchant_ref
Referensi Anda sendiri untuk pembayaran itu, maks 64 karakter, dikembalikan di setiap respons dan bisa difilter di endpoint daftar. Field ini tidak mencegah duplikat. Dua create dengan merchant_ref sama adalah dua permintaan pembayaran.
external_id
Nomor pesanan milik penjual. Sama seperti merchant_ref, hanya disimpan dan bisa difilter — satu pesanan wajar saja dibayar dua kali, dan kami tidak memutuskan sebaliknya untuk Anda.
Sebaiknya pakai apa
Nilai yang unik per permintaan pembayaran — nomor pesanan Anda, atau UUID yang kode Anda buat sebelum percobaan pertama lalu dipakai lagi untuk setiap retry-nya. Membuat key baru setiap retry justru membatalkan gunanya, dan tidak ada field lain yang akan menutupinya.