Integrasi Gateway Pembayaran Otomatis
1. Ikhtisar & Nilai Bisnis
Modul Integrasi Gateway Pembayaran memungkinkan DAGANGBOT memfasilitasi transaksi secara otonom dan otomatis dari awal hingga akhir, menjembatani percakapan penjualan langsung menuju kas pelunasan secara instan. Menghubungkan akun Midtrans (Snap) atau Xendit khusus milik merchant memungkinkan
asisten virtual mencetak tautan tagihan yang sah, mengirimkannya di saluran WhatsApp atau Telegram, lalu otomatis mengubah status pemesanan ke paid sesaat setelah dana terkonfirmasi masuk melalui mekanisme Webhook, tanpa menunggu pelanggan mengunggah bukti transfer manual atau intervensi staf
Anda.
Integrasi spesifik merchant ini mengarahkan dana pelanggan langsung ke dompet atau penyelesaian (settlement) milik Anda, sepenuhnya menghindari skema dana transit (rekonsiliasi settlement pihak ketiga) di rekening platform DAGANGBOT. Kami bertindak murni sebagai jembatan backend, mengatur sinkronisasi ketersediaan barang, menghasilkan payload transaksi, dan memvalidasi keaslian tanda tangan digital pada tagihan yang dibayarkan.
Keuntungan strategis dari pemanfaatan Gateway Pembayaran ini meliputi:
- Penyelesaian Tanpa Kontak (Zero-Touch Checkout): Pembeli menerima QRIS atau nomor Virtual Account (VA) tepat pada saat minat beli mereka paling tinggi (di dalam ruang percakapan).
- Pemberantasan Bukti Transfer Palsu: Alur pemrosesan ini kebal terhadap manipulasi gambar karena sistem hanya akan menganggap pesanan "Lunas" bila Webhook dari server Xendit/Midtrans masuk ke server DAGANGBOT dengan tanda tangan kriptografis yang valid.
- Pengurangan Beban Kognitif Kasir: Menghapuskan keharusan admin untuk memeriksa mutasi rekening bank satu per satu pada jam sibuk.
Modul ini merupakan perbandingan mutlak untuk efisiensi jika disandingkan dengan alur pengerjaan operasional dari Pembayaran Manual.
2. Alur Visual & Antarmuka

Ketika pengguna atau agen berinteraksi untuk melakukan penyiapan, mereka disuguhkan formulir modal konfigurasi kredensial:

3. Panduan Langkah-demi-Langkah
Untuk dapat menerima tagihan instan (seperti QRIS, Virtual Account, E-Wallet, hingga kartu kredit) secara otonom di percakapan bot, ikuti urutan instalasi berikut dengan presisi:
Tahap 1: Registrasi dan Ekstraksi Kunci
- Pilih Penyedia Gateway: Platform saat ini mendukung Midtrans (Snap) dan Xendit. Buat akun bisnis pada salah satu platform.
- Siapkan Kunci API (Gateway API Key):
- Midtrans: Buka dasbor Settings -> Access Keys. Anda akan melihat dua jenis kunci: Server Key dan Client Key. Salin keduanya. (Untuk tahap pengujian, pastikan Anda menggunakan kunci dari Sandbox Environment yang umumnya diawali dengan
SB-). - Xendit: Buka menu API Keys, lalu cetak Secret API Key baru. Berikan izin Write untuk Invoices (Tagihan).
- Midtrans: Buka dasbor Settings -> Access Keys. Anda akan melihat dua jenis kunci: Server Key dan Client Key. Salin keduanya. (Untuk tahap pengujian, pastikan Anda menggunakan kunci dari Sandbox Environment yang umumnya diawali dengan
Tahap 2: Perekaman Kredensial di DAGANGBOT
- Akses Dasbor Integrasi: Buka Dasbor DAGANGBOT, navigasikan ke modul "Integrasi" dan klik tombol "Tambah Integrasi Baru". Pilih jenis "Pembayaran".
- Pilih Penyedia: Pada menu tarik-turun, pilih Midtrans atau Xendit sesuai kunci yang telah Anda siapkan.
- Masukkan Kredensial: Isikan parameter yang diperoleh dari penyedia ke dalam formulir.
- Tentukan Mode Lingkungan: Pastikan memilih sakelar mode Sandbox atau Production yang tepat agar seragam dengan identitas kunci. Kunci berawalan
SB-atauxnd_development_hanya bisa disimpan jika mode Sandbox (Uji Coba) aktif. DAGANGBOT memiliki validasi level Gateway yang akan menolak kunci tes di ranah produksi.
Tahap 3: Pemasangan Webhook (Sangat Kritis)
Agar DAGANGBOT mengetahui pelanggan Anda sudah mentransfer dana secara real-time, penyedia gateway harus mengirimkan sinyal ke DAGANGBOT ketika ada dana masuk. Jika langkah ini dilewati, pelanggan bisa membayar namun bot tidak akan memproses pesanan mereka.
- Bagi Pengguna Midtrans: Masukkan URL DAGANGBOT
<BASE_URL>/webhook/payment/midtrans(Ganti<BASE_URL>dengan domain instalasi / layanan platform) ke dalam kolom Notification URL di Dasbor Midtrans (Buka Pengaturan -> Konfigurasi -> Payment Notification URL). DAGANGBOT juga menerapkan mekanisme injeksi headerX-Override-Notificationpada setiap pembuatan invoice, sehingga URL Webhook akan ditimpa (override) secara otomatis jika merchant lupa mengisi, tetapi pengisian manual tetap direkomendasikan. - Bagi Pengguna Xendit: Masukkan
<BASE_URL>/webhook/payment/xenditke dalam pengaturan Xendit Callback URL (centang notifikasi untuk fitur Invoices yang berhasil dibayar). Xendit akan mencetak Callback Verification Token. Salin dan simpan Callback Verification Token tersebut kembali ke formulir Integrasi DAGANGBOT agar sistem dapat memvalidasi keaslian pengirim.
Tahap 4: Pengujian Transaksi Sandboxing
Platform merekomendasikan percobaan pembuatan satu tagihan boneka (sebagai Sandbox / mode Development) dan mensimulasikan pembayaran lunas menggunakan simulator yang disediakan oleh Midtrans/Xendit. Verifikasi apakah pesanan di dalam modul "Pesanan DAGANGBOT" otomatis berubah menjadi Paid.
Tahap 5: Transisi ke Produksi
Apabila sistem bot sukses merespons pembayaran pengujian, Anda siap merilis fitur ini:
- Ganti seluruh kata sandi (kunci API) di DAGANGBOT ke varian Production.
- Ubah tautan webhook ke mode Production pada dasbor Midtrans/Xendit.
- Nyalakan sakelar Is Production (menjadi
true) pada formulir DAGANGBOT dan simpan.
4. Parameter & Spesifikasi Teknis
Ketika platform mengomunikasikan pembuatan transaksi, DAGANGBOT merangkai data keranjang pelanggan menjadi spesifikasi kerangka (payload) JSON yang komprehensif. Ini meliputi rincian nama item, kuantitas, serta pengumpulan detail pelanggan (customer_details).
Transformasi Entitas Pesanan
Setiap pesanan di DAGANGBOT akan dipetakan dengan cermat ke dalam Invoice Gateway:
- Invoice ID: ID internal pesanan akan dimasukkan ke dalam
order_idatauexternal_id(Misal:ORD-12345ABC). - Gross Amount: Total tagihan (setelah pajak, ongkos kirim, dan diskon).
- Item Details: Seluruh barang di keranjang diteruskan (forwarded) secara terperinci (
id,price,quantity,name). - Customer Details: Nama, email, dan nomor telepon WhatsApp pelanggan dikirimkan ke Gateway agar tampil pada resi digital dan invoice Midtrans/Xendit.
- Expiry Duration: Standar masa kedaluwarsa tautan pembayaran diatur secara default menjadi 24 jam (
expiry_duration: 24h), kecuali Anda melakukan kustomisasi di pengaturan level toko. Tagihan kedaluwarsa akan otomatis membatalkan pesanan. - Finish URL: Platform otomatis menyematkan rute kembali (redirect) ke
[APP_URL]/app/billingsetelah pelanggan selesai bertransaksi di halaman Midtrans Snap.
Spesifikasi Midtrans Snap
Tanda pengenal kunci di Midtrans bersifat eksplisit berdasarkan peruntukannya.
Spesifikasi Xendit Invoice
Untuk Xendit, parameter yang disertakan sedikit berbeda, terutama pada alur pembuktian Webhook tingkat aplikasi (Application-Level Webhook Security).
Kode Contoh - Mengkonfigurasi Gateway Midtrans via API
Anda secara programatis dapat mendaftarkan akun dedicated Midtrans melalui rute API Integrasi (jika Anda memiliki hak akses setara Platform Admin atau Manajer Cabang).
curl -X POST "https://dagangbot.web.id/api/v1/integrations" \
-H "Authorization: Bearer <TOKEN_ANDA>" \
-H "Content-Type: application/json" \
-d '{
"type": "payment",
"name": "Midtrans Utama",
"config": {
"provider": "midtrans",
"server_key": "SB-Mid-server-YOURKEYHERE",
"client_key": "SB-Mid-client-YOURCLIENT",
"is_production": false,
"enabled_payments": ["qris", "bca_va", "gopay"]
}
}'Kode Contoh - Pembuatan Invoice (Simulasi Sistem)
Di balik layar, ketika DAGANGBOT memicu tagihan ke Midtrans (setelah percakapan checkout pelanggan), ia menyusun format JSON yang komprehensif menuju endpoint https://app.midtrans.com/snap/v1/transactions. Berikut adalah ilustrasi representatif dari payload yang dikirim backend:
{
"transaction_details": {
"order_id": "ORD-999123A",
"gross_amount": 155000
},
"expiry": {
"unit": "hour",
"duration": 24
},
"enabled_payments": ["qris", "bca_va", "gopay"],
"customer_details": {
"first_name": "Budi Santoso",
"email": "[email protected]",
"phone": "08123456789"
},
"item_details": [
{
"id": "PRD-001",
"price": 150000,
"quantity": 1,
"name": "Sepatu Lari Elite"
},
{
"id": "SHP-001",
"price": 5000,
"quantity": 1,
"name": "Ongkos Kirim Reguler"
}
],
"callbacks": {
"finish": "https://dagangbot.web.id/app/billing"
},
"notification_url": "https://dagangbot.web.id/webhook/payment/midtrans"
}Respons dari panggilan ini akan mengembalikan parameter token dan redirect_url dari Midtrans Snap, yang kemudian diubah DAGANGBOT menjadi tombol tautan bayar (Payment Link) interaktif di jendela obrolan pelanggan WhatsApp.
Kode Contoh - Validasi Status Transaksi
Terkadang, Webhook mengalami kegagalan transmisi jaringan (misalnya putus tengah jalan). DAGANGBOT memiliki rutinitas mandiri untuk memeriksa status order CheckTransactionStatus secara periodik atau ketika admin menekan tombol "Sinkronkan Status" di Dasbor:
# Permintaan sinkronisasi status (memerintahkan backend DAGANGBOT mengecek ke Gateway)
curl -X POST "https://dagangbot.web.id/api/v1/orders/ORD-999123A/sync-payment" \
-H "Authorization: Bearer <TOKEN_ANDA>" \
-H "Content-Type: application/json"Keamanan Webhook & Mekanisme Idempotensi
Sistem menerima notifikasi (Webhook) pada lajur API terbuka yang secara inheren dapat ditembak oleh siapa saja di internet. Untuk mencegah skenario di mana peretas (attacker) atau pihak iseng mengirimkan sinyal JSON palsu yang menyatakan suatu pesanan bernilai puluhan juta rupiah telah "Lunas", DAGANGBOT membangun lapis validasi berlapis yang absolut, memisahkan intent asli dari percobaan eksploitasi.
- Validasi Tanda Tangan Kriptografi (Midtrans):
Saat server Midtrans memanggil webhook, ia selalu menyertakan atribut
signature_keydi dalam badan JSON (payload). DAGANGBOT, secara internal melalui fungsiVerifyMidtransSignature, merangkai kombinasi string mentah berupaorder_id+status_code+gross_amount+server_keyrahasia Anda. String gabungan ini kemudian dilebur (hashing) dengan algoritma kriptografi satu arahSHA-512. Jika, dan hanya jika, keluaran hash murni ini secara identik cocok dengan nilaisignature_keydari muatan Midtrans, barulah DAGANGBOT mempercayai dan memvalidasi pembayaran. - Validasi Callback Token Tingkat Header (Xendit):
Berbeda dengan Midtrans, model keamanan Webhook Xendit bertumpu pada injeksi Header HTTP. DAGANGBOT secara ketat mencocokkan nilai kunci
x-callback-tokenyang terbaca pada Header transmisi masuk terhadap Callback Token yang Anda rekam saat pertama kali melakukan konfigurasi. Tanpa kecocokan string absolut (atau jika header ini sama sekali tidak ada), request akan dibuang ke keranjang sampah (di-drop) seketika dengan pengembalian respons HTTP403 Forbidden, tanpa pernah menyentuh database. - Mekanisme Idempotensi Logis (Pencegahan Pemrosesan Ganda):
Sistem arsitektur Gateway pembayaran terkemuka mana pun lazimnya menerapkan kebijakan pengulangan kirim (Retry Policy). Apabila koneksi internet terputus sepersekian detik di tengah jabat tangan (handshake) atau respons dari DAGANGBOT terhambat, Gateway berasumsi pesan belum tersampaikan dan
akan mengirim dua, tiga, atau belasan webhook identik berturut-turut. DAGANGBOT menerapkan penangkal eksekusi ganda melalui kunci idempotensi logis. Status faktur (pending, paid, atau expired) dikunci secara transaksional. Webhook penyelesaian (settlement) yang secara fungsional sudah
diproses sebelumnya akan langsung diapresiasi dengan tanggapan HTTP
200 OKtanpa memanipulasi database ulang atau melipatgandakan dana pesanan.
Kegagalan Panggil Balik (Callback Failure)
Pada insiden esoterik di mana server DAGANGBOT mengalami malfungsi (downtime) sesaat atau koneksi jaringan memblokir rutinitas sehingga webhook mengalami kegagalan transmisi terus-menerus, pihak gateway akan menyerah dan menangguhkan pesan tersebut. Anda tak perlu membatalkan manual; antarmuka "Sinkronkan Status" pesanan di DAGANGBOT menembak fungsi internal untuk memaksa backend berbalik menarik (polling) data ke server gateway. Aksi manual ini menambal lubang sinkronisasi pasif dengan tarikan proaktif yang definitif.
Kode Contoh - Mensimulasikan Panggilan Webhook (Uji Notifikasi)
Anda dapat melakukan uji notifikasi terhadap lapisan integrasi pembayaran dengan menyimulasikan kedatangan JSON menggunakan curl berikut (contoh untuk endpoint Midtrans):
curl -X POST "https://dagangbot.web.id/webhook/payment/midtrans" \
-H "Content-Type: application/json" \
-d '{
"transaction_time": "2026-10-08 15:00:00",
"transaction_status": "settlement",
"transaction_id": "8a32a67e-2x34",
"status_message": "midtrans payment notification",
"status_code": "200",
"signature_key": "9x...contoh_hash_sha512...x7",
"payment_type": "qris",
"order_id": "ORD-12345ABC",
"merchant_id": "M123",
"gross_amount": "155000.00",
"fraud_status": "accept"
}'5. Relasi & Integrasi
Modul Pembayaran Otomatis ini bukan sistem yang terisolasi atau berdiri sendiri; ia merajut erat fungsi-fungsi inti lain dalam denyut operasional platform:
- Rekonsiliasi Transfer Manual: Fitur integrasi ini menjalin hubungan mutual dengan modul Pembayaran Manual. Di dunia nyata, sering kali pembeli sudah meminta tautan pembayaran, namun di tengah jalan kartu kredit mereka bermasalah atau mereka
ingin beralih mentransfer via teller bank. Melalui pemahaman mendalam intent (maksud) AI percakapan pada saluran pelanggan—atau lewat pemicuan fungsi rute internal
switch_payment_method—DAGANGBOT dapat membatalkan dan mengekspirasi (void) tautan URL Midtrans/Xendit yang sedang aktif secara instan. Sebaliknya, pelanggan yang tadinya memilih transfer manual bisa tiba-kata meminta "Bayar pakai Gopay saja", dan bot akan mencetak tautan Snap baru sambil membatalkan intent unggah foto bukti transfer. - Pencegahan Penipuan (Anti-Fraud): Sistem sangat menopang dan bahkan menggantikan sebagian beban keandalan dari modul Anti-Fraud Conversation Shield dalam mendeteksi manipulasi receipt (resi) atau struk palsu. Modul perisai penipuan (Visi AI) yang boros token dan waktu tidak perlu lagi dilibatkan untuk menganalisis keaslian foto struk kertas dari mesin ATM jika transaksi tersebut sudah difasilitasi murni melalui konfirmasi sistem-ke-sistem Webhook. Webhook adalah kebenaran tunggal (single source of truth) yang secara matematis mustahil dipalsukan oleh pelanggan, menjadikannya perisai penipuan absolut.
- Reservasi Inventaris (Stock Booking): Tautan pembayaran membawa parameter
expiry_duration. Ketika tautan kedaluwarsa, tidak hanya invoice di Gateway yang hangus, melainkan worker belakang DAGANGBOT juga akan melepas kembali stok barang yang tadinya di-reserve untuk pesanan tersebut ke dalam katalog sirkulasi, memastikan barang tidak tertahan selamanya oleh buyer fiktif.
6. Pemecahan Masalah
Jika tautan pembayaran gagal digenerasi (bot mencetak pesan "Gagal membuat tautan pembayaran pada saat ini") atau sistem menolak pendaftaran form integrasi Anda, Anda dapat menelusuri resolusinya dari beberapa aspek berikut sebelum menghubungi tim dukungan:
- Validasi Pertukaran Kunci Midtrans (Swapped Keys):
Midtrans menerbitkan dua pasang sandi: Server Key dan Client Key. Kegagalan paling lazim dan repetitif—yang akhirnya memaksa platform untuk menangkap kesalahan ini secara proaktif—terjadi tatkala Client Key (yang lazimnya berawalan
Mid-client-atauSB-Mid-client-) direkatkan pada lajur isian form untuk Server Key. Rutinitas validasi kode internal DAGANGBOT (validateCredentialEnvironment) akan langsung melarang dan menolak penyetelan ini. Anda cukup menukar kembali posisi sisipan salin-tempel Anda pada form. - Ketidaksesuaian Lingkungan Sandbox/Production (Mode Mismatch):
Sistem menolak penyimpanan integrasi jika mendeteksi penggunaan kunci awalan
SB-(kunci tes kotak pasir Midtrans) atau awalanxnd_development_(Xendit) apabila Anda dengan sadar mencentang modeis_production: true. Secara logis, Anda dilarang meluncurkan lingkungan Live yang memotong saldo rekening asli pelanggan jika infrastruktur Anda masih berpijak pada kunci mesin uji coba. - Penyelesaian Webhook (Settlement) Terhenti atau Gagal:
Masalah klasik: Tagihan pelanggan sudah terbayar lunas dari sisi aplikasi m-banking pelanggan dan saldo mereka berkurang, namun status pesanan anehnya tidak berubah menjadi Paid pada Dasbor Manajemen Pesanan DAGANGBOT.
- Pastikan URL Webhook di pengaturan Gateway dikonfigurasi menuju tautan notifikasi yang benar (secara persis mengandung route
/webhook/payment/midtransatau/webhook/payment/xendit). - Pastikan Server Key Anda di DAGANGBOT tidak pernah diganti secara sepihak atau diputar ulang (rotated) di dasbor Midtrans tanpa melakukan penyelarasan ganda (re-sync) di dasbor DAGANGBOT. Bila hal ini terjadi, tanda tangan digital Webhook di DAGANGBOT akan terus-menerus gagal diverifikasi karena ia memakai gembok lama untuk kunci baru.
- Pastikan URL Webhook di pengaturan Gateway dikonfigurasi menuju tautan notifikasi yang benar (secara persis mengandung route
- Masa Kedaluwarsa Link Berakhir Prematur: Pembeli menekan tautan dan mendapatkan layar "Tagihan Kedaluwarsa". Ini adalah perilaku normatif jika ambang batas standar (24 jam) atau durasi kustom pendek yang Anda tetapkan telah terlampaui. Anda hanya perlu mengarahkan atau membiarkan pelanggan untuk meminta bot merilis invoice pesanan baru; jangan memaksakan membayar invoice yang sudah hangus.
Kode Error & Penanganan Khusus
DAGANGBOT memuntahkan kode validasi string yang sangat spesifik pada sistem backend log maupun toast notification untuk mengarahkan Anda ke titik akar masalah (root cause) saat men-debug sebuah integrasi pembayaran yang buntu:
