Lewati ke konten utama

Merchant Verification — Scope & Pemisahan Domain

Dibuat: 2026-06-07
Konteks: Keputusan arsitektur saat Phase 5.5 KYC write cutover diimplementasi.

1. KYC vs KYB — Terminologi Industri​

Industri verifikasi digital membedakan dua istilah yang sering dicampur:

KYC — Know Your Customer​

Verifikasi identitas individu (pemilik / penanggung jawab akun).

"Siapa kamu?"

Produk KYC API (Verihubs, Privy, Sumsub, dll.) mencakup:

  • OCR dokumen identitas — ekstrak data dari KTP/Passport/SIM
  • Face match — cocokkan selfie dengan foto di dokumen
  • Liveness detection — pastikan selfie bukan foto dari foto (anti-spoofing)
  • Dukcapil check — validasi NIK ke database kependudukan pemerintah (Indonesia)

KYC menjawab pertanyaan: apakah orang ini adalah siapa yang mereka klaim?

KYB — Know Your Business​

Verifikasi entitas bisnis yang diwakili individu tersebut.

"Apakah usahamu nyata dan sah?"

Produk KYB API mencakup:

  • NPWP check — validasi ke database DJP
  • NIB check — validasi Nomor Induk Berusaha ke OSS
  • SIUP / izin usaha check — verifikasi legalitas operasional
  • Rekening bank check — verifikasi nama pemilik rekening sesuai data usaha

KYB menjawab pertanyaan: apakah entitas bisnis ini terdaftar secara legal?

Perbedaan kunci​

KYCKYB
SubjekIndividu (pemilik/penanggung jawab)Entitas bisnis
Dokumen utamaKTP, PassportNPWP, NIB, akta perusahaan
Bisa di-API-kan sepenuhnyaYa — dokumen digital + biometrikSebagian — foto usaha tetap manual review
Foto tempat usahaBukan bagian KYCBukan bagian KYB formal — manual evidence
Regulasi acuanOJK POJK 12/2017, Permendagri 19/2010OJK POJK 12/2017, UU Cipta Kerja

Catatan: Foto tempat usaha (business_photo_url) tidak masuk KYC maupun KYB formal berbasis API. Ini adalah manual evidence — reviewer manusia yang menilai, bukan sistem otomatis.

2. Dua Domain Verifikasi di Kesles​

Proses onboarding merchant Kesles melibatkan dua jenis verifikasi yang secara konsep berbeda dan disimpan di tempat yang berbeda:

KYC — Identity VerificationKYB — Business Verification
Pertanyaan utamaSiapa pemiliknya?Apakah usahanya nyata?
DokumenKTP, selfie/livenessFoto usaha, NPWP, rekening bank
SOT (Source of Truth)kyc.submissions di db_kesles_merchant_authmerchant.merchant_registration_requests di db_kesles_merchant
Service ownerauth_servicemerchant_core_api
Dipakai untukFraud detection, re-KYC, dedup lintas akunReview kelayakan usaha, acquirer submission

3. KYC — Identity Verification​

Scope​

KYC di Kesles adalah verifikasi identitas pemilik merchant. Cakupannya:

  • Dokumen identitas: foto KTP (ktp_photo_url)
  • Liveness check: selfie pemilik (face_photo_url)
  • Data yang di-extract dari KTP via OCR:
    • nik — 16-digit NIK
    • owner_name — nama lengkap sesuai KTP
    • birth_date — tanggal lahir (derivasi dari NIK digit 7–12, Permendagri 19/2010)
    • gender — jenis kelamin (derivasi dari NIK digit 7)
  • Kualitas OCR:
    • ktp_nik_confidence — confidence score NIK hasil scan (0–100)
    • ktp_name_confidence — confidence score nama hasil scan (0–100)
    • ktp_was_edited_after_prefill — apakah user mengedit data setelah OCR prefill
  • Fraud signal:
    • ktp_photo_sha256 — hash SHA-256 foto KTP untuk dedup lintas akun
    • face_photo_sha256 — hash SHA-256 selfie untuk dedup
    • nik_invalid_date_pattern — flag NIK 16-digit numeric tapi tanggal tidak valid (dokumen mencurigakan)

Storage​

Database: db_kesles_merchant_auth
Schema/Table: kyc.submissions
Dikelola oleh: auth_service via POST /internal/kyc/submissions

KYC disimpan terpisah dari data merchant karena:

  1. Bersifat PII sensitif — akses harus di-gate ketat
  2. Bisa dipakai lintas produk (re-KYC, tier upgrade, external API)
  3. Dedup check butuh query lintas registrasi — lebih efisien jika terisolasi

Write path (sejak Phase 5.5, 2026-06-07)​

mobile_user
  → POST /merchant/registration (core_api)
    → CreateMerchantRegistration() [tulis ke db_kesles_merchant]
    → [best-effort] POST /internal/kyc/submissions (auth_service)
                      → INSERT INTO kyc.submissions

4. KYB — Business Verification​

Scope​

Business verification adalah verifikasi bahwa usaha merchant nyata dan layak. Cakupannya:

  • business_photo_url — foto tampak depan tempat usaha / storefront
  • business_npwp — NPWP perusahaan (untuk badan usaha)
  • bank_name, account_number, account_holder_name — rekening bank untuk settlement

Field-field ini bukan KYC. Foto usaha tidak dipakai untuk verifikasi identitas dan tidak memiliki nilai dedup cross-account seperti foto KTP/wajah.

Storage​

Database: db_kesles_merchant
Schema/Table: merchant.merchant_registration_requests
Dikelola oleh: merchant_core_api

Business verification tetap di main DB karena:

  1. Terikat dengan workflow registrasi merchant dan acquirer submission
  2. Bank account dipakai oleh payment service untuk settlement — harus di domain merchant
  3. Tidak perlu dedup atau re-use lintas produk

Kolom di merchant_registration_requests​

business_photo_url        text        -- foto tempat usaha
business_npwp             varchar     -- NPWP perusahaan
bank_name                 varchar     -- nama bank settlement
account_number            varchar     -- nomor rekening
account_holder_name       varchar     -- nama pemilik rekening

5. Mengapa business_photo_url Tidak Masuk kyc.submissions​

kyc.submissions di db_kesles_merchant_auth secara eksplisit tidak punya kolom business_photo_url. Ini keputusan desain:

  1. Bukan identity document — foto usaha tidak membuktikan siapa pemiliknya, hanya di mana usahanya
  2. Tidak ada kebutuhan dedup — tidak ada fraud signal dari foto usaha yang sama dipakai dua merchant (tidak seperti KTP/wajah)
  3. Tidak perlu re-use — untuk re-KYC atau tier upgrade, foto usaha tidak relevan; yang diulang adalah verifikasi identitas
  4. Acquirer dependency — bank acquirer butuh bukti tempat usaha sebagai bagian submission merchant, bukan sebagai data KYC

6. Field Map Lengkap — Mana ke Mana​

kyc.submissions (db_kesles_merchant_auth)​

KolomDariKeterangan
subject_typehardcoded "user"Pemilik merchant
subject_iduser_id dari JWTUUID pemilik
purposehardcoded "merchant_registration"
nikidentity.users.nikNIK 16-digit
owner_nameidentity.users.full_nameNama sesuai KTP
genderderivasi NIKmale / female
birth_datederivasi NIK digit 7–12Format date
nik_invalid_date_patternderivasi NIKtrue jika NIK valid format tapi tanggal invalid
ktp_photo_urlrequest bodyURL MinIO foto KTP
face_photo_urlrequest bodyURL MinIO foto selfie
ktp_photo_sha256upload phase (nullable sementara)Hash dedup KTP
face_photo_sha256upload phase (nullable sementara)Hash dedup selfie
ktp_nik_confidencerequest bodyOCR score 0–100
ktp_name_confidencerequest bodyOCR score 0–100
ktp_was_edited_after_prefillrequest bodyEdit flag
source_registration_idmerchantRecord.IDCross-DB link ke merchant_registration_requests.id

merchant_registration_requests (db_kesles_merchant) — business verification fields​

KolomKeterangan
ktp_photo_urlDuplikasi untuk audit trail registrasi (read-only setelah submit)
face_photo_urlIdem
business_photo_urlFoto tempat usaha — tidak masuk KYC
business_npwpNPWP perusahaan
bank_nameBank settlement
account_numberNomor rekening settlement
account_holder_nameNama pemilik rekening

7. Diagram Singkat​

mobile_user (submit registrasi)
│
├─► merchant_core_api
│     │
│     ├─► merchant.merchant_registration_requests  (db_kesles_merchant)
│     │     business_photo_url ✓
│     │     business_npwp ✓
│     │     bank_name / account_number ✓
│     │     ktp_photo_url (copy untuk audit trail)
│     │     face_photo_url (copy untuk audit trail)
│     │
│     └─► [best-effort] auth_service
│               │
│               └─► kyc.submissions  (db_kesles_merchant_auth)
│                     ktp_photo_url ✓
│                     face_photo_url ✓
│                     nik / owner_name / birth_date / gender ✓
│                     ktp_nik_confidence / ktp_name_confidence ✓
│                     ktp_was_edited_after_prefill ✓
│                     source_registration_id → link ke merchant_registration_requests

8. Referensi​

  • kyc-saas-evolution-plan.md — roadmap Phase 5–8 KYC extraction
  • merchant-registration-flow.md — flow lengkap 7-step registrasi
  • services/auth_service/internal/store/kyc.go — store layer kyc.submissions
  • merchant_core_api/internal/httpapi/merchant_handlers.go — write path Phase 5.5
  • merchant_database/db_kesles_merchant_auth/migrations/v1/001_initial_schema.sql — DDL kyc.submissions