Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

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

Kartu Integrasi Payment Gateway di dasbor DagangBot
Panel kartu integrasi Payment Gateway dengan panduan penyedia Midtrans dan Xendit di Dasbor Integrasi.

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

Modal Konfigurasi Kredensial Payment Gateway
Formulir modal konfigurasi Payment Gateway untuk input Provider, Server Key, dan Client Key terenkripsi.

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

  1. Pilih Penyedia Gateway: Platform saat ini mendukung Midtrans (Snap) dan Xendit. Buat akun bisnis pada salah satu platform.
  2. 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).

Tahap 2: Perekaman Kredensial di DAGANGBOT

  1. Akses Dasbor Integrasi: Buka Dasbor DAGANGBOT, navigasikan ke modul "Integrasi" dan klik tombol "Tambah Integrasi Baru". Pilih jenis "Pembayaran".
  2. Pilih Penyedia: Pada menu tarik-turun, pilih Midtrans atau Xendit sesuai kunci yang telah Anda siapkan.
  3. Masukkan Kredensial: Isikan parameter yang diperoleh dari penyedia ke dalam formulir.
  4. Tentukan Mode Lingkungan: Pastikan memilih sakelar mode Sandbox atau Production yang tepat agar seragam dengan identitas kunci. Kunci berawalan SB- atau xnd_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 header X-Override-Notification pada 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/xendit ke 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:

  1. Ganti seluruh kata sandi (kunci API) di DAGANGBOT ke varian Production.
  2. Ubah tautan webhook ke mode Production pada dasbor Midtrans/Xendit.
  3. 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_id atau external_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/billing setelah pelanggan selesai bertransaksi di halaman Midtrans Snap.

Spesifikasi Midtrans Snap

Tanda pengenal kunci di Midtrans bersifat eksplisit berdasarkan peruntukannya.

Atribut Parameter Tipe Keterangan
provider String Diisi konstan dengan nilai midtrans.
server_key String Kunci akses server rahasia milik Anda. Biasanya diawali Mid-server- untuk versi Live atau SB-Mid-server- untuk versi kotak pasir (sandbox).
client_key String Kunci klien pelengkap (Client Key). DAGANGBOT menggunakan proteksi penolakan otomatis apabila nilai Server Key keliru diisi dengan Client Key.
is_production Boolean Apabila true, lingkungan akan menggunakan rute rujukan Snap dan validasi Webhook tingkat produksi. DAGANGBOT akan memblokir jika Server Key bertanda SB- namun modenya produksi.
enabled_payments Array (Opsional) Daftar spesifik kanal pembayaran yang ingin ditampilkan pada halaman Snap. Contoh: ["qris", "bca_va", "gopay", "shopeepay"]. Jika dikosongkan, semua saluran yang diizinkan Midtrans akan muncul.
notification_url String (Opsional) URL Webhook statis untuk memintas penentuan URL dinamis dari platform.

Spesifikasi Xendit Invoice

Untuk Xendit, parameter yang disertakan sedikit berbeda, terutama pada alur pembuktian Webhook tingkat aplikasi (Application-Level Webhook Security).

Atribut Parameter Tipe Keterangan
provider String Diisi konstan dengan nilai xendit.
api_key String Kunci akses Secret untuk Xendit. Umumnya berawalan xnd_development_ untuk mode kotak pasir atau xnd_production_ untuk rilis Live.
callback_token String Callback Verification Token Xendit, diperlukan bagi DAGANGBOT (pada lapis Handler) agar menjamin Webhook dikirim murni oleh entitas Xendit, mencegah pemalsuan pembayaran oleh pihak ketiga.
is_production Boolean Lingkungan produksi (true) yang akan mendikte rute URL dasar Xendit.

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).

bash
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:

json
{
  "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:

bash
# 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.

  1. Validasi Tanda Tangan Kriptografi (Midtrans): Saat server Midtrans memanggil webhook, ia selalu menyertakan atribut signature_key di dalam badan JSON (payload). DAGANGBOT, secara internal melalui fungsi VerifyMidtransSignature, merangkai kombinasi string mentah berupa order_id + status_code + gross_amount + server_key rahasia Anda. String gabungan ini kemudian dilebur (hashing) dengan algoritma kriptografi satu arah SHA-512. Jika, dan hanya jika, keluaran hash murni ini secara identik cocok dengan nilai signature_key dari muatan Midtrans, barulah DAGANGBOT mempercayai dan memvalidasi pembayaran.
  2. 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-token yang 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 HTTP 403 Forbidden, tanpa pernah menyentuh database.
  3. 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 OK tanpa 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):

bash
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:

  1. 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- atau SB-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.
  2. Ketidaksesuaian Lingkungan Sandbox/Production (Mode Mismatch): Sistem menolak penyimpanan integrasi jika mendeteksi penggunaan kunci awalan SB- (kunci tes kotak pasir Midtrans) atau awalan xnd_development_ (Xendit) apabila Anda dengan sadar mencentang mode is_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.
  3. 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/midtrans atau /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.
  4. 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:

Kode Error / Status Log Keterangan dan Solusi Penanganan Logis
MIDTRANS_KEY_SWAPPED Secara harfiah Server Key dan Client Key tertukar. Fungsi Gateway internal DAGANGBOT mendeteksi string dan memprotes kunci Mid-client- yang dikirim ke slot penyimpanan Server. Solusinya, tukar kembali penempatan Client Key dan Server Key di halaman konfigurasi Anda.
midtrans: server key not configured Sistem gagal total menginisialisasi panggilan ke app.midtrans.com karena kunci rahasia (secret) tidak termuat, tertinggal, atau kosong dari hasil pembacaan basis data. Pastikan integrasi pembayaran belum dinonaktifkan (disabled) dan kunci tersimpan baik.
invalid midtrans signature Pemrosesan Webhook Handler menolak dan membatalkan sinyal masuk. Algoritma SHA-512 muatan JSON Midtrans tidak sepadan dengan Server Key. Kemungkinan: Server Key di DAGANGBOT lapuk (stale) karena Anda baru me-reset kunci di dasbor Midtrans.
WEBHOOK_FAILED Token pelindung pada penanda HTTP permintaan Xendit (variabel x-callback-token) tidak sepadan dengan karakter Callback Token yang tersimpan di pengaturan sistem DAGANGBOT Anda, memicu penolakan payload pada lapisan perantara (handler). Tinjau dasbor Xendit, buat token verifikasi webhook baru, dan salin ulang.
xendit: development api key cannot use production mode Aturan pemeriksaan awalan sandi API keliru bagi Xendit. Mematikan toggle Sandbox ke posisi Live / Produksi mewajibkan adanya penggunaan API Key yang murni berawalan xnd_production_.

7. Referensi Terkait

content/docs/integrations/payment.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot