Berhenti membuat tautan pembayaran satu per satu: kapan pindah ke integrasi API

Membuat tautan pembayaran dari dashboard tidak pernah salah. Cara itu justru yang paling cepat untuk sepuluh pesanan pertama, dan banyak usaha berjalan bertahun-tahun tanpa satu baris kode integrasi. Yang perlu dikenali adalah titik ketika cara itu berhenti sepadan, karena titik itu datang bukan sebagai kegagalan melainkan sebagai kelelahan yang pelan.

Jawaban singkatnya: batas kerasnya 100 permintaan pembayaran per hari, dan batas praktisnya jauh lebih awal, yaitu pada saat nominal masih diketik tangan dan status pesanan masih harus dilihat sendiri satu per satu. Halaman ini menandai titik itu, menghitung apa yang dibeli sebuah integrasi, dan menyebutkan integrasi paling kecil yang sudah berguna. Cara memasangnya langkah demi langkah ada di panduan tersendiri dan tidak diulang di sini.

Apa yang sebenarnya dikerjakan tangan pada tiap pesanan

Formulir pembuatan pembayaran di dashboard meminta nominal, pilihan menerima utuh atau tidak, metode pembayaran, data pembeli bila diperlukan, dan deskripsi opsional maksimal 255 karakter, lengkap dengan pratinjau biaya dan jumlah yang akan diterima sebelum tombol ditekan. Setelah itu tautannya disalin dan dikirim ke pembeli.

Hitungan kasarnya sekitar sembilan puluh detik per pesanan bila semuanya lancar, dan lebih lama bila nominal harus dihitung ulang dari keranjang atau data pembeli harus dicari di percakapan. Dua puluh pesanan sehari berarti sekitar setengah jam, setiap hari, dikerjakan orang yang sama, pada jam yang biasanya sedang sibuk. Yang lebih mahal bukan setengah jamnya, melainkan bahwa pekerjaan itu tidak bisa ditunda: pembeli sedang menunggu tautannya.

Tiga tanda jalur manual sudah berhenti sepadan

Nominal diketik ulang. Angka yang diketik adalah angka yang mengikat. Salah ketik satu nol menghasilkan tagihan yang sah dan bisa dibayar, dan memperbaikinya berarti mengembalikan uang lewat transfer bank biasa, bukan menekan tombol batal. Selama nominal berpindah dari keranjang ke formulir lewat mata dan jari, kesalahan itu hanya soal waktu.

Nomor pesanan tidak punya tempatnya sendiri. Formulir dashboard tidak punya kolom nomor pesanan, jadi nomor itu dititipkan ke kolom Deskripsi, yang memang ikut terbawa ke kotak pencarian dan ke ekspor CSV. Cara itu bekerja sampai penulisannya tidak seragam. Pembuatan lewat API punya kolomnya sendiri, yaitu external_id untuk nomor pesanan dan merchant_ref maksimal 64 karakter untuk nomor internal kedua, dan keduanya bisa difilter langsung di endpoint daftar.

Status pesanan diperbarui manusia. Notifikasi payment.paid dikirim untuk setiap pembayaran yang terkonfirmasi, termasuk yang dibuat dari dashboard, jadi pemberitahuannya sebenarnya sudah ada sejak awal. Yang belum ada adalah penerimanya. Selama tidak ada sistem yang mendengarkan, seseorang harus membuka dashboard, mencocokkan pembayaran dengan pesanan, lalu menandainya di tempat lain. Itulah pekerjaan yang sebenarnya dihapus oleh integrasi, bukan pembuatan tautannya.

Batas yang menutup jalur manual sepenuhnya

Secara bawaan sebuah akun boleh membuat 100 permintaan pembayaran per hari, dengan total nominal Rp 50.000.000 per hari, dan yang dihitung adalah permintaan yang dibuat, bukan yang dibayar. Tautan yang tidak pernah dibuka memakan jatah yang sama dengan penjualan.

Dua hal yang membuat batas ini sering ditemukan pada waktu yang paling buruk. Pertama, halaman pembayaran permanen menarik dari jatah harian yang sama, jadi hari yang tampak sepi di dashboard bisa saja sudah penuh. Kedua, jatah yang habis tidak muncul sebagai pesan galat kepada penjual, melainkan sebagai halaman yang sedang sibuk di sisi pembeli, sehingga kabarnya datang dari pembeli. Arti kedua angka itu, kapan jatahnya kembali nol, dan cara meminta kenaikannya ada di tulisan tentang batas harian dan cara menaikkannya.

Apa yang dibeli sebuah integrasi

Baris terakhir penting karena sering dikira sebaliknya: tidak ada tarif berbeda untuk integrasi. Biayanya tetap MDR 0,7% yang diteruskan tanpa markup ditambah Rp 250 per transaksi berhasil, dan pencairan ke rekening bank Rp 3.000 per pencairan, apa pun cara pembuatannya. Yang dibeli integrasi adalah waktu dan ketepatan, bukan harga yang lebih murah.

Integrasi paling kecil yang sudah berguna

Integrasi pertama tidak perlu menyentuh halaman checkout sendiri. Dua endpoint sudah cukup untuk menghapus seluruh pekerjaan tangan di atas: satu panggilan untuk menerbitkan pembayaran, dan satu URL untuk menerima kabar bahwa pembayaran itu lunas.

curl https://pay.kasera.id/v1/transactions \
  -H "Authorization: Bearer kp_live_..." \
  -H "Idempotency-Key: ORD-1042-create" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "description": "Kaos komunitas",
    "external_id": "ORD-1042",
    "return_url": "https://toko.example/selesai"
  }'

Balasannya berisi checkout_url, yaitu tautan yang selama ini disalin manual dari dashboard, dan pembeli dibawa ke sana persis seperti sebelumnya. Bedanya tautan itu lahir pada detik pesanan dibuat, membawa nomor pesanannya sendiri, dan mengembalikan pembeli ke halaman toko setelah pembayaran berhasil.

Sisi keduanya satu URL webhook yang menerima payment.paid, memverifikasi header Kasera-Signature-V1 atas timestamp dan body mentah, lalu menandai pesanan lunas. Endpoint webhook diatur dari menu Developer di dashboard, sampai lima per mode, masing-masing dengan signing secret sendiri. Bentuk lengkap kedua sisi itu ada di dokumentasi membuat permintaan pembayaran dan dokumentasi webhook, sedangkan urutan memasangnya dari nol sampai pembayaran terkonfirmasi otomatis ada di panduan integrasi QRIS di website.

Dua hal yang tidak boleh dianggap detail, karena keduanya baru terlihat setelah merugikan. Kirim Idempotency-Key yang deterministik per pesanan, misalnya nomor pesanan ditambah keperluannya, karena satu percobaan ulang tanpa kunci itu menerbitkan tagihan kedua yang sama sahnya. Dan verifikasi tanda tangan sebelum payload dipakai, karena alamat webhook bukan rahasia.

Langkah setengah: halaman pembayaran permanen

Ada jalur tengah yang sering terlewat. Halaman pembayaran permanen adalah satu alamat tetap yang bisa dibagikan sekali dan dipakai berkali-kali, dengan nominal diisi pembeli. Halaman itu menghapus pekerjaan menerbitkan tautan tanpa satu baris kode, dan memang cocok untuk iuran, donasi, atau pembayaran yang nominalnya ditentukan pembeli.

Batasnya perlu diketahui sebelum dipilih. Halaman itu menampilkan QRIS, nominalnya diketik pembeli sehingga bisa keliru, dan tidak ada nomor pesanan yang melekat, jadi pencocokan ke pesanan kembali menjadi pekerjaan tangan. Untuk penjualan yang terikat pesanan, halaman permanen memindahkan pekerjaan, bukan menghapusnya. Perbandingan ketiga jalur tanpa website ada di panduan menerima QRIS tanpa website.

Susunan campuran yang biasanya benar

Pindah ke API tidak berarti menutup pintu yang lain. Susunan yang paling awet biasanya campuran: alur utama diterbitkan integrasi, dashboard tetap dipakai untuk pesanan luar biasa seperti penjualan lewat telepon atau tagihan tambahan, dan halaman permanen dipakai untuk pembayaran yang memang tidak terikat pesanan. Ketiganya menghasilkan objek pembayaran yang sama dan masuk ke daftar transaksi yang sama, dengan kolom sumber yang membedakan Dashboard, API, dan Halaman pembayaran, jadi rekap hariannya tetap satu berkas. Cara menutup buku dari daftar itu ada di panduan rekonsiliasi harian toko online.

Checklist sebelum memulai

Satu, tulis integrasinya memakai key tes berawalan kp_test_ lebih dulu, dan jalankan juga jalur pembayaran yang kedaluwarsa, bukan hanya yang berhasil. Dua, tentukan bentuk kunci idempotensi per pesanan sebelum baris pertama ditulis. Tiga, siapkan URL webhook beserta verifikasi tanda tangannya, dan buktikan endpoint terjangkau lewat tombol kirim event percobaan di dashboard. Empat, cocokkan batas harian dengan jumlah pesanan harian yang sebenarnya, dan urus kenaikannya sebelum dibutuhkan. Lima, biarkan pembuatan dari dashboard tetap hidup selama minggu pertama sebagai jalur cadangan.

Pertanyaan yang sering muncul