KYC (Know Your Customer) verification confirms the identity of an individual User belonging to your client account. Verification is independent of payments: no endpoint checks kyc_status, so you decide whether and when to verify a user based on your own compliance policy.
All endpoints in this section use the /api/v1/kyc base path.
Verification modes
Each user has a verification_mode that determines how their identity is verified. The default is set at the client level and can be overridden per user with the Update User Verification Mode endpoint.
| Mode | What it requires |
|---|---|
urbanpayx_kyc | UrbanpayX runs the identity check. You call Initiate KYC Verification to register the user and receive a verification_url. The user completes verification through that link, and the result is delivered asynchronously. |
external_attestation | You verify the user with your own provider and report the outcome to UrbanpayX with the Update External Verification Status endpoint. UrbanpayX stores the status, provider name, and reference but does not run any check itself. |
A user can only be acted on through the endpoint that matches their mode. Initiating UrbanpayX KYC for an external_attestation user, or submitting an external status for an urbanpayx_kyc user, returns 400 Bad Request.
Status lifecycle
For users in urbanpayx_kyc mode, kyc_status moves through these values:
kyc_status | Meaning |
|---|---|
none | No verification has been started. |
pending | Verification was initiated and is awaiting a result. |
approved | The user passed verification. |
rejected | The user failed verification. |
on_hold | A previously approved user was placed on hold pending review. |
For users in external_attestation mode, the lifecycle lives on external_verification_status instead: pending, verified, or rejected, whichever you last reported.
Verification state is informational as far as the API is concerned. Payment link generation, contract sending, and every other endpoint work regardless of kyc_status, including rejected and on_hold. If your compliance policy requires an approved user before you take money, enforce that in your own application before calling the payment endpoint.
Typical flow
For a user verified by UrbanpayX (urbanpayx_kyc mode):
- Initiate KYC Verification - registers the user (creating them if they do not yet exist) and returns a
verification_urlto send to the user. Theirkyc_statusbecomespending. - The user completes the hosted verification flow at that link.
- Get User KYC Status - poll a user's current
kyc_status,verification_mode, and latest verification link at any time. Results are also pushed to you asynchronously via thekyc.status_changedwebhook, so polling is optional. - Get KYC Decision - fetch the full verification decision and reconcile
kyc_statuson demand. Use this as a fallback when a webhook is missed. - Get Verification Detail - read the most recent curated verification record (extracted document and check data) for the user.
For a user verified externally (external_attestation mode), replace step 1 with Update External Verification Status to report the result, then read state with Get User KYC Status.
To verify users in bulk or browse all users at once, use the bulk and list endpoints in this section.
Authentication
All KYC endpoints require a client Bearer token. Each endpoint also enforces a permission and an account role:
| Operation | Permission | Allowed roles |
|---|---|---|
| Create / update / activate users, change verification mode | KYC_USERS_WRITE | OWNER, OPERATIONS |
| Initiate KYC, fetch decision | KYC_VERIFICATION_INITIATE | OWNER, OPERATIONS |
| Update external verification status | KYC_EXTERNAL_STATUS_WRITE | OWNER, OPERATIONS |
| Read status, lists, and levels | KYC_USERS_READ | OWNER, DEVELOPER, OPERATIONS |
| Read verification detail and detail history | KYC_USERS_READ | OWNER, OPERATIONS |
Related guides
- KYC Verification Guide - Detailed flows for both verification modes, bulk operations, and status transitions
- Core Concepts - How users and verification fit in the domain model
- Error Reference - KYC-related errors
- Pagination - User list pagination (default: 20, max: 200)