Docs / API and agents

Business verification (KYB)

How an organization administrator verifies the business with Didit, and how the signed webhook moves the status.

GET /v1/kyb returns whether verification is available and the latest status for the active organization. POST /v1/kyb/sessions starts a check and returns the hosted Didit link (url) the business contact opens. Didit runs the check (https://docs.didit.me/business-verification/quickstart); VendorLogic stores only the session status.

Who can use it#

Holders of the org.kyb permission: by default the Owner and Administrator of a supplier or customer organization. Without it both endpoints answer 403. An already approved business gets 409 on a new start.

Statuses#

Not Started, In Progress, In Review, Awaiting User, Resubmitted, then the final Approved, Declined or Kyc Expired (https://docs.didit.me/integration/verification-statuses). A late delivery never reopens a final status.

Webhook#

POST /v1/webhooks/didit is public; the HMAC-SHA256 of the body (X-Signature or X-Signature-V2, with X-Timestamp within five minutes) is the only credential (https://docs.didit.me/integration/webhooks). The payload is Didit's flat v3 envelope (webhook_type, session_id, status, session_kind at the top level). Only status.updated events of business sessions for a session VendorLogic started are applied; each applied change is audited (kyb.started, kyb.status_changed) with no personal data.

Setup#

Set DIDIT_API_KEY, DIDIT_WORKFLOW_ID (the Business Verification workflow) and DIDIT_WEBHOOK_SECRET on the services container, and add https://<host>/v1/webhooks/didit as a webhook destination in the Didit console. Unset, the start endpoint answers 503 naming the variables and the rest of the app is unaffected.

Making it mandatory (`KYB_REQUIRED`)#

Off by default. With KYB_REQUIRED=1 on the services container, every business (including organizations that predate onboarding) needs an Approved verification before its gated actions: a supplier cannot publish its credit application, a customer cannot submit one while signed in, and the customer cannot skip the step. The answer is the usual 409 onboarding_incomplete with missing: ["kyb"]. Declined and Kyc Expired can be started again; In Review waits for Didit. If Didit is not configured the step is "not needed" and nothing is blocked. GET /v1/kyb returns required (the switch) and, in verification, the sessionId of the latest check.