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: tidak ada batas harian yang memaksa pindah, jadi batasnya praktis, 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 masih berlaku pada kedua jalur

Akun terverifikasi tidak punya batas jumlah maupun total nominal permintaan pembayaran per hari, jadi tidak ada angka yang menutup jalur manual pada hari ramai. Yang berlaku sama untuk dashboard dan API adalah batas per pembayaran: nominal minimum per metode dan maksimum Rp 10.000.000. Integrasi menambah satu batas lagi, yaitu 300 permintaan per menit per API key, yang dijawab dengan 429 rate_limited dan cukup diulang setelah jeda. Angka lengkapnya, dan mana yang bisa dinaikkan, ada di tulisan tentang batas yang masih berlaku dan cara menaikkannya.

Apa yang dibeli sebuah integrasi

Baris terakhir penting karena sering dikira sebaliknya: tidak ada tarif berbeda untuk integrasi. Biayanya tetap tarif QRIS 0,7% 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.

Toko yang sudah berjalan di atas WooCommerce punya jalan pintas atas seluruh bagian ini, karena kedua sisi itu sudah ada di dalam plugin resminya. Pertimbangannya, termasuk apa yang tidak bisa diubah dari dalam plugin dan bentuk penjualan yang tetap menuntut integrasi sendiri, dibahas di perbandingan memakai plugin dan menulis integrasi sendiri.

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, pastikan kode mengulang hanya penolakan rate_limited, bukan setiap 429. Lima, biarkan pembuatan dari dashboard tetap hidup selama minggu pertama sebagai jalur cadangan.

Pertanyaan yang sering muncul