Uma chamada para verificar cada vendedor. Registo, proprietários, AML — juntos.

You are integrating Didit into a marketplace that lists third-party sellers (Etsy, Shopify, Faire, Amazon Handmade, OnBuy archetype). EU Digital Services Act Article 30 and the new EU Anti-Money Laundering (AML) package require you to verify the seller (KYB) before any listing goes live, and to keep that verification fresh while they sell.

Four obligations on every seller:

  1. Pull the company's registry record (legal name, registration number, status, incorporation date) from the authoritative government source.
  2. Extract every Ultimate Beneficial Owner (UBO) — anyone owning 25% or more — and run a closed-loop KYC on each one.
  3. Screen the company AND every UBO against sanctions, Politically Exposed Persons (PEP), and adverse-media lists.
  4. Collect the corporate evidence (certificate of incorporation, tax registration, proof of business address) and watch the seller continuously for status changes, UBO turnover, AML hits, and document expiry.

Pricing (verified live):
  - KYB session (registry + company AML + documents + key-people flow): $2.00 per seller, pay-per-call
  - Linked KYC per UBO: $0.33 per UBO (ID + Passive Liveness + Face Match + IP + AML)
  - Ongoing AML monitoring: $0.07 per user per year
  - First 500 KYC verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id for KYB from the Workflow Builder. The workflow's type (KYC or KYB) drives the session shape — no explicit business flag is needed on the request.
  - A workflow_id for KYC bundled with ID + Passive Liveness + Face Match + IP + AML, used for the linked UBO sessions.

STEP 1 — Create the KYB session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your KYB workflow id>",
      "vendor_data": "<your seller id, max 256 chars>",
      "callback_url": "https://<your-app>/sellers/kyb/callback",
      "expected_country": "GB",
      "metadata": {
        "seller_id": "<your internal seller id>",
        "marketplace_segment": "handmade"
      }
    }

  Response: 201 Created with the hosted session URL. Email it to the seller or embed it in your onboarding UI. Behind the scenes, Didit runs:
    - kyb_registry — live registry lookup against the country's authoritative source
    - kyb_company_aml — sanctions / PEP / adverse media on the company
    - kyb_documents — document collection + Optical Character Recognition (OCR) (incorporation, TIN, proof of address)
    - kyb_key_people — UBO + director extraction with linked-KYC sessions

STEP 2 — Read the signed webhook on KYB completion

  Didit POSTs to your callback. KYB SESSION statuses are UPPER_SNAKE_CASE:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "session_kind": "business",
      "vendor_data": "<your seller id>",
      "status": "APPROVED",
      "decision": {
        "company": {
          "legal_name": "Maker Goods Ltd.",
          "registration_number": "1029847",
          "country_code": "GB",
          "registry_status": "ACTIVE"
        },
        "features": [
          { "node_id": "kyb_registry", "status": "APPROVED" },
          { "node_id": "kyb_company_aml", "status": "APPROVED", "total_hits": 0 },
          { "node_id": "kyb_documents", "status": "APPROVED" },
          { "node_id": "kyb_key_people", "status": "APPROVED",
            "key_people": [
              { "uuid": "<uuid>", "name": "Sara Ortega", "role": "director", "is_ubo": true, "ownership_percentage": 60, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/..." },
              { "uuid": "<uuid>", "name": "Niels Janssen", "role": "shareholder", "is_ubo": true, "ownership_percentage": 30, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/..." }
            ]
          }
        ]
      }
    }

  SESSION status enum (KYB · UPPER_SNAKE_CASE):
    NOT_STARTED | IN_PROGRESS | AWAITING_USER | APPROVED | DECLINED | IN_REVIEW | RESUBMITTED | ABANDONED | EXPIRED

  FEATURE status enum (inside decision.features[].status · UPPER_SNAKE_CASE):
    NOT_FINISHED | APPROVED | DECLINED | IN_REVIEW | RESUB_REQUESTED | AWAITING_USER

  Note: kyc_status on key_people IS Title Case ("Approved" / "Declined" / "Pending") — those are KYC sessions linked from inside the KYB feature, not KYB features themselves.

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 3 — Linked KYC on each UBO is automatic

  When the seller completes the hosted KYB flow and submits the UBO list, Didit spawns a child KYC session per UBO using the KYC workflow you configured on the KYB workflow. Each child session has its own session_id and its own hosted URL on the kyc_session_url field inside the key-people block.

  You don't need to call POST /v3/session/ again for the UBOs — they're stitched to the parent KYB session automatically. You DO need to drive each UBO through their hosted KYC URL (email it, SMS it, embed it in your seller dashboard).

  Per-UBO KYC session status is Title Case With Spaces (KYC convention):
    Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned

  Linked-KYC pricing: $0.33 per UBO.

STEP 4 — Retrieve the decision

  GET https://verification.didit.me/v3/session/{sessionId}/decision/
  Headers:
    x-api-key: <your api key>

  Returns the full KYB decision payload — company block, AML hits, document OCR, every UBO with their kyc_status and kyc_session_url. Use this for audit-pack export and for re-rendering the seller status in your admin UI.

STEP 5 — Decide

  Branch logic:
    APPROVED       → activate the seller, allow listings.
    IN_REVIEW      → keep listings off, wait for analyst webhook update.
    DECLINED       → refuse onboarding, log the decision_reason_code.
    AWAITING_USER  → nudge the seller to complete the pending step (typically UBO list submission).

  Pre-DSA Article 30: store the trader information (legal name, registration number, address, contact) in your trader-information record alongside the decision payload.

STEP 6 — Ongoing monitoring is automatic when enabled

  Enable Ongoing AML on the seller and on each UBO ($0.07/user/year). The session status updates automatically as new sanctions hits land, dissolutions are filed in the registry, or document expirations approach. Your webhook fires on every state change.

  No separate endpoint to call — the same workflow drives it.

WEBHOOK EVENT NAMES
  - status.updated — session status changed (filter on data.session_kind === "business" for KYB).
  - data.updated — session data changed (registry refresh, key-people submission, document upload, ongoing AML hit).
  - business.status.updated — the linked Business entity changed.
  - business.data.updated — Business entity data changed.

  Verify X-Signature-V2 on every payload. The webhook secret is per-environment — sandbox key is separate from production.

CONSTRAINTS
  - KYB session statuses use UPPER_SNAKE_CASE (APPROVED, IN_REVIEW, DECLINED). KYC session statuses use Title Case (Approved, In Review, Declined). They live in different APIs — don't mix them in the same code path.
  - Default record retention is 5 years post-relationship per the EU AML package; some jurisdictions go higher.
  - You cannot replace the registry lookup with a self-attested form — DSA Article 30 requires the data to come from an authoritative source.

Read the docs:
  - https://docs.didit.me/business-verification/integration-guide
  - https://docs.didit.me/business-verification/statuses
  - https://docs.didit.me/business-verification/webhooks
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 KYC verifications free every month, no credit card.