Integrasi Pihak Ketiga & Ekosistem Digital - Unit Simpan Pinjam (UNT-USP)

Dokumen ini memuat spesifikasi integrasi antarmuka pemrograman aplikasi (Application Programming Interface / API) dengan mitra perbankan, gerbang pembayaran digital, mesin notifikasi pesan singkat, serta layanan geolokasi spasial pada Unit Simpan Pinjam BUMDes.

1. Arsitektur Lanskap Integrasi#

+-------------------------------------------------------------------------+
| ERP BUMDes - Core USP Engine |
| (PostgreSQL, Supabase Auth, Row Level Security, Automated Ledger Hooks) |
+-------------------------------------------------------------------------+
 | | |
 v v v
+------------------+ +-------------------+ +--------------------+
| Payment Gateway | | WhatsApp Gateway | | Geolocation & Maps |
| (QRIS & VA Bank) | | (Reminder Engine) | | (OpenStreetMap/GIS)|
+------------------+ +-------------------+ +--------------------+
 | | |
 v v v
 Bank Pembangunan Debitur & Penjamin Audit Fisik Agunan
 Daerah (BPD) / BRI Kolektor Lapangan & Verifikasi Domisili

2. Gerbang Pembayaran Digital (QRIS & Virtual Account)#

2.1. Alur Transaksi Virtual Account (VA) Bank Mitra

Untuk memfasilitasi angsuran debitur yang memiliki mobilitas tinggi di luar desa:

1. Setiap nomor kontrak pinjaman secara otomatis dihubungkan dengan 16-digit Static Virtual Account dari Bank Mitra (misalnya BPD Jawa Timur, Bank Jateng, Bank BJB, atau BRI).

• Format: [Bank Prefix 4 Digit][Kode Unit USP 2 Digit][Nomor Rekening Debitur 10 Digit].

2. Saat debitur melakukan transfer melalui ATM/Mobile Banking, webhook dari server perbankan mengirimkan muatan data (payload) HTTP POST terenkripsi HMAC-SHA256 ke endpoint ERP BUMDes: POST https://api.bumdes.desa.id/v1/integrations/payment-webhook
3. Sistem memverifikasi tanda tangan digital, mencocokkan nomor tagihan, membukukan jurnal debet Kas Bank 1-101.05 dan kredit Piutang Angsuran 1-120.05 & Pendapatan Bunga 4-100.05.

2.2. Dynamic QRIS untuk Loket Teller & Kolektor

• Sistem menghasilkan Dynamic QRIS berstandar Bank Indonesia (ASPI) pada layar tablet loket atau printer bluetooth kolektor.
• Nilai QRIS disetel persis sesuai nominal angsuran sehingga menghilangkan kesalahan input (human error) nominal oleh nasabah.
• Status pembayaran terkonfirmasi otomatis dalam waktu kurang dari 3 detik melalui polling webhook real-time.

3. Notifikasi Otomatis WhatsApp Gateway#

Sistem mengintegrasikan WhatsApp Business Cloud API untuk menjaga komunikasi proaktif dan transparan dengan anggota:

3.1. Notifikasi Transaksi Seketika (Instant Receipt)

• Setiap kali teller atau kolektor menginput setoran tunai tabungan atau angsuran pinjaman, debitur secara otomatis menerima pesan konfirmasi WhatsApp resmi:

BUMDES MANDIRI - TANDA TERIMA ANGSURAN RESMI

Yth. Bpk/Ibu [Nama Debitur], Pembayaran angsuran ke-[N] untuk No. Pinjaman [KONTRAK-ID] sebesar Rp [Nominal] telah kami terima pada [Tanggal & Waktu].

• Pokok: Rp [Nominal Pokok]
• Bunga: Rp [Nominal Bunga]
• Sisa Baki Debet: Rp [Sisa Pokok]

Struk sah digital dapat diunduh di: https://bumdes.desa.id/kwitansi/[UUID] Simpan pesan ini sebagai bukti pembayaran yang sah.

3.2. Peringatan Dini Jatuh Tempo (Early Reminder Engine)

• Jadwal H-3 Jatuh Tempo: Pengingat sopan jadwal jatuh tempo dan rincian nominal tagihan.
• Jadwal H-1 Jatuh Tempo: Konfirmasi apakah debitur akan membayar via teller, transfer VA, atau dikunjungi kolektor.
• Jadwal H+1 Keterlambatan: Notifikasi tunggakan dan pemberitahuan ketentuan denda keterlambatan harian sesuai perjanjian kredit.

4. Verifikasi Spasial & Pemetaan Agunan (GIS API)#

Sistem memanfaatkan integrasi OpenStreetMap (OSM) dan GeoJSON untuk pengamanan risiko kredit:

1. Geotagging Domisili Debitur:

• Analis kredit wajib merekam titik koordinat GPS (latitude, longitude) serta akurasi presisi (kurang dari 10 meter) saat melakukan survei fisik tempat tinggal.

2. Pemetaan Batas Agunan Lahan (Polygon Boundaries):

• Untuk agunan berupa tanah kas desa, sawah, atau pekarangan bersertifikat/petok D, analis menggambar poligon batas tanah pada modul GIS ERP.
• Peta batas ini mencegah penjaminan ganda (double pledging) atas sebidang tanah yang sama kepada dua peminjam berbeda.

5. Keamanan & Kepatuhan Integrasi API#

• Enkripsi Data: Seluruh pertukaran data API pihak ketiga wajib menggunakan protokol TLS 1.3 dengan sertifikat SSL minimal 2048-bit RSA.
• API Key & Secret Rotation: Kunci otentikasi API disimpan dalam environment variables terenkripsi dan diputar secara berkala setiap 90 hari.
• Idempotency Key: Setiap panggilan transaksi penagihan atau pembayaran menyertakan UUID Idempotency Key untuk mencegah eksekusi ganda jika terjadi network timeout.