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.

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:
- 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 ).
- 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):
- Peladen DagangBot memanggil antarmuka penyedia (gateway API) untuk menciptakan URL pembayaran aktif.
- Midtrans / Xendit menembakkan sinyal Webhook (berisi XenditWebhookPayload atau Midtrans Notification) kembali ke peladen DagangBot.
- Peladen memverifikasi keaslian notifikasi. Untuk Midtrans, tanda tangan dihitung ulang sebagai
SHA-512(order_id + status_code + gross_amount + server_key)lalu dibandingkan dengan ruassignaturememakai 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. - 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_configdengan izincreatedanupdateuntuk 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 izinreadpada modul yang sama. Unggahan bukti dari sisi pelanggan dijaga izinbilling:readmilik sesi pelanggan, bukanbilling_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 galatUPLOAD_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 berawalanimage/, dengan pengecualian eksplisit untuk ekstensi.heic. Berkas juga melewati penyaringfileguard.IsMalicioussebelum 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-256atas bytes gambar yang telah dioptimasi disimpan per penyewa, sehingga pelanggan tidak bisa mendaur ulang foto resi yang sama untuk dua tagihan berbeda (galatDUPLICATE_PROOF). - Isolasi Data Antar-Tenant (Row-Level Security): Seluruh tabel pangkalan data seperti
bank_accountsdaninvoicesdilindungi 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 kolomis_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
- Masuk ke halaman Pengaturan → Pembayaran.
- Pada bagian Metode Pembayaran Manual, klik Tambah Rekening.
- Masukkan Nama Bank (contoh: Bank Central Asia) beserta Kode Bank (misal
BCA) — keduanya wajib dan masing-masing dibatasi 100 dan 20 karakter. - Masukkan Nomor Rekening berupa deret angka tanpa tambahan spasi.
- Ketik Atas Nama (Account Holder) agar pembeli memiliki jaminan keamanan sebelum transfer.
- 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 kolomsort_order.
4.2 Mengonfigurasi Gateway (Midtrans / Xendit)
- Pada layar Pengaturan → Pembayaran, pilih penyedia prioritas Anda (preferred gateway).
- Masukkan atribut Client Key dan Server Key rahasia yang diambil dari dasbor Gateway Anda.
- Pastikan URL Webhook panggil balik DagangBot disalin ke portal pihak ketiga, yaitu
/webhook/payment/midtransatau/webhook/payment/xenditpada host backend Anda. - Sistem menyediakan mekanisme cadangan (fallback). Jika Xendit downtime, Anda bisa mengalihkan rute secara dinamis.
4.3 Memverifikasi Transfer Manual Pelanggan
- Buka layar Pesanan → Menunggu Verifikasi. Anda juga akan melihat notifikasi real-time.
- Klik pesanan tersebut untuk membuka detail gambar pratinjau transfer.

- Cek silang jumlah pada faktur (
total_amount=principal_amount+unique_code) dengan riwayat perbankan mobile banking (M-Banking) toko Anda. - 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).
- Jika pembeli membiarkan tagihan melewati batas
expires_at, pekerja latar (Cron Job Worker) mengubah wujud objek daripendingmenjadiexpired. - Setelah masa berlaku hangus, semua akses pembayaran ditutup. Pembeli yang menekan tombol upload resi akan mendapat galat
INVOICE_EXPIREDdengan kode HTTP410 Gone. Unggahan bukti juga ditolak bila tagihan sudah tidak berada pada statuspendingatauwaiting_verification, atau bila rekening tujuan sudah tidak aktif. - 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 bernamaproof_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 kueriinclude_deleted=true.POST /api/v1/platform/bank-accounts: Menyimpan rekening baru (membutuhkanbank_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/midtransdanPOST /webhook/payment/xendit: Titik penerimaan notifikasi settlement dari penyedia. Midtrans dipverifikasi lewatVerifyMidtransSignature(SHA-512), Xendit lewatVerifyXenditToken(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:
