Menyebut satu metode pembayaran atau menawarkan semuanya: bukan soal selera, melainkan dua bentuk respons yang berbeda

Pada pembuatan permintaan pembayaran ada satu field yang tampak seperti pengaturan tampilan, yaitu payment_methods, dan biasanya diisi sekali lalu disalin ke seluruh integrasi berikutnya. Field itu sebenarnya menentukan bentuk respons yang diterima kembali, dan empat hal lain ikut berubah bersamanya.

Jawaban singkatnya: sebut satu kode kalau nomor pembayarannya perlu dikirim sendiri, misalnya ditempel di badan invoice atau di pesan WhatsApp. Tawarkan semuanya kalau pembeli datang ke halaman checkout dan memang berhak memilih. Sisa artikel ini menjelaskan apa yang dikorbankan masing-masing.

Perbedaan pokoknya: apa yang ikut di respons create

Menyebut satu kode membuat instrumen pembayarannya dicetak pada saat pembuatan, dan instrumen itu ikut pulang di respons sebagai object payment: string QRIS untuk qris, nomor Virtual Account untuk kode VA. Menyebut beberapa kode, atau mengosongkan field-nya sehingga seluruh metode aktif ditawarkan, berarti pembeli belum memilih jalur. Belum ada yang bisa dicetak, jadi yang kembali hanya checkout_url sampai pembeli memilih.

Satu detail penamaan yang rutin menjerat integrasi baru: field yang dikirim bernama payment_methods berbentuk array, sedangkan yang dibaca kembali bernama payment_method berbentuk satu kode. Keduanya bukan pasangan kirim dan terima dari satu nilai yang sama.

Akibat praktisnya besar bagi penjual yang menagih lewat chat atau lewat invoice PDF. Nomor Virtual Account yang bisa disalin hanya tersedia sejak awal kalau satu kode VA disebut. Kalau yang dikirim daftar berisi beberapa kode, nomor itu baru lahir setelah pembeli membuka halaman checkout dan memilih, jadi nomornya tidak bisa dicetak di invoice yang dikirim lebih dulu. Rinciannya ada di dokumentasi pembuatan permintaan pembayaran.

Akibat kedua: kapan biayanya diketahui

Tarif adalah fakta tentang pasangan akun dan metode, bukan tentang akun saja. Saat satu kode disebut, metodenya sudah pasti pada detik pembuatan, sehingga fee dan net ikut tercetak di respons dan angkanya tidak akan berubah lagi. Saat beberapa kode ditawarkan, jalurnya belum ditentukan, jadi tarifnya baru dihitung saat pembeli memilih, dan dihitung ulang kalau pembeli berpindah jalur. Tarif yang tercatat pada barisnya dan biaya yang dipotong selalu berubah bersama-sama, tidak pernah salah satunya saja, sehingga tidak pernah ada baris yang dicap satu tarif tetapi dipotong tarif lain.

Pada pembayaran Rp 150.000, selisih yang sedang dipertaruhkan itu terlihat jelas:

Karena QRIS berbentuk persentase dan Virtual Account berbentuk nominal tetap, urutan termurahnya berbalik pada nominal besar. Menawarkan keduanya berarti menyerahkan keputusan itu kepada pembeli, yang tidak melihat biayanya sama sekali. Panduan memilih QRIS atau Virtual Account memuat titik baliknya.

Akibat ketiga: batas nominal yang menyaring, atau menolak

Ini perbedaan yang paling jarang diketahui, dan paling mahal kalau ditemukan di produksi. Batas nominal diperiksa saat pembuatan, berlaku per metode, dan nilainya dapat berbeda per akun. Nilai bawaannya Rp 10.000 sampai Rp 10.000.000.

Saat beberapa kode ditawarkan, pemilih hanya menampilkan jalur yang muat untuk nominal itu, dan jalur yang tidak muat disaring diam-diam. Menolak seluruh pembuatan gara-gara satu jalur punya batas bawah lebih tinggi akan menjatuhkan jalur lain yang sebenarnya muat, dan menampilkan jalur itu tetap berarti membiarkan pembeli memilih sesuatu yang kemudian ditolak.

Saat satu kode disebut, tidak ada yang tersisa untuk disaring, jadi pembuatannya ditolak 422 amount_too_small atau 422 amount_too_large. Untuk integrasi sendiri ini kabar baik: kesalahan muncul di log, bukan di layar pembeli. Untuk toko yang menyebut satu kode demi kerapian, ini berarti pesanan bernominal kecil bisa gagal dibuat sama sekali padahal jalur lain masih menerimanya. Sebagai gambaran, pada akun yang batas bawah Virtual Account-nya dinaikkan di atas batas QRIS-nya, pesanan Rp 9.000 yang menyebut satu kode VA ditolak mentah, sementara pesanan yang sama dengan dua kode tetap terbit dan hanya menampilkan QRIS kepada pembeli. Daftar batas dan galatnya ada di halaman batas dan laju.

Akibat keempat: isian yang diminta kepada pembeli

Permintaan data pembeli dijumlahkan atas seluruh metode yang ditawarkan, bukan atas metode yang akhirnya dipilih. QRIS tidak membutuhkan apa pun. Virtual Account membutuhkan nama, karena nomornya tidak bisa dicetak sebelum nama itu diketahui. Kartu membutuhkan email.

Jadi menambahkan satu bank Virtual Account ke tautan yang tadinya QRIS saja menambah satu kolom wajib bagi semua pembeli, termasuk yang pada akhirnya memindai QRIS. Artikel tentang data pembeli yang diminta saat membayar membahas penjumlahan itu beserta perangkapnya.

Menghilangkan langkah pemilih

Kalau satu kode sudah disebut, langkah pemilih pada halaman checkout tidak punya pekerjaan. Object checkout menerima steps, yaitu urutan langkah yang dilalui pembeli: customer untuk formulir data, payment_method untuk pemilih, dan payment untuk QR, kode, atau pengalihan. Buang payment_method saat satu kode disebut, dan buang customer saat data pembelinya sudah dipegang penjual. Langkah payment selalu terakhir dan ditambahkan sendiri kalau tidak disebut.

Satu jebakan yang menyertainya: mengirim object checkout mengganti ketiga pengaturan permintaan data sekaligus, sehingga object yang hanya berisi steps mematikan default akun untuk pembayaran itu. Mengosongkan seluruh object-nya berarti mewarisi setelan akun. Bentuk halamannya dibahas di dokumentasi Checkout.

Kode yang tidak aktif ditolak, bukan dibuang

Kode yang tidak ada, atau ada tetapi tidak aktif di akun yang bersangkutan, ditolak 422 payment_method_unavailable. Permintaannya tidak diteruskan dengan kode itu dibuang diam-diam. Ini layak diingat saat menyalin daftar kode antar lingkungan atau antar akun. Yang tersedia hari ini adalah QRIS, delapan bank Virtual Account, dan kartu; daftarnya beserta status masing-masing ada di halaman metode pembayaran.

Memilih menurut bentuk penjualannya

Susunan ketiga, yaitu pembuatan tanpa object checkout sama sekali, adalah hal yang berbeda lagi: tidak ada halaman yang dilalui, sehingga metode yang membutuhkan field yang tidak ikut dikirim ditolak 422 customer_required alih-alih menanyakannya kepada pembeli.

Pertanyaan yang sering muncul

Ringkasnya

• Satu kode mencetak instrumennya saat create; beberapa kode hanya memberi checkout_url.
• Satu kode mencetak biayanya juga; beberapa kode menundanya sampai pembeli memilih.
• Nominal di luar batas sebuah metode disaring diam-diam saat banyak kode ditawarkan, dan ditolak 422 saat satu kode disebut.
• Isian yang diminta adalah penjumlahan atas metode yang ditawarkan, bukan yang dipilih.
• Kirim payment_methods, baca kembali payment_method.