Dua plafon nominal yang berbeda, dan yang mana yang menolak: rentang sampai satu miliar yang lolos validasi API sementara tidak satu pun metode melayani di atas sepuluh juta, dua penolakan 422 yang terbaca sama padahal berasal dari dua pemeriksaan, dan pemeriksaan ketiga di layar pembeli yang tidak mengembalikan galat apa pun

Sebuah integrasi baru biasanya membaca satu baris di dokumentasi galat, menemukan bahwa amount harus berupa bilangan bulat 1 sampai 1.000.000.000, lalu memasang pemeriksaan itu di sisinya sendiri dan menganggap urusan nominal selesai. Pemeriksaan itu benar dan sama sekali tidak cukup.

Jawaban singkatnya: ada dua plafon yang jaraknya seratus kali lipat. Yang pertama adalah aturan bentuk field, berlaku sama untuk setiap akun, menolak sebagai validation_failed. Yang kedua adalah maksimum akun per metode, bawaannya Rp 10.000.000, menolak sebagai amount_too_large. Nominal Rp 50.000.000 lolos plafon pertama dengan mulus dan mati di plafon kedua, dan seluruh rentang di antara keduanya adalah nominal yang diterima sebagai bentuk dan tidak akan pernah bisa dibayar siapa pun.

Plafon pertama: aturan bentuk field, bukan kemampuan akun

Pemeriksaan pertama berjalan atas body yang dikirim, sebelum apa pun tentang akun atau metode ikut dipertimbangkan. amount wajib berupa bilangan bulat pada rentang 1 sampai 1.000.000.000; di luar itu request ditolak 422 validation_failed. Dua sifat penolakan ini yang layak diketahui.

Pertama, penolakannya menyertakan error.fields, yang menyebut tiap field bermasalah beserta aturan yang dilanggarnya, dengan key berupa path field itu di dalam body yang dikirim. Kedua, dan ini yang menentukan cara menanganinya, body yang sama akan ditolak setiap kali dikirim. Tidak ada gunanya mencoba ulang, dan penolakan ini tidak pernah berubah karena keadaan akun berubah. Daftar lengkap aturan field lain yang ikut memicu kode yang sama ada di referensi kode galat.

Plafon kedua: maksimum akun, per metode

Pemeriksaan kedua adalah yang benar-benar membatasi penjualan. Nominal dicek terhadap minimum dan maksimum metode yang dipilih, dan bawaannya Rp 10.000.000 sebagai batas atas untuk setiap metode yang hidup, yaitu QRIS dan kedelapan bank Virtual Account. Nominal di atasnya ditolak 422 amount_too_large, dan penyelesaiannya bukan mengulang request melainkan memecah pesanan atau meminta plafonnya dinaikkan.

Yang sering terlewat: angka itu milik akun, bukan milik API. Kasera mengatur minimum dan maksimum per metode untuk sebuah akun, sehingga akun yang memang menjual barang besar bisa memiliki maksimum Virtual Account yang jauh di atas bawaan sementara QRIS-nya tetap di bawaan. Akibatnya bagi integrasi: plafon tidak boleh ditulis sebagai angka tetap di dalam kode. Angka milik akun sendiri selalu terbaca di dashboard pada pengaturan metode pembayaran, dan seluruh aturan batas beserta tempat pesannya muncul ada di halaman batas transaksi.

Sisi bawah punya bentuk yang sama dan kode yang berbeda lagi, yaitu amount_too_small untuk nominal di bawah minimum metode, bawaannya Rp 1.000 untuk QRIS dan Rp 10.000 untuk Virtual Account. Porsi biaya pada nominal kecil dan lantai pencairan yang mengikutinya sudah dibahas di tulisan tentang nominal kecil dan batas minimum per metode, jadi halaman ini tetap di sisi atasnya.

Rentang yang diterima dan tidak akan pernah dibayar

Aritmetikanya layak dinyatakan terang-terangan. Rentang yang lolos aturan bentuk field berhenti di 1.000.000.000. Rentang yang benar-benar bisa dibayar berhenti di 10.000.000 pada akun dengan plafon bawaan. Artinya sembilan puluh sembilan persen jangkauan yang diterima API adalah nominal yang tidak akan pernah menghasilkan satu pun pembayaran. Tabel berikut memakai akun dengan plafon bawaan.

Dua baris terakhir adalah inti persoalannya. Keduanya menolak, keduanya berstatus 422, dan keduanya berasal dari pemeriksaan yang berbeda dengan penyelesaian yang berbeda. Integrasi yang menangani nominal besar dengan satu cabang saja akan menyarankan hal yang salah pada salah satu dari keduanya.

Pemeriksaan ketiga, yang tidak mengembalikan galat apa pun

Ada satu pemeriksaan lagi, dan inilah yang membuat tagihan tampak terbit dengan baik lalu mati di layar pembeli. Batas dicek saat permintaan pembayaran dibuat, dan dicek lagi saat pembeli memilih metode. Kalau sebuah tagihan menawarkan beberapa metode, pembeli hanya melihat metode yang rentangnya cocok dengan nominal tagihan itu. Metode yang tidak cocok tidak ditawarkan, dan tidak ada pesan apa pun yang menjelaskannya. Request baru ditolak kalau tidak ada satu pun metode yang cocok.

Akibatnya terbaca di dua arah. Tagihan Rp 7.500 terbit tanpa galat dan tetap bisa dibayar, hanya saja Virtual Account tidak akan pernah muncul padanya. Sebaliknya, pada akun yang maksimum Virtual Account-nya sudah dinaikkan sementara QRIS tetap di bawaan, tagihan Rp 25.000.000 terbit dan hanya menawarkan Virtual Account. Pembeli yang menunggu QRIS akan melaporkannya sebagai kerusakan. Sebab-sebab lain yang menghasilkan layar serupa, mulai dari metode yang dimatikan sendiri sampai jalur bank yang sedang dimatikan sementara, dibahas di tulisan tentang metode pembayaran yang hilang dari halaman pembayaran.

Kalau biaya dibebankan ke pembeli, yang diperiksa adalah totalnya

Satu keadaan batas yang mudah terlewat: nominal acuan batas adalah nominal yang dibayar pembeli. Saat mode penanggung biaya disetel agar penjual menerima jumlah penuh, biaya ikut ditambahkan pada angka yang dibayar pembeli, dan angka itulah yang diperiksa terhadap plafon. Tagihan Rp 9.998.000 yang biayanya dibebankan ke pembeli karena itu bisa terdorong melewati Rp 10.000.000 dan ditolak, padahal nominal yang diminta penjual masih di bawah plafon. Sisi penetapan harga dari mode ini dibahas di tulisan tentang harga jual setelah biaya transaksi.

Satu penolakan lagi yang bukan soal plafon

Terpisah dari kedua plafon, penolakan nominal yang paling sering ditemui pada minggu pertama integrasi justru soal tipe. Nominal yang dikirim dengan tanda kutip, seperti "amount": "150000", adalah JSON yang sah dan tetap ditolak, dengan pesan yang menyebut field dan tipe yang diharapkan di sana. Ini bukan validation_failed dan bukan soal besarnya angka: library klien yang mengubah angka menjadi string saat menyusun body adalah penyebab yang paling lazim, dan nominalnya tidak pernah sampai ke satu pun pemeriksaan plafon.

Apa yang sebaiknya divalidasi di sisi integrasi

• Validasi terhadap plafon akun, bukan terhadap 1.000.000.000. Aturan bentuk field bukan pernyataan tentang apa yang bisa dibayar.
• Jangan menuliskan Rp 10.000.000 sebagai angka tetap. Angka itu bisa dinaikkan per akun dan per metode, jadi baca dari pengaturan akun dan simpan di konfigurasi, bukan di kode.
• Pastikan nominal dikirim sebagai angka, bukan string, dan sebagai bilangan bulat rupiah tanpa pecahan.
• Kalau biaya dibebankan ke pembeli, hitung totalnya lebih dulu dan bandingkan total itu terhadap plafon.
• Bedakan dua cabang penanganan galat: validation_failed berarti perbaiki body dan jangan diulang, amount_too_large berarti pecah pesanannya atau minta plafon dinaikkan.
• Untuk tagihan bernominal besar, kirim kode metode yang memang melayaninya alih-alih membiarkan pembeli menghadapi daftar metode yang sudah tersaring tanpa penjelasan.

Nominal di atas plafon: memecah atau menaikkan

Untuk penjualan yang memang di atas Rp 10.000.000, ada dua jalan dan keduanya sah. Memecah menjadi beberapa pembayaran, misalnya uang muka lalu pelunasan, bekerja hari ini tanpa menunggu siapa pun, dengan catatan tiap bagian adalah permintaan pembayaran sendiri yang punya biaya dan barisnya sendiri. Menaikkan plafon akun ditempuh lewat dukungan dengan menyebut metode yang dimaksud, nominal terbesar yang diperkirakan, dan alasannya. Untuk usaha yang nominal besarnya rutin, menaikkan plafon lebih rapi daripada memecah setiap pesanan; untuk yang sesekali, memecah lebih cepat.

Pertanyaan yang sering muncul

Ringkasnya

• Plafon pertama adalah aturan bentuk field, yaitu bilangan bulat 1 sampai 1.000.000.000, sama untuk setiap akun, menolak sebagai validation_failed.
• Plafon kedua adalah maksimum akun per metode, bawaannya Rp 10.000.000, bisa dinaikkan per akun, menolak sebagai amount_too_large.
• Rentang di antara keduanya diterima sebagai bentuk dan tidak akan pernah bisa dibayar, sehingga memvalidasi terhadap plafon pertama saja bukan validasi.
• Pemeriksaan ketiga berjalan saat pembeli memilih metode dan tidak mengembalikan galat: metode di luar rentang hilang dari layar tanpa pesan, dan request hanya ditolak kalau tidak ada satu pun yang cocok.
• Saat biaya dibebankan ke pembeli, yang diperiksa terhadap plafon adalah total termasuk biaya itu.