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.
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: 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.
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.
- After sign-up, the dashboard shows a KYC banner prompting Verify your identity.
- The merchant clicks Start verification. The portal opens a Kwik ID session (
referenceId, typepersonal_kyc, countryCM) and creates a local KYC record inINITIALIZEDstate, keyed to the user and stamped with the Kwik IDjobId. - 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.
- On submit, the widget returns
submitted. The portal shows a "submitted / checking status" state and begins polling the KYC status after about 10 seconds. - Kwik ID finishes verification asynchronously and POSTs an HMAC-signed webhook back to the platform. The result lands as
VERIFIEDorREJECTED.
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. |
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. |
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.
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-requestsalert 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 new.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 for the live collection flow, and Create and activate your account for how verification fits into activation.