KYC and KYB

Identity verification is required for many payment and OTC flows. The API chooses KYC vs KYB from the active team and role — you do not pick a mode in the request body.

Prerequisites#

  • Session from OTP onboarding for the profile you want to verify
  • For business admin on a business team: KYB applies
  • Otherwise: individual KYC applies

Check current status before creating a new verification attempt.

1. Check verification status#

curl -sS https://api-stg.vudy.app/v1/kyc/status \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"

If data.isVerified is true, continue to the gated workflow. Otherwise create a verification session.

2. Create a verification session#

Auth: API key + session. Context is the login profile/team.

curl -sS https://api-stg.vudy.app/v1/kyc/session \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@example.com"}'
const { data } = await fetch("https://api-stg.vudy.app/v1/kyc/session", {
	method: "POST",
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		email: "alex@example.com",
		metadata: { source: "integration" }, // optional
	}),
}).then((r) => r.json());

// data: { sessionUrl, verificationId, status }
// Open sessionUrl for the hosted verification UI

Do not send x-profile-id expecting a different actor. The selected profile and team come from the session.

3. Open the hosted flow and poll status#

curl -sS https://api-stg.vudy.app/v1/kyc/status \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"
const { data } = await fetch("https://api-stg.vudy.app/v1/kyc/status", {
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
	},
}).then((r) => r.json());
// { isVerified, status, verification }

Open sessionUrl for the user, then poll. isVerified is true when the applicable user KYC or team KYB is approved.

Status transitions#

Typical values:

none / not_started → in_progress → in_review → terminal approved | declined | expired | abandoned | kyc_expired

Poll until a terminal state before starting gated payments or OTC create.

List prior user verifications#

curl -sS https://api-stg.vudy.app/v1/kyc/verifications \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT"

This lists user KYC records. For business-admin KYB, rely on GET /v1/kyc/status.

Compliance fee (when gated)#

Some OTC and channel flows require a paid yearly compliance fee. Check OTC gating (missing.complianceFee). To pay:

curl -sS https://api-stg.vudy.app/v1/compliance/checkout \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{"successUrl":"https://your.app/ok","cancelUrl":"https://your.app/cancel"}'

Next steps#