Mengintegrasikan API pembayaran kripto mengikuti bentuk yang dapat diprediksi terlepas dari penyedia: Anda membuat invoice, mengarahkan atau menyematkan checkout, menerima webhook asinkron seiring pembayaran berkembang, memverifikasinya, dan merekonsiliasi terhadap catatan Anda sendiri. Bagian sulitnya bukan jalur mulus — melainkan tepian.
Alur inti
Sebagian besar gateway mengekspos REST API dengan siklus hidup yang sama. Anda memanggilnya di sisi server (jangan pernah mengekspos kunci API di peramban), dan Anda memperlakukan webhook — bukan pengalihan peramban — sebagai sumber kebenaran apakah pesanan terbayar.
Rancang mesin status pesanan Anda lebih dulu: tertunda → kurang bayar/terbayar → terkonfirmasi → selesai, dengan cabang eksplisit untuk kedaluwarsa dan lebih bayar. Merangkai itu di muka mencegah percabangan kusut yang menyebabkan pemenuhan ganda.
- Buat invoice dengan jumlah, mata uang, ID pesanan, dan URL webhook.
- Tampilkan checkout ter-host atau render sendiri alamat dan jumlahnya.
- Terima webhook untuk setiap perubahan status dan verifikasi tanda tangannya.
- Pastikan pembayaran mencapai konfirmasi yang diperlukan sebelum memenuhi.
- Rekonsiliasi webhook terhadap transaksi on-chain dan pesanan Anda.
Membuat invoice
Invoice mengikat jumlah tertentu ke pesanan tertentu untuk waktu terbatas. Kirim ID pesanan Anda sebagai metadata agar webhook dapat dicocokkan kembali tanpa menebak, dan simpan ID invoice yang dikembalikan gateway.
Kutipan kedaluwarsa — gateway mengunci nilai tukar selama beberapa menit. Simpan kedaluwarsa dan status invoice agar UI Anda dapat menampilkan penghitung mundur dan agar pembayaran terlambat ditangani sebagai kasus rekonsiliasi, bukan pesanan hilang.
Webhook adalah sumber kebenaran
Pengalihan peramban setelah pembayaran adalah kemudahan, bukan jaminan — pengguna bisa menutup tab. Webhook yang diterima server Anda adalah yang Anda tindak lanjuti. Verifikasi setiap webhook: periksa tanda tangan (biasanya HMAC atas body mentah dengan rahasia Anda) sebelum memercayai satu bidang pun.
Buat penanganan webhook idempoten. Gateway mencoba ulang pengiriman, jadi peristiwa 'terbayar' yang sama bisa tiba dua kali; kunci pemrosesan Anda pada ID peristiwa atau invoice dan buat pengiriman berulang menjadi no-op. Kembalikan 2xx dengan cepat dan lakukan pekerjaan lambat secara asinkron agar gateway tak kehabisan waktu dan mencoba ulang sia-sia.
Konfirmasi dan finalitas
Pembayaran bisa terlihat (di mempool atau dengan nol konfirmasi) jauh sebelum final. Tetapkan ambang konfirmasi yang sesuai dengan jumlah dan rantai, dan penuhi hanya setelah tercapai. Untuk pembayaran stablecoin kecil di rantai cepat ini cepat; untuk jumlah besar, tunggu lebih banyak.
Waspadai reorg dan double-spend dengan memercayai status 'terkonfirmasi' gateway ketimbang penampakan pertama Anda sendiri, dan dengan tidak melepas barang pada pembayaran nol konfirmasi kecuali Anda menerima risikonya.
Rekonsiliasi dan mode kegagalan
Rekonsiliasi adalah pekerjaan harian membuktikan bahwa setiap pesanan 'terbayar' memetakan ke transaksi on-chain nyata dan sebaliknya. Simpan hash transaksi, jumlah yang diterima, dan jaringan pada setiap pesanan agar ketidaksesuaian menjadi kueri, bukan investigasi.
Rencanakan secara eksplisit untuk kurang bayar (pembeli mengirim terlalu sedikit), lebih bayar (kembalikan selisih atau kreditkan), pengiriman jaringan salah, dan invoice kedaluwarsa-lalu-terbayar. Ini bukan kasus tepi langka pada skala besar — ini peristiwa mingguan, dan sistem yang menanganinya diam-diam itulah arti 'siap produksi' sesungguhnya.
Pertanyaan yang sering diajukan
Haruskah saya memercayai pengalihan peramban atau webhook?
Webhook. Pengalihan bisa hilang jika pengguna menutup tab, dan bisa dipalsukan. Verifikasi tanda tangan webhook di sisi server dan perlakukan sebagai sinyal otoritatif bahwa pesanan terbayar.
Bagaimana saya mencegah sebuah webhook diproses dua kali?
Buat penanganan idempoten. Gateway mencoba ulang pengiriman, jadi kunci logika Anda pada ID invoice atau peristiwa dan buat pengulangan menjadi no-op. Jangan pernah memenuhi pesanan dua kali karena peristiwa 'terbayar' yang sama tiba lagi.
Berapa banyak konfirmasi yang harus saya tunggu?
Bergantung jumlah dan rantai. Pembayaran stablecoin kecil di jaringan cepat bisa dianggap final hampir seketika; jumlah besar membenarkan lebih banyak konfirmasi. Gunakan status 'terkonfirmasi' gateway ketimbang penampakan pertama Anda sendiri.
Apa yang terjadi jika pelanggan kurang bayar atau lebih bayar?
Tangani keduanya secara eksplisit. Gateway menandai kurang bayar sehingga Anda dapat meminta selisih atau mengembalikan; untuk lebih bayar Anda kembalikan kelebihannya atau kreditkan. Membangun cabang-cabang ini di muka adalah beda antara demo dan produksi.