API Reference

KYC Verification

KYC (Know Your Customer) verification confirms the identity of an individual User belonging to your client account. Verification is not mandatory to use UrbanpayX, but a user's verification state gates payment eligibility: a user must be verified before payments can be initiated on their behalf.

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.

ModeWhat it requires
urbanpayx_kycUrbanpayX 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_attestationYou 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 and payment eligibility

For users in urbanpayx_kyc mode, kyc_status moves through these values:

kyc_statusMeaningPayments allowed
noneNo verification has been started.No (KYC_REQUIRED)
pendingVerification was initiated and is awaiting a result.No (KYC_PENDING)
approvedThe user passed verification.Yes
rejectedThe user failed verification.No (KYC_REQUIRED)
on_holdA previously approved user was placed on hold pending review.No (KYC_ON_HOLD)

For users in external_attestation mode, eligibility is driven by external_verification_status:

external_verification_statusPayments allowed
pendingNo (EXTERNAL_VERIFICATION_PENDING)
verifiedYes
rejectedNo (EXTERNAL_VERIFICATION_REJECTED)

Only approved (UrbanpayX KYC) or verified (external attestation) makes a user eligible for payments. Any other state blocks payment initiation with the error code shown above.

Typical flow

For a user verified by UrbanpayX (urbanpayx_kyc mode):

  1. Initiate KYC Verification - registers the user (creating them if they do not yet exist) and returns a verification_url to send to the user. Their kyc_status becomes pending.
  2. The user completes the hosted verification flow at that link.
  3. 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 the kyc.status_changed webhook, so polling is optional.
  4. Get KYC Decision - fetch the full verification decision and reconcile kyc_status on demand. Use this as a fallback when a webhook is missed.
  5. 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:

OperationPermissionAllowed roles
Create / update / activate users, change verification modeKYC_USERS_WRITEOWNER, OPERATIONS
Initiate KYC, fetch decisionKYC_VERIFICATION_INITIATEOWNER, OPERATIONS
Update external verification statusKYC_EXTERNAL_STATUS_WRITEOWNER, OPERATIONS
Read status, lists, and levelsKYC_USERS_READOWNER, DEVELOPER, OPERATIONS
Read verification detail and detail historyKYC_USERS_READOWNER, OPERATIONS

Related guides

Updated 26 days ago

Updated 26 days ago