# Kwik ID

Kwik ID is Kwik Nkap's own identity-verification product. It verifies a real person from a government ID and a live selfie, and returns the result through an HMAC-signed webhook. Kwik Nkap consumes Kwik ID exactly like any external customer would, and uses it to power merchant [identity verification (KYC)](/en/products/kyc).

:::note
Kwik ID is the identity product Kwik Nkap uses internally to verify merchants today. It is consumed through Kwik Nkap's own dashboard and internal services, not through the public developer API (`/v1`, `X-API-Key`). There is no public, key-authenticated endpoint to open or query a Kwik ID session. The only internet-reachable Kwik ID surface is the result webhook, which is a provider callback secured by HMAC, not a developer endpoint.
:::

## What Kwik ID is

Kwik ID is a separate product from the Payments API. Where Payments moves Mobile Money, Kwik ID answers a single question: is this a real, identified person holding a valid document?

It is built to be consumed the way a clean third-party identity service is consumed, with three moving parts:

| Part | What it does |
| --- | --- |
| API key | Authenticates the caller and opens a verification session. |
| Hosted widget | A drop-in UI that captures the ID and selfie and handles liveness and image quality. |
| Signed webhook | Delivers the final result, with extracted identity data, to a callback URL. The body is HMAC-signed so the receiver can verify authenticity. |

Because Kwik ID owns the hosted capture UI, the consuming application never builds a camera form, never handles raw document images during capture, and never implements liveness detection. It opens a session, embeds the widget, and waits for the webhook.

## What Kwik ID verifies

A single verification covers both the document and the person:

- **ID document, front and back.** A government-issued identity document is photographed on both sides inside the widget.
- **Selfie and liveness.** A live selfie is captured and checked for liveness, so a static photo of someone else does not pass.

On success, Kwik ID extracts and returns structured data from the document: the holder's **name**, **document number**, and **document type**.

## The verification flow, end to end

A verification moves through four steps, from opening a session to receiving a signed result.

1. **Open a session.** The consumer opens a Kwik ID session with a `referenceId`, a verification type (for personal identity, `personal_kyc`), and a country (`CM` for Cameroon). Kwik ID returns a `jobId` and a client token. At this point the verification is `INITIALIZED`.
2. **Capture in the hosted widget.** The widget opens with the returned client token. Inside it, the user photographs their **ID front and back** and takes a **selfie**. The widget handles liveness and image quality.
3. **Submit.** On submit, the widget returns `submitted`. The verification moves to `PENDING` while Kwik ID processes it, and the consumer can poll status while waiting.
4. **Receive the signed webhook.** When verification finishes, Kwik ID POSTs an HMAC-signed webhook to the consumer's callback URL. A `verification.completed` event carries `VERIFIED` plus the extracted name, document number, and document type. A `verification.rejected` or `verification.failed` event carries `REJECTED` with a reason.

:::info
The result is asynchronous. The session call returns quickly with a `jobId` and token, but the verified outcome arrives later by webhook, not in the original response. Build for the webhook as the source of truth and treat polling as a convenience.
:::

### The result webhook and its signature

Kwik ID signs every webhook delivery. The receiver verifies it before trusting the body.

- The HMAC signature is sent in the **`X-Kwik-Signature`** header.
- The receiver recomputes an HMAC over the raw request body using its shared Kwik ID webhook secret and compares the result to `X-Kwik-Signature`.
- A signature that does not match is rejected. This is what stops a forged result from marking someone as verified.

```http
POST /your/callback/url HTTP/1.1
Content-Type: application/json
X-Kwik-Signature: <hmac-hex-digest>

{
  "event": "verification.completed",
  "jobId": "<job-id>",
  "status": "VERIFIED",
  "data": {
    "name": "<extracted name>",
    "document_number": "<extracted document number>",
    "document_type": "<extracted document type>"
  }
}
```

:::warning
Always verify `X-Kwik-Signature` against the raw, unparsed request body before acting on a webhook. Reformatting or re-serializing the body before verifying will break the comparison. A delivery whose signature does not match should never advance a verification to `VERIFIED`.
:::

## Statuses

A Kwik ID verification moves through these states.

| Status | Meaning |
| --- | --- |
| `INITIALIZED` | A session was opened, but the user has not finished capture yet. |
| `PENDING` | Capture was submitted and Kwik ID is verifying. |
| `VERIFIED` | Verification succeeded. The extracted name, document number, and document type are available on the result. |
| `REJECTED` | Verification failed or was rejected, with a reason attached. |

:::note
A verification that has already reached `VERIFIED` is never silently downgraded by a later failed or rejected callback. A new session cannot be opened over a verification that is already `VERIFIED` or `PENDING`.
:::

## How Kwik Nkap uses Kwik ID

Kwik Nkap is a Kwik ID customer. Merchant personal verification on the platform is powered by Kwik ID, consumed through the same three parts described above: a key opens the session, the hosted widget captures the ID and selfie, and the `X-Kwik-Signature` webhook delivers the result.

When a merchant starts verification in the dashboard, the platform opens a Kwik ID session, embeds the widget, and stores the returned `jobId`. When the signed webhook arrives, the platform matches it back to the merchant by `jobId`, records the outcome, and re-hosts the captured images privately. A `VERIFIED` result is what clears the merchant's KYC gate and unlocks live transacting.

For the full merchant-facing flow, including personal and business KYC, document storage, and admin review, see [Identity & KYC](/en/products/kyc).

:::tip
Kwik ID powers the personal identity check, but it is not the whole KYC story. Business verification and the admin review queue are Kwik Nkap features built around Kwik ID. The [Identity & KYC](/en/products/kyc) page covers how they fit together.
:::

## Replacing the legacy Smile ID path

Kwik ID replaces the legacy **Smile ID** path that Kwik Nkap previously used for personal verification. Both paths can produce a verified personal identity, but Kwik ID is the one the platform is standardizing on. Smile ID remains only for parity and for resolving older records, and those legacy records are settled through the admin review queue rather than an automated provider callback. New personal verifications run through Kwik ID.