Integrasi Pengiriman Data Nasabah ke Pihak Luar
Dokumen ini menjelaskan cara data KYC nasabah dikirimkan secara otomatis ke sistem eksternal (core banking, sistem penjamin, atau partner) setelah pengajuan disetujui oleh approver berwenang.
Mekanisme Pengiriman
Ketika approver menekan Setuju dan status pengajuan berubah menjadi APPROVED, sistem secara otomatis memanggil submitKycToExternal() sebagai fire-and-forget — artinya kegagalan pengiriman tidak membatalkan proses approval.
Request yang dikirim ke endpoint luar
POST <kyc_endpoint>
Content-Type: application/json
Authorization: Bearer <kyc_api_key>
X-Api-Key: <kyc_api_key>
X-Source: customer-acquisition
X-App-No: CA-2026-00042
{ ...full KYC payload... }
Konfigurasi
Semua konfigurasi disimpan di tabel admin_settings dengan category = 'kyc_submission'. Ini memungkinkan perubahan endpoint/key tanpa deploy ulang.
| setting_key | Contoh Nilai | Keterangan |
|---|---|---|
kyc_enabled | true | Aktifkan/matikan pengiriman KYC |
kyc_endpoint | https://api.partner.id/kyc/receive | URL endpoint sistem penerima |
kyc_api_key | sk_live_xxxxx | API Key / Bearer Token untuk autentikasi |
kyc_timeout_ms | 15000 | Timeout HTTP request dalam milidetik |
kyc_include_doc_urls | true | Sertakan URL file dokumen dalam payload |
Pengajuan tetap disetujui. KYC submission dicatat dengan status PENDING dan bisa dikirim ulang manual via POST /api/kyc/:id/retry setelah konfigurasi diisi.
Format Payload KYC
Berikut adalah struktur JSON lengkap yang dikirimkan ke sistem luar. Semua nilai numerik sudah dikonversi ke tipe number (bukan Decimal string).
Struktur Top-Level
| Key | Tipe | Keterangan |
|---|---|---|
meta | Object | Informasi sumber, nomor pengajuan, cabang, produk |
application | Object | Jumlah pinjaman, tenor, tujuan, metode pencairan, credit score |
personalData | Object | Data diri nasabah (nama, NIK, TTL, status pernikahan, dll) |
contactData | Array | Nomor telepon + kontak darurat |
addressData | Array | Alamat tinggal, usaha, dan permanen + koordinat GPS |
businessData | Object | Sektor usaha, deskripsi, lama usaha, jumlah karyawan |
spouseData | Object|null | Data pasangan (jika menikah) |
financialData | Object | Ringkasan cashflow MFO + net income CA/TL |
creditHistory | Object|null | Hasil SLIK OJK (KOL 1–5, total outstanding) |
riskProfile | Object|null | Analisis 5C oleh MFO (Watak, Kemampuan, Modal, Kondisi, Collateral) |
collaterals | Array | Daftar agunan beserta estimasi nilai |
declaration | Object|null | Persetujuan SLIK dan pihak ketiga |
documents | Array | Daftar dokumen + URL akses file |
Contoh Payload Lengkap
{
"meta": {
"sourceSystem": "customer-acquisition",
"applicationNo": "CA-2026-00042",
"trackingCode": "TRK-ABCD1234",
"submittedAt": "2026-04-02T07:00:00.000Z",
"branch": { "id": 1, "name": "Cabang Jakarta Pusat", "code": "JKT-01" },
"product": { "id": 2, "name": "Kredit Mikro", "code": "KM-01" }
},
"application": {
"requestAmount": 5000000,
"tenor": 52,
"purpose": "Modal usaha warung makan",
"disbursementMethod": "bank_transfer",
"weeklyInstallment": 120000,
"creditScore": 78.5,
"creditGrade": "B"
},
"personalData": {
"fullName": "Budi Santoso",
"nik": "3271010101900001",
"gender": "L",
"placeOfBirth": "Jakarta",
"dateOfBirth": "1990-01-01T00:00:00.000Z",
"mothersName": "Siti Rahayu",
"maritalStatus": "married",
"lastEducation": "SMA",
"numberOfDependents": 2
},
"contactData": [
{
"contactType": "MN",
"contactNumber": "081234567890",
"contactName": "Budi Santoso",
"isEmergency": false,
"emergencyRelationship": null
},
{
"contactType": "MN",
"contactNumber": "081298765432",
"contactName": "Siti Rahayu",
"isEmergency": true,
"emergencyRelationship": "parent"
}
],
"addressData": [
{
"addressType": "RESIDENTIAL",
"address": "Jl. Merdeka No. 10, RT 01/RW 02",
"area": "Gambir, Jakarta Pusat",
"lengthOfStay": 60,
"statusOfResidence": "own",
"gps": { "lat": -6.1754, "lng": 106.8272 }
}
],
"businessData": {
"sector": "Perdagangan",
"subSector": "Makanan & Minuman",
"businessDesc": "Warung makan nasi padang",
"businessLength": 48,
"totalManPower": 2
},
"financialData": {
"cashflow": {
"revenuePerMonth": 12000000,
"grossOtherIncome": 12500000
},
"netIncome": {
"netIncomePerMonth": 4500000,
"maxMonthlyInstallment": 800000
}
},
"creditHistory": {
"slikStatus": "CLEAN",
"totalOutstanding": 0,
"kol1Count": 0, "kol2Count": 0, "kol3Count": 0
},
"riskProfile": {
"riskLevel": "RENDAH",
"mfoRecommendation": "RECOMMENDED",
"watakGrade": "good",
"kemampuanGrade": "good",
"hasCollateral": false
},
"declaration": {
"slikConsent": "SETUJU",
"thirdPartyConsent": true,
"agreed": true
},
"documents": [
{
"docType": "CUSTOMER_KTP",
"fileName": "ktp_budi.jpg",
"mimeType": "image/jpeg",
"url": "https://yourdomain.com/uploads/documents/ktp_budi.jpg",
"gps": null,
"uploadedAt": "2026-03-20T08:30:00.000Z"
}
]
}
Tipe Dokumen — docType
| Nilai | Keterangan |
|---|---|
CUSTOMER_KTP | Foto KTP nasabah |
CUSTOMER_PHOTO | Foto selfie / pas foto nasabah |
CUSTOMER_SIGNATURE | Tanda tangan nasabah (digital) |
SPOUSE_KTP | Foto KTP pasangan |
FAMILY_CARD | Kartu Keluarga (KK) |
HOUSE_PHOTO | Foto tempat tinggal |
BUSINESS_PHOTO | Foto lokasi usaha |
COLLATERAL_PHOTO | Foto agunan / jaminan |
OTHER | Dokumen pendukung lainnya |
API Internal — Manajemen KYC
Base URL: http://localhost:5000/api/kyc
Semua endpoint memerlukan header Authorization: Bearer <jwt_token>
Roles Diizinkan
Query Parameters
Response
{
"success": true,
"data": [{
"id": 1,
"customerId": 42,
"status": "SENT",
"externalRefId": "EXT-KYC-20260402-042",
"approvedBy": "BM",
"approvedAt": "2026-04-02T07:00:00.000Z",
"sentAt": "2026-04-02T07:00:02.000Z",
"ackAt": null,
"retryCount": 0,
"lastError": null,
"customer": {
"applicationNo": "CA-2026-00042",
"personalDetails": { "fullName": "Budi Santoso", "nik": "32710..." },
"branch": { "name": "Cabang Jakarta Pusat" }
}
}],
"pagination": { "page": 1, "limit": 20, "total": 1 }
}
Roles Diizinkan
Path Parameter
Mengembalikan 404 jika pengajuan belum pernah disetujui atau record submission belum ada.
Roles Diizinkan
Mengembalikan payload JSON lengkap persis seperti yang akan dikirim ke sistem luar. Berguna untuk debugging dan validasi data sebelum pengiriman.
Roles Diizinkan
Jika status sudah SENT atau ACKNOWLEDGED, endpoint ini akan mengembalikan error 400.
Response Sukses
{ "success": true, "message": "KYC retry berhasil dimulai" }
Roles Diizinkan
Request Body
{ "externalRefId": "EXT-KYC-20260402-042" }
Status akan berubah SENT → ACKNOWLEDGED dan field ackAt diisi dengan timestamp saat ini.
Status KYC Submission
| Status | Keterangan | Aksi Selanjutnya |
|---|---|---|
| PENDING | Endpoint belum dikonfigurasi saat approval, atau baru di-trigger | Konfigurasi endpoint, lalu retry manual |
| SENT | HTTP POST berhasil (2xx), menunggu konfirmasi dari sistem luar | Tunggu ACK, atau panggil /ack manual |
| ACKNOWLEDGED | Sistem luar mengonfirmasi penerimaan data ✓ | Selesai |
| FAILED | HTTP error, timeout, atau network error | Cek lastError, perbaiki, lalu retry |
| Sedang dalam proses retry manual | Tunggu hasil (akan berubah ke SENT atau FAILED) |
Alur Lengkap
requestAmount ≤ approvalLimit BM?APPROVEDKYC dikirim otomatis
KYC dikirim setelah approval final
submitKycToExternal() dipanggilSENTexternalRefId disimpan
FAILEDlastError dicatat
POST /api/kyc/:id/ack → status ACKNOWLEDGEDSetup Database
Jalankan SQL berikut untuk mengaktifkan pengiriman KYC ke endpoint tertentu:
INSERT INTO admin_settings (category, setting_key, setting_value, description) VALUES ('kyc_submission', 'kyc_enabled', 'true', 'Aktifkan pengiriman KYC'), ('kyc_submission', 'kyc_endpoint', 'https://api.partner.id/kyc/receive', 'URL endpoint sistem luar'), ('kyc_submission', 'kyc_api_key', 'sk_live_XXXXXXXXXXXX', 'API Key / Bearer Token'), ('kyc_submission', 'kyc_timeout_ms', '15000', 'Timeout request dalam ms'), ('kyc_submission', 'kyc_include_doc_urls', 'true', 'Sertakan URL dokumen dalam payload');
Data Sensitif & Keamanan
| Item | Perlindungan |
|---|---|
| NIK, foto KTP, tanda tangan | Pastikan endpoint tujuan menggunakan HTTPS. Data hanya dikirim ke endpoint yang terdaftar. |
| API Key | Disimpan di tabel admin_settings (database), tidak di-hardcode di source code atau environment file. |
| Log respons | Disimpan di kyc_submissions.response_payload, dipotong maksimal 65KB untuk menghindari kebocoran data berlebih. |
| Kegagalan pengiriman | Tidak membatalkan proses approval. Error dicatat dan dapat di-retry tanpa mempengaruhi alur bisnis. |
| Akses API Internal | Endpoint /api/kyc/* memerlukan JWT yang valid + role check. Preview payload hanya ADMIN. |