Initiates KYB (Know Your Business) verification for a business customer. Identify the business by its registration_number and country; if no matching business exists under your client it is created automatically with the catalog default KYB level, then an UrbanpayX-managed hosted verification session is started. The response returns the business id, its current kyb_status, and a verification_url to send the business through. To control the KYB level (rather than using the default), call POST /api/v1/kyb/businesses first with an explicit kyb_level.

Authentication & access

• Requires a Bearer token (client API credential or an authenticated client user session).
• Permission: kyb.verification.initiate.
• Client users must hold the owner or operations role. API credentials must carry the permission above.
• The client must have KYB link generation enabled. If kyb_links_enabled is disabled for your client, the request is rejected with 403.

Request body

• company_name (string, required) - 1 to 255 characters.
• registration_number (string, required) - 1 to 128 characters. Combined with country, this identifies the business under your client.
• country (string, required) - exactly 3 characters. Normalized to uppercase server-side.
• legal_address (string, optional) - up to 512 characters.
• tax_id (string, optional) - up to 128 characters.
• contact_email (string, optional) - must be a valid email address.
• callback_url (string, optional) - HTTPS URL the business is redirected to after completing verification, up to 1024 characters. Falls back to your client's default verification callback URL when omitted. A non-HTTPS or malformed URL is rejected with 422.

Behavior

• The business is matched by client_id + registration_number + country. A new business is created on the fly if none matches, using the catalog default KYB level.
• If the matched business is configured for external_attestation verification mode, the request is rejected; switch it to urbanpayx_kyb before initiating KYB.
• If the business is already in a terminal or in-progress state, no new session is started and the current state is returned instead:
  • approved - returns verification_url: null with a message that the business is already verified.
  • rejected - returns verification_url: null and a message to contact support.
  • on_hold - returns verification_url: null and a message that KYB is temporarily on hold.
• For a business already pending with a still-valid verification link, the existing link is reused (idempotent retry) rather than generating a new one.
• The verification session is provisioned automatically from the resolved KYB level; the response shape is identical either way.

Responses

• 200 OK - returns a KYBVerificationResponse:
  • business_customer_id (string) - the business id.
  • kyb_status (string) - one of none, pending, approved, rejected, on_hold.
  • verification_url (string or null) - the hosted link for the business to complete verification; null when no new session applies (e.g. already approved, rejected, or on hold).
  • message (string) - human-readable status of the request.

Error responses

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.