# Payrail KYC

> Hosted identity verification and AML service operated by Payrail.

> **Base URL:** `https://kyc.payrail.one`

## Overview

Payrail KYC provides a REST API for identity verification. Developers integrate via API key (`X-API-Key: ik_...`) to run a 5-step pipeline: front document OCR, back document barcode/MRZ, cross-validation, liveness detection, and face matching. Additional layers include face age estimation, velocity fraud detection, IP geolocation risk, AML/sanctions screening, PEP screening, and optional voice authentication. All decisions are deterministic — no LLMs in the decision pipeline.

The hosted API, developer portal, review dashboard, and user verification flow share one origin at `kyc.payrail.one`.

## Quick Links

- [Full API Documentation](https://kyc.payrail.one/llms-full.txt): Complete API reference in markdown
- [API Docs (Backend)](https://kyc.payrail.one/api/docs/markdown): Machine-readable API docs
- [Developer Portal](https://kyc.payrail.one/developer): Register, get API keys, manage webhooks
- [Review Dashboard](https://kyc.payrail.one/admin/verifications): Review, approve, and reject verifications
- [Documentation](https://kyc.payrail.one/docs): Interactive documentation

## SDKs

- JavaScript/TypeScript: `npm install @payrail/kyc-sdk`
- React Component: `npm install @payrail/kyc-react`
- Python: `pip install payrail-kyc`

## Verification Flow

```
POST /api/verify/initialize          → Create session
POST /api/verify/:id/front-document  → OCR extraction
POST /api/verify/:id/back-document   → Barcode/MRZ + cross-validation
POST /api/verify/:id/live-capture    → Liveness + face match
POST /api/verify/:id/voice-challenge → Generate voice challenge digits (optional)
POST /api/verify/:id/voice-capture   → Speaker verification (optional)
GET  /api/verify/:id/status          → Poll for final result
GET  /api/verify/:id/selfie          → Live-capture selfie URL (300s signed, owner-scoped)
```

All POST endpoints accept an `Idempotency-Key` header for safe retry on network failures. Same key replays the original response within 24 hours. See llms-full.txt § Idempotency.

## Verification Modes

| Mode | Steps | Use Case |
|------|-------|----------|
| `full` (default) | Front → Back → CrossVal → Live → FaceMatch | Full identity verification |
| `document_only` | Front → Back → CrossVal | Document checks, no biometric |
| `identity` | Front → Live → FaceMatch | Quick identity check, no back doc |
| `age_only` | Front (DOB check) | Age-gated content (18+/21+) |

Passports are single-sided — when detected, back-document and cross-validation steps are automatically skipped (even in `full` and `document_only` modes). The front-document response includes `requires_back: false`.

## Verifiable Credentials (W3C JWT-VC)

Issue W3C Verifiable Credentials for completed verifications. Credentials are signed with Ed25519 (EdDSA) and can be independently verified by any relying party using the issuer's DID document — no API key needed for verification.

```
GET  /api/verify/:id/credential       → Issue JWT-VC (requires API key, vc_enabled)
POST /api/verify/:id/credential/send  → Email credential with QR code (requires API key, vc_enabled)
GET  /api/credentials/:jti/status     → Check revocation status (public, no auth)
POST /api/credentials/:jti/revoke     → Revoke credential (requires API key)
GET  /.well-known/did.json               → Issuer DID document (public)
```

**Client-side verification:** Resolve `did:web:kyc.payrail.one` → fetch `https://kyc.payrail.one/.well-known/did.json` → extract the Ed25519 public key → verify the JWT signature.

## Compliance Orchestration Engine

Developer-configurable rule engine. Rules auto-select verification mode, gates, and post-verification actions.

All endpoints accept **either** `X-API-Key` (developer automation/SDK) **or** an organization-admin reviewer session cookie (Admin Dashboard UI at `/admin/verifications`). Regular reviewers and platform admins are rejected.

```
POST   /api/compliance/rulesets           → Create ruleset
GET    /api/compliance/rulesets           → List rulesets
GET    /api/compliance/rulesets/:id       → Get ruleset with rules
PUT    /api/compliance/rulesets/:id       → Update ruleset
DELETE /api/compliance/rulesets/:id       → Delete ruleset + rules (CASCADE)
POST   /api/compliance/rulesets/:id/rules → Add rule to ruleset
PUT    /api/compliance/rules/:id          → Update rule
DELETE /api/compliance/rules/:id          → Delete rule
POST   /api/compliance/evaluate           → Dry-run: test context against rules
```

Rules auto-apply at `POST /api/verify/initialize`. Response includes `compliance_applied` when rules match.

## AML / Sanctions & PEP Screening

Automatic screening after face matching (Gate 6). Configurable via `AML_PROVIDER` env var (`opensanctions`, `pep`, `offline`, or comma-separated for multiple). PEP (Politically Exposed Persons) screens against heads of state, senior officials, and associates. Per-developer opt-out via `aml_enabled: false`. Results include `risk_level`, `match_count`, `matches[]` with `listed_name`, `score`, and `list_source`.

## Face Age Estimation

Cross-checks apparent face age (from both document photo and live capture) against declared DOB. Flags age discrepancies as a fraud signal. Appears in `age_estimation` object in live-capture and status responses.

## Velocity / Fraud Detection

Analyzes verification velocity during live capture: rapid IP reuse, bot-like step timing, burst activity, multi-IP abuse. Flags route sessions to manual review. Contributes to composite risk score. `velocity_analysis` object in responses with `flags[]` and `score`.

## IP Geolocation Risk

Detects country mismatches between document nationality and client IP, Tor exit nodes, datacenter/VPN IPs, and high-risk jurisdictions. `ip_geolocation` object in responses with `geo_risk_flags[]`.

## Voice Authentication (Optional)

Speaker verification step after face matching. Developer opt-in via `voice_auth_enabled` toggle. Random 6-digit challenge → user speaks digits → ASR transcription verification + 512D speaker embedding comparison (cosine similarity, fixed threshold). Anti-spoofing by design.

```
PUT  /api/developer/settings/voice-auth     → Enable/disable voice auth
POST /api/verify/:id/voice-challenge     → Generate 6 random digits (120s expiry)
POST /api/verify/:id/voice-capture       → Submit audio, verify digits + speaker match
```

## Identity Vault

Tokenized identity storage. Store verified identity data encrypted at rest (AES-256-GCM), reference it via opaque tokens.

```
POST /api/vault/store             → Store verified identity, get vault token (requires API key, vault_enabled)
GET  /api/vault/:token            → Retrieve full identity data (requires API key)
GET  /api/vault/:token/attributes/:attr → Get single attribute e.g. age_over_21 (requires API key)
DELETE /api/vault/:token          → GDPR hard delete (requires API key)
GET  /api/vault                   → List vault tokens, paginated (requires API key)
POST /api/vault/:token/share      → Create time-limited share link (requires API key)
GET  /api/vault/share/:shareToken → Access shared attributes (public, no auth)
```

## Integration Options

1. **Redirect** — initialize server-side (`POST /api/verify/initialize`), redirect user to the returned `verification_url` (session-token-based, no API key in browser). Append `&redirect_url=https://yourapp.com/done` to auto-redirect the user back with `verification_id`, `status`, and `user_id` query params. Works on both desktop and mobile devices. `redirect_url` must use `http:` or `https:` protocol.
2. **Iframe** — embed the hosted page with `allow="camera; microphone"`
3. **SDK** — `@payrail/kyc-sdk` PayrailKycEmbed (modal/inline) or `@payrail/kyc-react` React component

## Base URLs

- API and hosted frontend: `https://kyc.payrail.one`

## Version

v1.8.52 — April 2026