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

Rekening Bank Toko & Integrasi Pembayaran

1. Ikhtisar & Nilai Bisnis

Bagi bisnis yang belum atau tidak ingin menggunakan Payment Gateway otomatis karena alasan potongan biaya administrasi, DagangBot menyediakan fasilitas Pembayaran Manual. Pelanggan akan melihat daftar rekening bank milik toko Anda saat proses bayar ( checkout ), mentransfer dana secara mandiri, lalu mengunggah gambar bukti transfer.

Namun, bagi skala bisnis menengah, DagangBot juga menyediakan integrasi dengan penyedia otomatis (Payment Gateway) terkemuka seperti Midtrans dan Xendit. Fitur ini mengurangi hambatan transaksi dan memotong waktu verifikasi manual, sehingga konversi penjualan meningkat tajam.

Tampilan antarmuka integrasi Payment Gateway di konsol DagangBot
Antarmuka kartu integrasi Payment Gateway dengan panduan sambungan Midtrans dan Xendit.

Sistem menyediakan dasbor untuk memverifikasi bukti bayar manual, memantau webhook gateway, dan melanjutkan pesanan ke tahap operasional tanpa kebingungan teknis.

2. Konsep Dasar

Terdapat dua jalur aliran dana pada sistem DagangBot:

  1. Rekening Bank Manual (Bank Accounts): Daftar akun finansial milik toko. Setiap akun memuat nama bank, nomor rekening, dan nama pemilik. Anda bisa mendaftarkan lebih dari satu rekening (misal: BCA, Mandiri, dan GoPay). Data rekening ini terikat penuh dengan kepemilikan Anda ( Row-Level Security ).
  2. Gateway Otomatis (Xendit/Midtrans): Pihak ketiga yang menghasilkan nomor kode sekali pakai (Single-use Virtual Account) atau QRIS, yang akan memotong saldo pembeli dan secara otomatis memberitahukan peladen (webhook callback) saat dana masuk.

2.1 Alur Siklus Hidup Pembayaran Manual

Faktur (invoice) memiliki tahapan status (state machine) yang berhubungan dengan objek bukti bayar:

  • pending: Pelanggan sudah checkout namun belum membayar. Sistem menanti pembeli.
  • waiting_verification: Pelanggan berhasil mengunggah foto bukti bayar, menunggu persetujuan Anda sebagai admin.
  • approved: Admin toko memvalidasi dan menerima resi bukti tersebut. Status faktur otomatis berubah menjadi Lunas (paid).
  • rejected: Admin menolak bukti bayar (misal: gambar blur, dana belum masuk). Siklus rekaman penolakan ini dikunci, pelanggan harus mengirim bukti unggahan baru.

2.2 Alur Rekonsiliasi Gateway

Sistem gerbang pembayaran beroperasi secara independen (tanpa campur tangan kasir Anda):

  1. Peladen DagangBot memanggil antarmuka penyedia (gateway API) untuk menciptakan URL pembayaran aktif.
  2. Midtrans / Xendit menembakkan sinyal Webhook (berisi XenditWebhookPayload atau Midtrans Notification) kembali ke peladen DagangBot.
  3. Peladen memverifikasi keaslian notifikasi. Untuk Midtrans, tanda tangan dihitung ulang sebagai SHA-512(order_id + status_code + gross_amount + server_key) lalu dibandingkan dengan ruas signature memakai pembanding waktu-konstan (constant-time compare). Untuk Xendit, ruas callback token dibandingkan utuh (juga waktu-konstan) terhadap kunci yang tersimpan di konfigurasi penyewa. Kunci kosong selalu berakhir gagal-tertutup (fail closed), sehingga notifikasi palsu tidak pernah diterima.
  4. Sistem otomatis mengubah status menjadi paid.

3. Prasyarat & Keamanan (Security & Limits)

  • Hak Akses Tingkat Penagihan (Billing Access): Anda wajib memiliki hak istimewa RBAC (Role-Based Access Control) billing_config dengan izin create dan update untuk mengatur dan menambah rekening bank atau memodifikasi kredensial Midtrans/Xendit. Sementara itu, staf kasir (Customer Service) yang bertugas mengecek mutasi dan menekan tombol verifikasi manual cukup dibekali izin read pada modul yang sama. Unggahan bukti dari sisi pelanggan dijaga izin billing:read milik sesi pelanggan, bukan billing_config.
  • Batas Toleransi Unggah Bukti (Payload Limit): Berkas bukti bayar yang diunggah pelanggan melalui antarmuka obrolan (chat) dibatasi ukuran maksimalnya oleh konfigurasi payment_methods.manual_payment.max_upload_size_mb (bawaan 5 MB). Nilai ini dibaca saat permintaan berjalan, jadi perubahan konfigurasi berlaku langsung tanpa restart. Berkas juga divalidasi ulang setelah optimasi gambar, karena proses kompresi bisa membesarkan ukuran berkas.
  • Pembatasan Laju Unggah (Upload Rate Limit): Konfigurasi payment_methods.max_uploads_per_hour (bawaan 5) menutup celah penyalahgunaan: bila jumlah bukti unggahan penyewa dalam satu jam terakhir sudah menyentuh ambang, permintaan ditolak dengan galat UPLOAD_LIMIT_REACHED.
  • Format File yang Sah (MIME Type Enforcement): Peladen mengeksekusi validasi sisi backend dengan membaca signature biner berkas melalui http.DetectContentType, bukan sekadar melihat ekstensi penamaan fail. Isi berkas wajib terdeteksi berawalan image/, dengan pengecualian eksplisit untuk ekstensi .heic. Berkas juga melewati penyaring fileguard.IsMalicious sebelum disimpan. Format dokumen seperti PDF, DOCX, atau rekaman video (MP4) secara otomatis ditolak karena tidak sesuai untuk pengenalan gambar.
  • Deteksi Unggahan Ganda (Duplicate Proof Detection): Sidik jari SHA-256 atas bytes gambar yang telah dioptimasi disimpan per penyewa, sehingga pelanggan tidak bisa mendaur ulang foto resi yang sama untuk dua tagihan berbeda (galat DUPLICATE_PROOF).
  • Isolasi Data Antar-Tenant (Row-Level Security): Seluruh tabel pangkalan data seperti bank_accounts dan invoices dilindungi isolasi RLS ketat. Kegagalan atau kesalahan injeksi pemanggilan API dari penyewa lain tidak akan bisa membocorkan mutasi rekening ataupun bocoran daftar transfer milik toko Anda. Pengecualiannya hanya tabel rekening bank: pemeriksaan keaktifan rekening dibaca langsung dari kolom is_active, sementara kepemilikan tagihan tetap diverifikasi eksplisit terhadap ID penyewa pemanggil.
  • Akun Gateway: Untuk metode otomatis, Anda wajib memiliki akun aktif (telah lolos KYC/KYB) di Midtrans atau Xendit.

4. Panduan Operasional

4.1 Menambah Rekening Manual

  1. Masuk ke halaman Pengaturan → Pembayaran.
  2. Pada bagian Metode Pembayaran Manual, klik Tambah Rekening.
  3. Masukkan Nama Bank (contoh: Bank Central Asia) beserta Kode Bank (misal BCA) — keduanya wajib dan masing-masing dibatasi 100 dan 20 karakter.
  4. Masukkan Nomor Rekening berupa deret angka tanpa tambahan spasi.
  5. Ketik Atas Nama (Account Holder) agar pembeli memiliki jaminan keamanan sebelum transfer.
  6. Simpan konfigurasi. Sistem merender informasi ini secara dinamis pada halaman checkout WhatsApp. Rekening juga bisa dinonaktifkan sementara (is_active = false) tanpa harus menghapusnya, dan diurutkan tampilannya lewat kolom sort_order.

4.2 Mengonfigurasi Gateway (Midtrans / Xendit)

  1. Pada layar Pengaturan → Pembayaran, pilih penyedia prioritas Anda (preferred gateway).
  2. Masukkan atribut Client Key dan Server Key rahasia yang diambil dari dasbor Gateway Anda.
  3. Pastikan URL Webhook panggil balik DagangBot disalin ke portal pihak ketiga, yaitu /webhook/payment/midtrans atau /webhook/payment/xendit pada host backend Anda.
  4. Sistem menyediakan mekanisme cadangan (fallback). Jika Xendit downtime, Anda bisa mengalihkan rute secara dinamis.

4.3 Memverifikasi Transfer Manual Pelanggan

  1. Buka layar Pesanan → Menunggu Verifikasi. Anda juga akan melihat notifikasi real-time.
  2. Klik pesanan tersebut untuk membuka detail gambar pratinjau transfer.
Layar verifikasi resi transfer pelanggan
Dasbor staf kasir ketika memeriksa gambar resi pembayaran manual.
  1. Cek silang jumlah pada faktur (total_amount = principal_amount + unique_code) dengan riwayat perbankan mobile banking (M-Banking) toko Anda.
  2. Klik Terima jika nominal sesuai (approved), atau Tolak (rejected) dengan menyertakan catatan kegagalan. Perekaman jejak audit (audit trail) menyalin profil staf Anda untuk keperluan audit di kemudian hari.

4.4 Menangani Jatuh Tempo (Expiration Timeout)

Ketika pembeli memesan keranjang dan masuk ke fase tagihan (invoice generation), sistem menetapkan tenggat expires_at sebesar jam yang dikonfigurasi pada payment_methods.gateway.deadline_hours (bawaan 1 jam).

  1. Jika pembeli membiarkan tagihan melewati batas expires_at, pekerja latar (Cron Job Worker) mengubah wujud objek dari pending menjadi expired.
  2. Setelah masa berlaku hangus, semua akses pembayaran ditutup. Pembeli yang menekan tombol upload resi akan mendapat galat INVOICE_EXPIRED dengan kode HTTP 410 Gone. Unggahan bukti juga ditolak bila tagihan sudah tidak berada pada status pending atau waiting_verification, atau bila rekening tujuan sudah tidak aktif.
  3. Toko tidak perlu membersihkan antrean ini, karena sapuan otomatis tersebut sekaligus merilis kembali alokasi stok barang yang tertahan (stock hold release).

5. Skenario Lanjutan

5.1 Siklus Bukti yang Sudah Ditolak

Sistem mencegah Anda untuk merevisi keputusan status menjadi pending atau waiting_verification kembali setelah bukti terlanjur ditolak. Apabila sebuah entitas unggahan sudah berstatus rejected, maka siklus hidup (state) objek tersebut selesai dan terkunci (immutable). Pelanggan akan diberikan pesan kegagalan dan tautan untuk menciptakan unggahan baru dengan identifikasi unik (UUID) yang berbeda — berkas baru selalu disimpan pada kunci objek baru, sehingga tidak pernah menimpa bukti lama.

5.2 Kode Unik Penanda Transfer (Unique Code)

Untuk mempercepat identifikasi mutasi (rekonsiliasi) di riwayat bank Anda, sistem dapat menghasilkan tiga digit angka acak khusus di belakang total akhir harga (misalnya belanja Rp100.000 menjadi Rp100.214). Angka 214 ini diundi saat tagihan manual dibuat, dari rentang tertutup yang diatur oleh payment_methods.manual_payment.unique_code_min (bawaan 1) dan payment_methods.manual_payment.unique_code_max (bawaan 999). Pengundian memakai kunci penasihat PostgreSQL (advisory lock) dan membaca tabel invoices untuk memastikan tidak ada dua tagihan aktif memakai kode yang sama; bila rentang habis, tagihan gagal dibuat dengan galat ErrUniqueCodeExhausted. Selalu patokan mutasi ke total akhir, bukan sub-total barang.

5.3 Filter dan Pencarian Silang

Halaman verifikasi pembayaran mendukung penyaringan parameter URL. Melalui fungsi tabel gabungan (SQL JOIN) antara faktur, pesanan, dan akun bank, satu kotak pencarian tunggal dapat memuat kueri pelanggan maupun ID pesanan. Daftar bukti juga menyertakan nama rekening tujuan (b.bank_name, b.account_number) agar kasir tidak perlu berpindah layar.

5.4 Pencatatan Panggil Balik (Webhook Audit)

Dalam skenario pengalihan dari gateway, DagangBot menyimpan balasan mentah (raw JSON payload) dari pihak ketiga. Jika pembeli mengeklaim "Saya sudah bayar OVO" namun pesanan tidak diproses, staf dukungan teknis toko bisa mencari nama pembeli di tabel pesanan dan menelusuri bilah Network / Gateway Logs di dasbor. Jika tidak ada rekaman panggil balik untuk pesanan tersebut, kesalahan mutlak ada pada sisi Midtrans / Xendit atau keterlambatan perbankan inti (core banking system), bukan peladen DagangBot.

6. Referensi Terkait

Antarmuka pembayaran di dalam platform ditangani oleh ekosistem layanan berantai.

6.1 Endpoint Sisi Penyewa (Tenant)

  • GET /api/v1/billing/payment-methods: Menghasilkan daftar metode pembayaran yang aktif untuk penyewa.
  • GET /api/v1/billing/bank-accounts: Menghasilkan larik daftar rekening toko terautentikasi.
  • POST /api/v1/billing/manual-transfer/{id}/upload-proof: Menangani unggahan multipart berkas bukti bayar; bidang formulir wajib bernama proof_image.
  • POST /api/v1/billing/topup/manual-proof: Rute kembar untuk unggahan bukti pada alur topup saldo.
  • GET /api/v1/billing/manual-transfer/{id}: Menyajikan detail tagihan, kode unik, dan daftar rekening tujuan bagi pembeli.

6.2 Endpoint Sisi Platform (Admin)

  • GET /api/v1/platform/bank-accounts: Daftar seluruh rekening, mendukung kueri include_deleted=true.
  • POST /api/v1/platform/bank-accounts: Menyimpan rekening baru (membutuhkan bank_name, bank_code, account_number, account_holder).
  • PUT /api/v1/platform/bank-accounts/{id}: Mengubah atribut rekening, termasuk menonaktifkan atau mengubah urutan tampil.
  • DELETE /api/v1/platform/bank-accounts/{id}: Menghapus opsi rekening dari daftar penyewa.
  • GET /api/v1/platform/payment-methods: Membaca status aktif setiap metode pembayaran.
  • PUT /api/v1/platform/payment-methods: Menentukan penyedia prioritas (preferred gateway) dan metode yang dinyalakan.
  • GET /api/v1/platform/manual-payments: Menampilkan daftar bukti pembayaran yang menunggu verifikasi, lengkap dengan pemilahan, paginasi, dan pencarian berpengereman (debounced search).
  • GET /api/v1/platform/manual-payments/{id}: Membuka detail satu bukti pembayaran.
  • POST /api/v1/platform/manual-payments/{id}/verify: Memproses persetujuan atau penolakan bukti.
  • POST /webhook/payment/midtrans dan POST /webhook/payment/xendit: Titik penerimaan notifikasi settlement dari penyedia. Midtrans dipverifikasi lewat VerifyMidtransSignature (SHA-512), Xendit lewat VerifyXenditToken (pembandingan token waktu-konstan), agar payload tidak bisa dipalsukan oleh klien pihak luar.

6.3 Skema Payload Verifikasi Bukti

Rute POST /api/v1/platform/manual-payments/{id}/verify menerima skema dengan tata letak sebagai berikut:

Bidang (Field) Tipe Status Deskripsi
status enum Wajib Hanya menerima dua kata cadangan murni: approved atau rejected.
actual_amount_received integer Wajib jika approved Nominal dana yang benar-benar masuk; harus lebih besar dari nol.
rejection_reason string Wajib jika rejected Teks keterangan penolakan yang akan dilempar (forward) ke layar WhatsApp pelanggan.
reject_action enum Opsional retry (bawaan) atau cancel, menentukan nasib tagihan setelah ditolak.
admin_notes string Opsional Catatan internal staf yang tidak dibaca pelanggan.

6.4 Kode Balasan (HTTP Status Codes)

Kode Deskripsi Sistem Panduan Pemulihan (Fallback)
200 OK Operasi sukses tersimpan, saldo/stok sudah bergeser, dan pesan telah dipicu. Alur sempurna.
400 Bad Request Kurang parameter wajib, status tagihan tidak menerima bukti (INVALID_STATUS), tagihan bukan transfer manual (NOT_MANUAL), atau berkas terdeteksi duplikat (DUPLICATE_PROOF). Tampilkan pesan galat apa adanya ke kasir; minta pelanggan mengunggah berkas berbeda.
403 Forbidden Upaya manipulasi ID tagihan beda penyewa atau ketiadaan RBAC izin. Hentikan proses, paksa klien memuat ulang hak akses (refresh token).
404 Not Found ID tagihan atau bukti tidak dikenal. Segarkan daftar pesanan sebelum mengulang aksi.
410 Gone Tagihan telah melewati expires_at (INVOICE_EXPIRED). Buat tagihan baru; unggahan bukti pada objek lama tidak akan diterima.
413 Payload Too Large Ukuran berkas melewati ambang max_upload_size_mb, baik sebelum maupun sesudah optimasi gambar (FILE_TOO_LARGE). Pelanggan wajib memperkecil resolusi foto resi.
429 Too Many Requests Batas unggah per jam per penyewa tercapai (UPLOAD_LIMIT_REACHED). Tunggu hingga jendela satu jam bergulir, atau naikkan payment_methods.max_uploads_per_hour.

7. Pemecahan Masalah

Masalah Penyebab Solusi
Gagal mengunggah foto ("Ukuran file melebihi batas") Resolusi kamera pelanggan sangat tinggi sehingga berkas lebih besar dari batas konfigurasi (bawaan 5 MB). Minta pelanggan mengecilkan ukuran (compress) gambar atau menangkap layar ulang (screenshot pada screenshot).
Pesan Error ("File harus berupa format gambar") Klien pelanggan mencoba mengirim berkas ekstensi non-gambar (misal PDF atau Word). Arahkan pelanggan untuk hanya membagikan foto ekstensi JPG, PNG, WebP, atau HEIC.
Tombol Setujui terkunci / tidak bisa diklik Status bukti unggahan bukan lagi pending atau waiting_verification. Jika pelanggan sudah mengunggah ulang, cari entri unggahan terbaru di daftar pesanan, bukan memuat kembali ID resi yang lama (kadaluwarsa).
Faktur via Gateway tidak pernah paid padahal pembeli dipotong Konfigurasi Webhook URL di dashboard Midtrans/Xendit Anda keliru/kosong, sehingga DagangBot buta terhadap notifikasi bank. Salin URL Webhook DagangBot ke pengaturan gateway Anda, lalu jalankan fitur pengujian notifikasi di situs mereka.
Gagal checkout Gateway Not Configured Anda memilih metode otomatis namun kolom Server Key dibiarkan kosong. Lengkapi kunci otentikasi. Jika Anda belum disetujui KYC oleh pihak Gateway, alihkan tombol ke metode Rekening Manual.
Nominal uang pembeli tidak pas (Lebih/Kurang) Pembeli mungkin melupakan atau mencantumkan tiga digit kode unik transfer manual. Jika kurang, hubungi pelanggan. Jika lebih, konfirmasi kelebihan tersebut atau abaikan demi mengejar status paid.
content/docs/features/payment-methods-bank.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot