KYB Verification

KYB (Know Your Business) verification is how UrbanpayX confirms that a business customer is allowed to send payments. 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. A business customer must reach a verified state before UrbanpayX will initiate payments on its behalf.

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 - UrbanpayX-managed KYB. UrbanpayX initiates a hosted verification session with its KYB provider, the business completes it through a verification link, and the provider's 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, eligibility is driven by external_verification_status instead:

Only approved (for urbanpayx_kyb) or verified (for external_attestation) makes a business eligible to initiate payments. Any other state blocks payment initiation with the error code shown above.

Typical flow

For a UrbanpayX-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 provider's full 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: