# Identity & KYC

KYC (Know Your Customer) is how a Kwik Nkap merchant proves who they are and that their company is real before they can transact. Personal verification runs through Kwik ID, Kwik Nkap's own identity product, with a legacy Smile ID path still in place. Verification is a gate: until it reaches `VERIFIED`, you stay in sandbox and cannot move real money.

:::note
KYC is a dashboard and internal flow today. It is not part of the public developer API (`/v1`, `X-API-Key`), which only exposes core Payments (create, list, status). There is no public endpoint to start, query, or approve a verification with an API key. Exposing identity status on the public API is planned. The one internet-reachable KYC endpoint, the Kwik ID webhook, is a provider callback secured by HMAC, not a developer endpoint.
:::

## Why KYC matters

Sandbox keys (`kn_sk_test_...`) need no verification. You can build and test a full collection flow against simulated outcomes immediately. But the moment you want to move real money, KYC is the gate.

A `VERIFIED` identity is what unlocks LIVE keys (`kn_sk_live_...`) and real money movement: real Mobile Money collections, real settlement to your balance, and disbursements. An unverified merchant stays boxed into sandbox. This is the same activation gate described in [Create and activate your account](/en/getting-started): verification clears the KYC banner in the dashboard and lets you proceed with merchant onboarding and transacting.

There are two layers of verification:

| Layer | What it proves | Record |
| --- | --- | --- |
| Personal KYC | The individual behind the account is a real, identified person. | One personal KYC record per user. |
| Business KYC | The company is a real, registered entity. | A separate `BusinessKYC` record per business. |

## Kwik ID and the legacy Smile ID path

Personal verification is powered by **Kwik ID**, Kwik Nkap's own standalone identity product. The platform consumes Kwik ID exactly like any external customer would: an API key, a hosted verification widget, and an HMAC-signed webhook for the result. This is the path the platform is standardizing on.

An older **Smile ID** path still exists for parity, but the platform is migrating to Kwik ID. Records that came in through Smile ID or direct submission are resolved through the admin review queue rather than an automated provider callback.

:::info
Because Kwik ID is consumed the same way an external developer would consume it (key plus hosted widget plus signed webhook), the personal KYC flow looks like a clean third-party identity integration from the inside.
:::

## Personal verification, end to end

The merchant-facing flow lives entirely in the client portal.

1. After sign-up, the dashboard shows a KYC banner prompting **Verify your identity**.
2. The merchant clicks **Start verification**. The portal opens a Kwik ID session (`referenceId`, type `personal_kyc`, country `CM`) and creates a local KYC record in `INITIALIZED` state, keyed to the user and stamped with the Kwik ID `jobId`.
3. The Kwik ID hosted widget opens with the returned client token. Inside the widget, the merchant captures their **ID front and back** and a **selfie**.
4. On submit, the widget returns `submitted`. The portal shows a "submitted / checking status" state and begins polling the KYC status after about 10 seconds.
5. Kwik ID finishes verification asynchronously and POSTs an HMAC-signed webhook back to the platform. The result lands as `VERIFIED` or `REJECTED`.

:::note
You cannot open a new verification session over a KYC record that is already `VERIFIED` or `PENDING`. The portal returns a `409` conflict instead. There is exactly one personal KYC record per user.
:::

### Capturing documents

All capture happens inside the Kwik ID hosted widget, not in a Kwik Nkap form. The merchant photographs the front and back of a government ID and takes a live selfie. The widget handles liveness and image quality; Kwik Nkap only receives the result and the extracted data.

## Statuses and what they mean

A personal KYC record moves through four states.

| Status | Meaning |
| --- | --- |
| `INITIALIZED` | A session was opened and the local record was created, but the merchant has not finished capture yet. |
| `PENDING` | Capture was submitted and Kwik ID is verifying. A new session cannot be started over this state. |
| `VERIFIED` | Verification succeeded. Extracted name, document number, and document type are stored. This unlocks live transacting. |
| `REJECTED` | Verification failed or was rejected, with a reason attached. The merchant is notified and can retry. |

:::caution
An already-`VERIFIED` record is never downgraded. A later failed or rejected callback will not pull a verified merchant back out of verification.
:::

On a successful `verification.completed` result, the record is set to `VERIFIED` and the extracted identity fields (name, document number, document type) are written. On `verification.rejected` or `verification.failed`, the record is set to `REJECTED` with a reason, a Slack `#kyc-requests` alert fires, and the merchant is notified.

## How documents are stored privately

Kwik Nkap does not leave your ID and selfie sitting on the provider. When a result comes back, the platform downloads the ID and selfie images from Kwik ID and **re-hosts them privately** through its own media service. This happens on both outcomes: even a `REJECTED` record has its images re-hosted privately, so there is an audit trail.

The key property is **private** storage. Unlike, say, a payment-link cover photo, KYC documents are not public assets. They are accessible only to the internal review and compliance path, never served on a public URL.

## Business verification

Business KYC is a separate record and a separate flow from personal KYC. It proves the company is a registered entity.

To submit business KYC, the merchant provides:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Company name | string | Yes | The registered company name. |
| Registration number | string | Yes | The company's official registration number. |
| Documents | file upload | Yes | Registration documents, uploaded one document type at a time. |

:::info
Before business KYC can be submitted, the `Business` must already have an address and a business type set. The submission creates a `BusinessKYC` record in `PENDING`.
:::

After submission, the merchant uploads the supporting documents (one document type per upload). Like personal KYC images, these documents are stored **privately** through the media service. A business KYC record waits in `PENDING` for an admin to review the company details and the uploaded documents.

## Admin review and approval

Business KYC, and any personal record that did not resolve automatically (for example Smile ID or direct submissions), is resolved by a human in the admin portal.

- Admins open a **review queue** of unverified records, both personal and business, with SLA aging so older submissions surface first.
- An admin inspects the record and the privately stored documents.
- The admin **approves** or **rejects** the record. A rejection requires a reason.

This admin path is what resolves the legacy and edge-case submissions and lets an operator override results where the automated provider flow is not enough.

:::note
The Kwik ID webhook resolves most personal verifications automatically. The admin queue exists for business KYC, for the legacy Smile ID path, and for edge cases the automated flow cannot settle on its own.
:::

## Notifications

Verification outcomes are surfaced in two directions:

- **To the merchant**: the dashboard banner reflects the current state (verify, in review, rejected), and the merchant is notified when a record is rejected so they can retry.
- **To the team**: a rejected or failed verification fires a Slack `#kyc-requests` alert so the compliance team can follow up.

## Money movement

None. KYC moves no money. It is purely a compliance gate. What it controls is **eligibility**: a record must reach `VERIFIED` before a merchant is allowed to onboard and run real collections or disbursements. It unlocks the ability to transact rather than moving any funds itself.

## Where this lives

Identity verification is a dashboard product. Start verification from the KYC banner at [app.kwiknkap.com](https://app.kwiknkap.com); personal capture happens in the Kwik ID hosted widget, and business documents are uploaded in the dashboard.

Once you are `VERIFIED` and holding live keys, the thing you actually build with is the public Payments API. See [Payments & Collections](/en/payments/overview) for the live collection flow, and [Create and activate your account](/en/getting-started) for how verification fits into activation.