Identomat KYC Integration

Architecture

• Frontend talks only to normalized backend routes:
  • POST /api/kyc/identomat/session
  • GET /api/kyc/me
  • POST /api/webhooks/identomat
• apps/web API routes are thin proxies to svc-kyc
• svc-kyc owns:
  • provider-specific session creation
  • callback verification
  • provider status mapping
  • persistence and audit snapshots
• UI never consumes raw Identomat payload shapes

Environment Variables

Server-only:

• KYC_SERVICE_URL
• IDENTOMAT_BASE_URL
• IDENTOMAT_COMPANY_KEY
• IDENTOMAT_SECRET_KEY
• IDENTOMAT_CALLBACK_API_KEY
• IDENTOMAT_VERIFY_WEBHOOK
• DATABASE_URL
• JWT_SECRET

Production runtime expectation:

• apps/web proxies KYC requests to KYC_SERVICE_URL
• recommended live value: http://127.0.0.1:4030
• production should install a dedicated kvary-kyc.service
• repo example unit:
  • ops/systemd/kvary-kyc.service.example

Callback Flow

1. User starts verification from the frontend
2. Backend creates Identomat session and stores internal record
3. Frontend receives only safe launch data (launchUrl, verificationId, normalized status)
4. Identomat calls /api/webhooks/identomat
5. Web backend proxies raw callback to svc-kyc
6. svc-kyc verifies authenticity, stores raw payload snapshot, maps provider status, and updates normalized state idempotently

Status Mapping

Internal normalized statuses:

• NOT_STARTED
• SESSION_CREATED
• IN_PROGRESS
• PENDING_REVIEW
• APPROVED
• REJECTED
• EXPIRED

Legacy compatibility:

• APPROVED -> VERIFIED
• PENDING_REVIEW / IN_PROGRESS / SESSION_CREATED -> PENDING
• REJECTED -> REJECTED
• EXPIRED -> UNVERIFIED

Local Test Checklist

1. Set IDENTOMAT_COMPANY_KEY and related env vars for svc-kyc
2. Run migrations:
   • npm --prefix services/svc-kyc run migrate
3. Start service:
   • npm --prefix services/svc-kyc run dev
4. Start web:
   • npm --prefix apps/web run dev
5. Open profile page and click Start Verification
6. Verify:
   • session record is created
   • normalized status loads from /api/kyc/me
   • callback hits /api/webhooks/identomat
   • duplicate callback is idempotent