eKYC Simulator

/ekyc/v1 · /verifications · /sessions/score · /references

Test the three eKYC flows. The result natively correlates biometrics with SIFIP telecom signals — a successful face check on a compromised line is flagged, not approved.

SIFIP differentiation

No standalone eKYC engine produces this decision: biometrics can be perfect, but if trust_signals detects a recent SIM swap, the session is downgraded to REVIEW.

Simulated scenario

Forces the engine outcome to illustrate each case.

Document

Document type

Country (ISO 3166)

Demo identity

Document front

Back (optional)

Selfie & liveness

Selfie (live face)

Camera only — file import disabled (anti-fraud)

Liveness required

Liveness mode

Trust signals (telecom correlation)

Number to correlate (E.164)

callback_url (webhook)

Request sent

POST /ekyc/v1/verifications

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

Content-Type: application/json

Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef0123456789

{
  "type": "onboarding",
  "reference_id": "client-defined-id-12345",
  "document": {
    "type": "national_id",
    "country": "MG",
    "front_image": "data:image/jpeg;base64,…"
  },
  "selfie": {
    "image": "data:image/jpeg;base64,…",
    "liveness_required": true,
    "liveness_mode": "passive"
  },
  "trust_signals": {
    "enabled": true,
    "phone_number": "+261340000000"
  },
  "callback_url": "https://client.example.com/webhooks/ekyc",
  "metadata": {
    "channel": "mobile_app",
    "session_ip": "41.0.0.0"
  }
}

Response

// Fill the form then run the simulation

Decision enumerations (§6)

APPROVEAll checks pass → allow.

REVIEWBiometrics OK but risk signal → human review / step-up.

REJECTCritical check failed → block.

Score → decision mapping (configurable)

0–40	REJECT
41–74	REVIEW
75–100	APPROVE

Reason codes (§6.3)

Code	Severity	Meaning
FACE_MATCH_OK / _FAIL	info / critical	Face concordance.
LIVENESS_OK / _FAIL	info / critical	Presence detection.
INJECTION_ATTACK_DETECTED	critical	Injected forged video stream.
DOC_AUTHENTIC / _TAMPERED	info / critical	Document authenticity.
DOC_EXPIRED	warning	Expired document.
RECENT_SIM_SWAP	warning	Correlated recent SIM swap.
LOW_LINE_TENURE	warning	Very recent line.
DATA_MISMATCH	warning	Document vs provided data mismatch.

Error handling (§9)

HTTP	Code	Case
400	INVALID_IMAGE	The selfie image is unreadable or too low resolution.
400	UNSUPPORTED_DOCUMENT	Unsupported document type or country.
401	UNAUTHORIZED	Missing, invalid or expired Bearer token.
404	REFERENCE_NOT_FOUND	Unknown reference.id.
409	IDEMPOTENCY_CONFLICT	Idempotency-Key reused with a different body.
422	LIVENESS_UNAVAILABLE	Liveness mode not supported for this channel.
429	RATE_LIMITED	Quota exceeded.
503	PROVIDER_UNAVAILABLE	Biometric engine unavailable (internal abstraction).

Verification states (§7) · Compliance & retention (§10 — Law 2014-038 / GDPR)

processing · completed · failed (technical failure ≠ business rejection).

Explicit, timestamped consent required for any reference.
Minimization: raw images deleted after processing unless a consented reference; only templates & metadata persisted.
Right to erasure: DELETE /references/{id} purges reference + derived templates.
Traceability: timestamped reasons & scores kept for audit, without raw image.