KYB Verification

KYB (Know Your Business) verification is how UrbanPay confirms the identity of a business customer. The subject of every KYB flow is a business customer: a company record owned by your client, identified by its company_name, registration_number, and country. Verification is independent of payments: no endpoint checks kyb_status, so you decide whether and when to verify a business based on your own compliance policy.

All KYB endpoints live under /api/v1/kyb and require a client Bearer token. Each endpoint checks a specific permission and the caller's account role, described in the sections below.

Verification modes

Every business customer carries a verification_mode that determines how it gets verified. Business customers support two modes (the urbanpayx_kyc mode is for individuals and is rejected here):

• urbanpayx_kyb - UrbanPay-managed KYB. UrbanPay initiates a hosted verification session, the business completes it through a verification link, and the resulting decision drives the business's kyb_status. This is the default mode when none is specified.
• external_attestation - The client attests that the business was verified elsewhere. There is no hosted session and no kyb_status lifecycle; instead the client reports an external_verification_status through the external status endpoint.

A business's mode can be switched with the Update Verification Mode endpoint as long as it is not already verified under the current mode.

Status lifecycle

For urbanpayx_kyb businesses, the kyb_status field tracks the verification lifecycle. The values are:

For external_attestation businesses, the lifecycle lives on external_verification_status instead: pending, verified, or rejected, whichever the client last reported.

Verification state does not gate anything in the API. Payment initiation works regardless of kyb_status, including rejected and on_hold. If your compliance policy requires an approved business before you move money, enforce that in your own application.

Typical flow

For a UrbanPay-managed (urbanpayx_kyb) business, the core endpoints run in this order:

1. Create Business Customer - register the business and choose its verification_mode and KYB level.
2. Initiate KYB Verification - start a hosted verification session and receive a verification_url to hand to the business. This moves kyb_status to pending.
3. Get Business KYB Status - poll the business's current kyb_status while verification is in progress.
4. Get KYB Decision - fetch and reconcile the full verification decision on demand (the fallback path when a webhook was missed), or Get KYB Verification Detail to read the latest normalized, curated verification record.

For an external_attestation business, replace steps 2 through 4 with the Update External Verification Status endpoint, which sets external_verification_status directly.

Authentication and permissions

All KYB endpoints authenticate with a client Bearer token and enforce a per-endpoint permission plus an account role check:

• Read endpoints (list businesses, get status, list KYB levels, read verification detail) require kyb.businesses.read.
• Creating and updating business customers and switching verification mode require kyb.businesses.write.
• Initiating verification and fetching the KYB decision require kyb.verification.initiate.
• Updating external verification status requires kyb.external_status.write.

Role requirements vary by endpoint: the business list, KYB status, and KYB level reads are available to OWNER, DEVELOPER, and OPERATIONS; reading verification detail and detail history is restricted to OWNER and OPERATIONS; write and verification endpoints (including the KYB decision) are restricted to OWNER and OPERATIONS; deactivating or activating a business is restricted to OWNER.

Error responses

Beyond standard authentication and authorization failures, the KYB endpoints return:

Related guides

• KYB Verification Guide - step-by-step flows for both verification modes, resubmission, and listing
• Custom Verification Workflows - build your own KYB level from modules
• KYC Verification - the equivalent endpoints for individual users
• Error Reference - error codes across the API