Solicitações KYB

KYB ("Know Your Business") verifica a identidade e a estrutura de uma entidade empresarial. O ciclo de vida é o mesmo do KYC — criar, enviar documentos de apoio, enviar para processamento e receber uma decisão —, mas com uma etapa extra: você envia um payload de dados da entidade KYB descrevendo a empresa e seus principais responsáveis.

Crie a solicitação com type: "BUSINESS" e depois faça um POST para o endpoint /kyb para anexar os dados da entidade.

A extensão KYB

POST /api/v1/kyc/requests/:id/kyb    Escopo: kyc:write

Anexa os dados da empresa, os diretores e os beneficiários finais (UBOs) a uma solicitação BUSINESS existente.

Corpo da requisição

{
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "appointedAt": "2018-01-15"
    }
  ],
  "ubos": [
    {
      "fullName": "Jane Doe",
      "dateOfBirth": "1975-06-22",
      "nationality": "GB",
      "ownershipPercentage": 100
    }
  ]
}

Cada diretor e UBO informa fullName, dateOfBirth e nationality, além de campos específicos do papel (appointedAt para diretores, ownershipPercentage para UBOs).

Resposta (201)

{ "id": "req_...", "status": "PENDING_UPLOAD" }

A resposta também inicia uma consulta ao registro em segundo plano — a Certivant consulta o registro comercial correspondente (Companies House para GB, OpenCorporates para muitos outros países) e armazena os resultados vinculados à solicitação. Os resultados do registro ficam visíveis em GET /kyb.

Obter dados KYB

GET /api/v1/kyc/requests/:id/kyb    Escopo: kyc:read

Retorna os dados da entidade enviados, junto com quaisquer resultados de consulta ao registro.

Resposta

{
  "id": "kyb_...",
  "requestId": "req_...",
  "companyName": "Acme Holdings Ltd",
  "registrationNo": "12345678",
  "countryOfIncorp": "GB",
  "companyType": "private_limited",
  "directors": [...],
  "ubos": [...],
  "registryLookup": {
    "status": "verified",
    "registryName": "Companies House",
    "registryUrl": "https://find-and-update.company-information.service.gov.uk/company/12345678",
    "registeredName": "Acme Holdings Ltd",
    "registeredAddress": "1 Example St, London",
    "status": "active",
    "incorporatedAt": "2018-01-15",
    "officerDelta": [],
    "raw": { ... }
  }
}

registryLookup.officerDelta lista quaisquer dirigentes encontrados no registro, mas não declarados no seu array directors — útil para identificar informações faltantes.

Documentos obrigatórios

Uma solicitação BUSINESS normalmente exige um conjunto de documentos diferente do de uma pessoa física:

• CERTIFICATE_OF_INCORPORATION — comprovante de que a empresa existe.
• PROOF_OF_ADDRESS — para a sede registrada.
• GOVERNMENT_ID e SELFIE para cada UBO e diretor (em algumas configurações, eles ficam em subsolicitações por solicitante).
• COMPANY_OWNERSHIP_STRUCTURE — organograma ou livro de acionistas.

A lista exata é retornada em pendingDocTypes na solicitação depois que você anexa a entidade KYB. As configurações KYB da sua organização determinam o que é exigido.

Subsolicitações KYC por dirigente

Dependendo das configurações da sua organização, a Certivant pode criar automaticamente subsolicitações KYC individuais para cada UBO e diretor. Elas aparecem como solicitações separadas, vinculadas à solicitação BUSINESS principal pelo campo parentRequestId. Você envia documentos para cada subsolicitação da mesma forma que envia para uma solicitação KYC avulsa — veja Documentos.

graph LR
  Parent[BUSINESS request<br/>req_parent] --> Co[Company docs<br/>incorporation, address]
  Parent --> Ubo1[UBO 1 sub-request<br/>req_ubo1]
  Parent --> Ubo2[UBO 2 sub-request<br/>req_ubo2]
  Parent --> Dir1[Director sub-request<br/>req_dir1]
  Ubo1 --> Id1[GOVERNMENT_ID + SELFIE]
  Ubo2 --> Id2[GOVERNMENT_ID + SELFIE]
  Dir1 --> Id3[GOVERNMENT_ID + SELFIE]

A solicitação principal permanece em PENDING_UPLOAD até que todas as subsolicitações estejam pelo menos em PROCESSING; em seguida, passa pelo mesmo ciclo de vida de uma solicitação individual — PROCESSING → APPROVED / REJECTED / ESCALATED.

Envio e decisão

Depois que os documentos da empresa forem enviados e todas as subsolicitações forem enviadas, envie a solicitação principal:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_parent/submit \
  -H "Authorization: Bearer ck_live_..."

O mecanismo de risco agrega as verificações da empresa da solicitação principal e o veredito de cada subsolicitação em uma única decisão. Os eventos de webhook são disparados para a principal — você não precisa acompanhar cada subsolicitação separadamente, a menos que queira uma visão detalhada.

Erros

• 400 BAD_REQUEST — a solicitação não é do tipo BUSINESS. Os endpoints KYB funcionam apenas em solicitações empresariais.
• 409 CONFLICT — os dados KYB já foram anexados. Para alterá-los, entre em contato com o suporte — os dados da entidade fazem parte da trilha de auditoria e não podem ser editados livremente.

Relacionados

• Solicitações KYC — os endpoints de solicitação subjacentes, com o mesmo ciclo de vida.
• Documentos — envio de comprovante de constituição e de documentos por dirigente.
• Webhooks — os mesmos eventos kyc.request.* se aplicam.