> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Integració KYB amb Didit: arquitectura i patrons

> Integració KYB amb Didit: arquitectura, sessions, webhooks i decisions. Des de $2.00 per verificació, segons país i nivell.



Prompt d'integració KYB
        Copia el prompt al porta-retalls



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Enganxa a

Aquesta guia complementa la [guia d'inici ràpid](https://docs.didit.me/ca/business-verification/quickstart.md). Cobreix l'arquitectura, totes les decisions d'integració i els patrons operatius que fan que la KYB sigui fiable en producció.## Arquitectura```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## AutenticacióTotes les sol·licituds requereixen la capçalera `x-api-key` amb la clau d'API de la teva aplicació. Consulta [autenticació de l'API](https://docs.didit.me/ca/getting-started/api-authentication.md) per a la rotació de claus, la separació d'entorns i els àmbits.## Creació de sessióUn únic endpoint: `POST /v3/session/`. El tipus de flux determina si la sessió és KYC o KYB, de manera que no cal cap marca explícita de «business».**Camps recomanats en la creació:**| Camp | Finalitat |
| - | - |
| `workflow_id` | Obligatori: fa referència al teu flux de KYB. |
| `vendor_data` | El teu identificador de l'empresa. Vincula la sessió a una [entitat d'empresa](https://docs.didit.me/ca/entities/businesses/overview.md). |
| `callback_url` | Opcional: on redirigir l'usuari en acabar. |
| `expected_details` | Opcional: `{ company_name, registry_country, registration_number }`. Precompleta la cerca al registre mercantil: el país de constitució es preselecciona i es bloqueja (`registry_country` com `XX`, o `XX-YY` per a registres a nivell d'estat, p. ex. `US-CA`), els camps de nom d'empresa i número de registre s'omplen prèviament, i la cerca amb aquestes dades s'executa automàticament, combinant els dos identificadors quan tots dos hi són presents. Només és un precompletat: les discrepàncies no generen advertències. |
| `metadata` | Opcional: JSON adjunt a la sessió. |Esquema complet: [crear sessió](https://docs.didit.me/ca/sessions-api/create-session.md).## Enviament de l'enllaç allotjatLa `url` de la resposta és un enllaç de verificació allotjat. Opcions per enviar-lo:- Enviar-lo per correu electrònic des de la teva pròpia plataforma.
- Incrustar-lo a la teva interfície d'alta com a enllaç.
- Obrir-lo en un webview integrat a l'app (iOS / Android / React Native).Pots **personalitzar** l'experiència allotjada (logotip, color, domini, plantilles de correu electrònic) amb [Marca blanca](https://docs.didit.me/ca/console/white-label.md).## Polling vs webhooksEls webhooks són el patró recomanat. Didit envia per POST els esdeveniments de finalització al teu endpoint subscrit tan bon punt acaba el processament.El polling és compatible per al desenvolupament o quan el teu endpoint de webhook no és accessible:* Fes polling a `GET /v3/session/{id}/decision/` amb backoff exponencial (cada 10 s inicialment, fins a 60 s).
* Atura el polling quan `status` sigui un de `"Approved"`, `"Declined"` o `"In Review"`.> [!WARNING]
>
> El polling a alta freqüència pot superar els [límits de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md). En producció, prioritza sempre els webhooks.## Gestió de webhooksSubscriu-te als esdeveniments que t'interessen: els mateixos esdeveniments cobreixen KYC i KYB, amb `session_kind: "business"` dins del payload per identificar els esdeveniments de sessions d'empresa:- `status.updated`: l'estat de la sessió ha canviat. Filtra per `session_kind === "business"` per a les sessions KYB.
- `data.updated`: un revisor ha editat les dades del registre o les persones clau a la consola, o el registre ha informat d'un canvi. No s'envia quan el sol·licitant puja un document o envia les persones clau: en aquest cas, segueix `status.updated`. S'aplica el mateix filtre de `session_kind`.
- `business.status.updated` / `business.data.updated`: l'[entitat d'empresa](https://docs.didit.me/ca/entities/businesses/overview.md) vinculada ha canviat.Catàleg complet d'esdeveniments: [webhooks de KYB](https://docs.didit.me/ca/business-verification/webhooks.md). Verificació de la signatura i semàntica de reintents: [referència de webhooks](https://docs.didit.me/ca/integration/webhooks.md).## Gestió de decisions```typescript theme={null}
switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}
```Consulta [estats de KYB](https://docs.didit.me/ca/business-verification/statuses.md) per a la màquina d'estats completa, i [advertències de KYB](https://docs.didit.me/ca/business-verification/warnings.md) per a les etiquetes que expliquen una decisió.## Flux de resubmissióQuan una sessió de Verificació d'empreses (KYB) passa a `Resubmitted` (o una funcionalitat es marca per a reenviament), l'empresa ha de pujar dades corregides o addicionals.Pots:- **Tornar a enviar** la mateixa `url`: el flux allotjat continua des del punt on cal el reenviament.
- **Reemetre un enllaç invalidat de persona clau**: una persona clau la sessió KYC filla de la qual s'ha eliminat o ha caducat abans que la persona l'iniciés rep una sessió nova amb [Regenerar sessió KYC de persones clau](https://docs.didit.me/ca/sessions-api/regenerate-kyb-party.md).
- **Obrir un [cas](https://docs.didit.me/ca/transaction-monitoring/cases.md)** a la Business Console per fer el seguiment de l'intercanvi intern.## Executa els passos des de la teva pròpia interfície d'usuariEls passos de documents i persones clau també es poden executar des del teu servidor amb la teva clau d'API, de manera que tu conserves la interfície d'usuari i Didit manté la verificació i la decisió.
Cada crida està associada a la sessió KYB i necessita el permís `write:businesses` (per llegir les parts extretes també s'accepta `read:businesses` o `read:sessions`), i executa les mateixes comprovacions, facturació i avançament del pas que la pàgina allotjada.1) [Puja els documents corporatius](https://docs.didit.me/ca/sessions-api/kyb-upload-documents.md) mentre la sessió es troba al pas de documents KYB.
2) [Llegeix les parts que figuren als documents](https://docs.didit.me/ca/sessions-api/kyb-extracted-parties.md), incloent-hi els accionistes i els percentatges de titularitat, i mostra-les al sol·licitant.
3) [Crea](https://docs.didit.me/ca/sessions-api/kyb-create-party-draft.md), [edita](https://docs.didit.me/ca/sessions-api/kyb-update-party-draft.md) i [elimina](https://docs.didit.me/ca/sessions-api/kyb-delete-party-draft.md) [esborranys de parts](https://docs.didit.me/ca/sessions-api/kyb-list-party-drafts.md). Un esborrany no es declara i no té cost.
4) [Envia els esborranys](https://docs.didit.me/ca/sessions-api/kyb-submit-parties.md). Didit decideix quines parts s'han de verificar, crea una sessió KYC per a cadascuna i retorna el seu `kyc_session_url` perquè l'enviïs o l'incrustis.
5) Llegeix la decisió consolidada de la sessió, igual que en el flux allotjat.Una crida feta mentre la sessió és en un altre pas respon `409 kyb_step_mismatch` amb el pas en què es troba, i una sessió finalitzada respon `409 kyb_session_not_writable`.## Agregació de perfils d'empresaSi passes `vendor_data` en crear la sessió, Didit agrega totes les sessions d'aquesta empresa en una única [entitat d'empresa](https://docs.didit.me/ca/entities/businesses/overview.md). Fes servir el mapa `features` de l'entitat per respondre «aquesta empresa està completament verificada ara mateix?» sense iterar sessions.Beneficis:- Els fluxos periòdics de re-KYB s'afegeixen al mateix perfil.
- Les transaccions monitoritzades amb el mateix `vendor_data` incorporen el context de risc de l'empresa.
- Els UBO i els administradors vinculats a entitats d'usuari omplen les relacions entre entitats.## Bones pràctiques| Pràctica | Motiu |
| - | - |
| Passa sempre `vendor_data` | Sense ell, la sessió queda òrfena i no es pot agregar. |
| Fes servir webhooks, no sondeig | Menys latència, sense pressió sobre el límit de freqüència. |
| Verifica les signatures dels webhooks | Evita esdeveniments suplantats. |
| Emmagatzema el `session_id` al teu sistema | Necessari per recuperar la decisió i generar PDFs. |
| Etiqueta les sessions amb `metadata` | Simplifica els informes i la depuració. |
| Configura un flux de treball de prova | Fes servir un flux de treball de sandbox per a les proves d'integració abans de producció. |## Gestió d'errors| Escenari | Resposta |
| - | - |
| `workflow_id` no vàlid | `400 Bad Request` |
| Sessió duplicada amb el mateix `vendor_data` | Crea una sessió nova; és el comportament previst, ja que s'espera una reverificació. |
| El país de l'empresa està fora dels països permesos del flux de treball | La comprovació del registre genera l'advertència `KYB_COUNTRY_RESTRICTED`. |
| Caiguda del proveïdor de registres durant la cerca d'empreses | `POST /v3/kyb/search/` retorna `502` amb `code: "kyb_registry_provider_unavailable"`. No es cobra. Torna a intentar-ho o, segons `code`, ofereix la introducció manual de l'empresa. Al flux allotjat de Didit, l'empresa passa automàticament a la introducció manual en lloc d'un error que només permet reintentar. Consulta [KYB Registry Search](https://docs.didit.me/ca/standalone-apis/kyb-registry-search.md#gestió-d’interrupcions-del-registre). |
| Límit de freqüència | `429 Too Many Requests` amb la capçalera `Retry-After`. |Referència completa de [límit de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md).## Propers passos> [card] [Webhooks](https://docs.didit.me/ca/business-verification/webhooks.md)
>
> Tots els esdeveniments i payloads de KYB.> [card] [Estats](https://docs.didit.me/ca/business-verification/statuses.md)
>
> Referència de la màquina d'estats.> [card] [Esquema de resposta](https://docs.didit.me/ca/business-verification/response-schema.md)
>
> Com interpretar la decisió de KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.