> ## 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.

# Guia de integração KYB: arquitetura e padrões

> Integre o KYB da Didit: arquitetura, sessões, fluxos hospedados, webhooks, polling e decisões. A partir de $2.00 por verificação, por país e nível.



Prompt de integração KYB
        Copiar o prompt para a área de transferência



      
      

\<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>



      
      

Colar em

Este guia complementa o [guia de início rápido](https://docs.didit.me/pt-br/business-verification/quickstart.md). Ele aborda a arquitetura, cada decisão de integração e os padrões operacionais que tornam o KYB confiável em produção.## Arquitetura```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
```## AutenticaçãoTodas as requisições exigem o cabeçalho `x-api-key` com a chave de API da sua aplicação. Consulte [Autenticação da API](https://docs.didit.me/pt-br/getting-started/api-authentication.md) para rotação de chaves, separação de ambientes e escopos.## Criação de sessãoUm único endpoint: `POST /v3/session/`. O tipo do fluxo de verificação (workflow) determina se a sessão é de KYC ou de KYB, sem necessidade de uma flag "business" explícita.**Campos recomendados na criação:**| Campo | Finalidade |
| - | - |
| `workflow_id` | Obrigatório: referencia o seu fluxo de KYB. |
| `vendor_data` | O seu identificador para a empresa. Vincula a sessão a uma [entidade empresarial](https://docs.didit.me/pt-br/entities/businesses/overview.md). |
| `callback_url` | Opcional: para onde redirecionar o usuário após a conclusão. |
| `expected_details` | Opcional: `{ company_name, registry_country, registration_number }`. Preenche previamente a busca no registro de empresas: o país de constituição fica pré-selecionado e bloqueado (`registry_country` como `XX`, ou `XX-YY` para registros estaduais, por exemplo `US-CA`), os campos de nome da empresa e número de registro ficam preenchidos e a busca informada é executada automaticamente, combinando os dois identificadores quando ambos estão presentes. Serve apenas para preenchimento prévio: divergências não geram avisos. |
| `metadata` | JSON opcional anexado à sessão. |Esquema completo: [criar sessão](https://docs.didit.me/pt-br/sessions-api/create-session.md).## Entrega do link hospedadoO `url` da resposta é um link de verificação hospedado. Opções de entrega:- Envie-o por e-mail a partir da sua própria plataforma.
- Incorpore-o como link na interface de onboarding.
- Abra-o em uma webview dentro do app (iOS / Android / React Native).Você pode **personalizar** a experiência hospedada (logotipo, cor, domínio, modelos de e-mail) por meio da [Marca própria](https://docs.didit.me/pt-br/console/white-label.md).## Polling vs. webhooksOs webhooks são o padrão recomendado. A Didit envia eventos de conclusão via POST para o endpoint cadastrado assim que o processamento termina.O polling é suportado para desenvolvimento ou quando o seu endpoint de webhook está inacessível:* Faça polling em `GET /v3/session/{id}/decision/` com backoff exponencial (a cada 10s inicialmente, até 60s).
* Interrompa o polling quando `status` for um dos seguintes: `"Approved"`, `"Declined"`, `"In Review"`.> [!WARNING]
>
> Fazer polling em alta frequência pode atingir os [limites de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md). Em produção, prefira sempre webhooks.## Tratamento de webhooksInscreva-se nos eventos que interessam a você. Os mesmos eventos cobrem KYC e KYB, com `session_kind: "business"` no payload para identificar eventos de sessões empresariais:- `status.updated`: o status da sessão mudou. Filtre por `session_kind === "business"` para sessões de KYB.
- `data.updated`: um revisor editou dados do registro de empresas ou as pessoas-chave no console, ou o registro de empresas informou uma alteração. Esse evento não é enviado quando o solicitante faz upload de um documento ou envia as Pessoas-chave: para isso, acompanhe `status.updated`. O mesmo filtro de `session_kind` se aplica.
- `business.status.updated` / `business.data.updated`: a [entidade empresarial](https://docs.didit.me/pt-br/entities/businesses/overview.md) vinculada mudou.Catálogo completo de eventos: [webhooks de KYB](https://docs.didit.me/pt-br/business-verification/webhooks.md). Verificação de assinatura e semântica de novas tentativas: [referência de webhooks](https://docs.didit.me/pt-br/integration/webhooks.md).## Tratamento de decisões```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;
}
```Consulte [status de KYB](https://docs.didit.me/pt-br/business-verification/statuses.md) para a máquina de estados completa e [avisos de KYB](https://docs.didit.me/pt-br/business-verification/warnings.md) para as tags que explicam uma decisão.## Fluxo de reenvioQuando uma sessão de Verificação de empresas (KYB) passa para `Resubmitted` (ou um recurso é marcado para reenvio), a empresa precisa enviar dados corrigidos ou adicionais.Você pode:- **Reenviar** o mesmo `url`: o fluxo hospedado retoma a partir do ponto em que o reenvio é necessário.
- **Reemitir um link inválido de pessoa-chave**: uma pessoa cuja sessão de KYC vinculada foi excluída ou expirou antes de a pessoa iniciá-la recebe uma nova sessão com [Regenerate Key People KYC Session](https://docs.didit.me/pt-br/sessions-api/regenerate-kyb-party.md).
- **Abrir um [caso](https://docs.didit.me/pt-br/transaction-monitoring/cases.md)** no Business Console para acompanhar internamente as idas e vindas.## Execute as etapas a partir do seu próprio front-endAs etapas de documentos e de Pessoas-chave também podem ser conduzidas a partir do seu servidor com a sua chave de API, de modo que você mantém a interface do usuário e a Didit mantém a verificação e a decisão.
Cada chamada é restrita à sessão de KYB, exige a permissão `write:businesses` (a leitura das partes extraídas também aceita `read:businesses` ou `read:sessions`) e executa as mesmas verificações, o mesmo faturamento e o mesmo avanço de etapa que ocorre na página hospedada.1) [Envie os documentos societários](https://docs.didit.me/pt-br/sessions-api/kyb-upload-documents.md) enquanto a sessão estiver na etapa KYB Documents.
2) [Leia as partes mencionadas nos documentos](https://docs.didit.me/pt-br/sessions-api/kyb-extracted-parties.md), incluindo acionistas e percentuais de propriedade, e mostre-as ao seu solicitante.
3) [Crie](https://docs.didit.me/pt-br/sessions-api/kyb-create-party-draft.md), [edite](https://docs.didit.me/pt-br/sessions-api/kyb-update-party-draft.md) e [exclua](https://docs.didit.me/pt-br/sessions-api/kyb-delete-party-draft.md) [rascunhos de partes](https://docs.didit.me/pt-br/sessions-api/kyb-list-party-drafts.md). Um rascunho não é declarado e não tem custo.
4) [Envie os rascunhos](https://docs.didit.me/pt-br/sessions-api/kyb-submit-parties.md). A Didit decide quais partes devem ser verificadas, cria uma sessão de KYC para cada uma e retorna o `kyc_session_url` correspondente para você enviar ou incorporar.
5) Leia a decisão consolidada na sessão, como no fluxo hospedado.Uma chamada feita enquanto a sessão está em outra etapa responde `409 kyb_step_mismatch` com a etapa em que ela está, e uma sessão finalizada responde `409 kyb_session_not_writable`.## Agregação do perfil da empresaSe você informar `vendor_data` na criação da sessão, a Didit agrega todas as sessões dessa empresa em uma única [entidade empresarial](https://docs.didit.me/pt-br/entities/businesses/overview.md). Use o mapa `features` da entidade para responder "esta empresa está totalmente verificada neste momento?" sem percorrer as sessões.Benefícios:- Fluxos periódicos de re-KYB são adicionados ao mesmo perfil.
- As transações monitoradas com o mesmo `vendor_data` carregam o contexto de risco da empresa.
- UBOs e administradores vinculados a entidades User geram relações entre entidades.## Boas práticas| Prática | Por quê |
| - | - |
| Sempre envie `vendor_data` | Sem ele, a sessão fica órfã e não pode ser agregada. |
| Use webhooks, não polling | Menor latência e nenhuma pressão sobre o limite de requisições. |
| Verifique as assinaturas dos webhooks | Evita eventos falsificados. |
| Armazene o `session_id` no seu sistema | É necessário para recuperar a decisão e gerar PDFs. |
| Marque as sessões com `metadata` | Simplifica relatórios e depuração. |
| Configure um fluxo de teste | Use um fluxo de sandbox para testar a integração antes da produção. |## Tratamento de erros| Cenário | Resposta |
| - | - |
| `workflow_id` inválido | `400 Bad Request` |
| Sessão duplicada com o mesmo `vendor_data` | Cria uma nova sessão. Isso é intencional, já que a reverificação é esperada. |
| País da empresa fora dos países permitidos no fluxo | A verificação no registro gera o aviso `KYB_COUNTRY_RESTRICTED`. |
| Indisponibilidade do provedor de registro durante a busca de empresas | `POST /v3/kyb/search/` retorna `502` com `code: "kyb_registry_provider_unavailable"`. Não há cobrança: tente novamente ou crie uma ramificação com base em `code` para oferecer o cadastro manual da empresa. No fluxo hospedado da Didit, a empresa é encaminhada automaticamente para o cadastro manual, em vez de receber um erro que exige apenas uma nova tentativa. Consulte [Busca no registro KYB](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-search.md#lidar-com-indisponibilidades-do-registro). |
| Limite de requisições | `429 Too Many Requests` com o cabeçalho `Retry-After`. |Referência completa de [limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md).## Próximos passos> [card] [Webhooks](https://docs.didit.me/pt-br/business-verification/webhooks.md)
>
> Todos os eventos e payloads de KYB.> [card] [Status](https://docs.didit.me/pt-br/business-verification/statuses.md)
>
> Referência da máquina de estados.> [card] [Esquema de resposta](https://docs.didit.me/pt-br/business-verification/response-schema.md)
>
> Como interpretar a decisão de KYB.


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