Integration Guide

This is the start-here guide. It walks the full path — credentials, SDK, server, results, decision, testing, go-live — and links to the detailed page for each step. Read it once end to end, then follow the links as you build. The goal is simple: get your integration right the first time, without a test-and-retest cycle.

How it fits together

Kora IDV verifies a person's identity end to end and screens them for financial-crime risk in a single flow:

• Document capture & authentication — government ID front/back, MRZ, NFC chip (ePassport), tamper detection.
• Selfie + face match — matches the selfie to the ID photo.
• Liveness — active gesture challenges (configurable) to prove a live person.
• Compliance screening — sanctions, PEP, and adverse-media checks, bundled into every verification (no extra call).
• A single decision — verified / manual_review / rejected, with a transparent score breakdown.

  Your app  ──(SDK)──►  Kora IDV verification UI  ──►  Kora IDV backend  ──►  ML + Compliance
     │                                                       │
     └────────────── verification result ◄──────────────────┤
  Your backend  ◄──────────── webhook (on completion) ───────┘

The SDK renders the capture UI, drives the flow, and returns a result to your app. In parallel, your backend receives a webhook at the terminal decision. Use both: the SDK result for immediate UX, the webhook as the source of truth.

Optional add-ons: Transaction Monitoring (AML) and KYB (business verification + UBO/directors).

Your integration path

Follow these in order. Each links to its detailed guide.

Step	Do this	Guide
1	Get your API key + tenant ID, set the required headers	Authentication
2	Pick your platform and drop in the SDK	SDK guides below
3	Create verifications from your server, pass the ID to the app	Server Integration
4	Receive results asynchronously; verify the signature	Webhooks
5	Understand why a verification passes, reviews, or rejects	Scoring
6	Drive every outcome deterministically before go-live	Sandbox Testing
7	Go to production	Go-live checklist below

SDK guides: iOS · Android · React Native · Flutter · Web.

Use the latest SDK version, and keep platforms in parity

Capture and theming fixes ship in the native layer bundled with the SDK. Always install the latest published version, and keep iOS and Android on the same SDK version so behavior matches across your apps.

The result model

On completion the SDK returns a Verification with a status and a scores breakdown; your backend also receives a webhook. The statuses are:

pending · processing · verified · rejected · manual_review · expired

The score breakdown (overall, IDV components, compliance) and how they combine into the decision are documented in full on the Scoring reference — including the component weights and the auto-approve / auto-reject bands. Decision thresholds are configurable per tenant to match your risk appetite; talk to your account manager to tune them.

A few things worth knowing up front about the decision (details on the Scoring page):

• Face match and liveness carry the most weight. A dated ID photo or a poor selfie is the most common cause of a borderline result routed to manual review.
• Sanctions or high compliance risk hard-reject regardless of a high identity score.
• Eyes must be visible. Sunglasses (including tinted and mirrored) reject; clear prescription glasses may route to manual review. This is enforced server-side and applies to all SDK versions.

Branding & theming

The verification UI is themeable through the theme on your SDK configuration. primaryColor is the one brand knob — it drives the progress bar, primary buttons, brand accents, and the liveness ring. Pass/fail result colors deliberately stay green/red for clarity (overridable if you must).

Platform	Value type	Example
iOS	Color(hex:) — 3/6/8-digit	KoraTheme(primaryColor: Color(hex: "#2563EB"))
Android	Long ARGB (alpha required)	KoraTheme(primaryColor = 0xFF2563EB)
React Native	hex string (3/6/8-digit)	theme: { primaryColor: '#2563EB' }
Flutter	hex string	KoraTheme(primaryColor: '#2563EB')
Web	CSS color string	theme: { primaryColor: '#2563EB' }

Set primaryColor to your brand color in the SDK config and it applies across the whole flow. Other slots: backgroundColor, surfaceColor, textColor, errorColor, successColor, corner radius, fontFamily. See your platform's SDK guide for the exact placement.

Compliance, Transaction Monitoring & KYB

Screening (sanctions / PEP / adverse-media) is bundled into every IDV verification — no separate call. It returns a complianceScore (100 = clean), a risk band, and per-list flags, and it feeds the decision (a sanctions hit or high risk hard-rejects; PEP or medium risk routes to manual review). Standalone screening is also available for entities outside an IDV flow.

Transaction Monitoring (AML) — optional add-on. Submit transactions for real-time and batch rule evaluation; alerts raise on velocity, card-testing, dormant-reactivation, and similar scenarios.

KYB (Know Your Business) — optional add-on. Business verification via company registries, document/address validation, UBO/director capture, entity + associate screening, and a risk-scored decision.

Ask your account manager to enable Transaction Monitoring or KYB for your tenant.

Common pitfalls

This section is the difference between a one-week and a one-month integration.

• Name match. If you pass expected first/last names, they must match the scanned ID or the verification rejects on name mismatch. Test accounts registered under a placeholder name will correctly fail — use real matching names when testing the happy path.
• Sunglasses / eyewear. Eyes must be visible; sunglasses auto-reject. Tell users to remove sunglasses before the selfie.
• Keep the SDK current and platforms in parity. Update to the latest version and keep iOS and Android on the same version (for React Native: reinstall the package, then cd ios && pod install).
• Pass the theme in the config object (config.theme), not a separate prop. primaryColor drives the brand; pass/fail stay green/red.
• Webhooks fire on completion, not creation. Sessions you create but never drive to a terminal decision never emit a webhook. Always verify the signature, and remember a per-verification callbackUrl overrides the tenant webhook URL. See Webhooks.
• One tenant per environment. Don't create duplicate/parallel tenants — split traffic causes confusing "some requests work, some don't" behavior.
• Staff the manual-review queue. Borderline matches, dated ID photos, and clear-glasses cases land in review by design (safe, not a bug). Have an operator working the review queue.

Go-live checklist

1. Credentials — swap sandbox key + tenant ID for your production key + tenant ID; set environment to production. See Authentication.
2. Latest SDK — confirm every app is on the latest published SDK version, iOS and Android in parity.
3. Webhooks — confirm your production callback endpoint (or per-request callbackUrl), and verify signatures with the production webhook secret. See Webhooks.
4. Smoke test in production — a real bare-eyes capture → verified; a sunglasses capture → rejected; a name-match happy path. Confirm the webhook arrives and your handler branches correctly.
5. Manual review — confirm your operator has dashboard access and a process for the review queue.
6. Keep sandbox for ongoing regression — it never bills. See Sandbox Testing.

---

Questions during integration? Contact your Korastratum technical contact. This guide reflects the current stable SDK line — always pull the latest published SDK version.