Pular para o conteúdo principal
Este guia mostra, chamada por chamada e com solicitações e respostas, como enviar as informações listadas em Requisitos KYB para Beneficiários de Contas Virtuais usando a API de Entidades. O lugar de cada item em Entities está na coluna How to send it dessa página. Em resumo: a empresa é uma entidade do tipo COMPANY, cada pessoa é uma entidade do tipo INDIVIDUAL (os proprietários são vinculados à empresa como UBOs), e cada documento é um documento declarado com seus arquivos. Os exemplos usam uma empresa fictícia registrada no Brasil.

Pré-requisitos

Fluxo

Representante legal. Crie-o como um INDIVIDUAL (seu documento de identidade pode ser o documento principal) e vincule-o à empresa com Link a UBO: ownershipPercentage: 0 e controlRole: LEGAL_REPRESENTATIVE. Se o representante legal também for proprietário, vincule-o uma única vez, com a sua porcentagem e controlRole: LEGAL_REPRESENTATIVE.

Passo a passo

Execute as chamadas abaixo nesta ordem. Guarde cada internalId e documentId retornado pela API. Os exemplos enviam apenas o mínimo.

  1. Leia o esquema dos seus campos personalizados.

GET /api/entity/v1/custom-fields/schema retorna os atributos que a sua conta aceita. Trecho com o perfil do negócio:

  1. Criar a empresa

POST /api/entity/v1/entities. O número de identificação fiscal é o documento principal, e o perfil do negócio vai em attributes:
Request
Response
A resposta é 201 Created (trecho). O documento principal retorna com seu documentId e sem arquivos, o que é esperado: ele não precisa de nenhum.

  1. Declare os documentos da empresa e faça o upload dos arquivos.

Declare cada documento com POST /api/entity/v1/entities/{companyId}/documents. O documento de constituição da empresa traz o número de registro em id (no Brasil, o CNPJ):
Em seguida, envie um POST /api/entity/v1/documents/{documentId}/proofs por arquivo, com proofType=DOCUMENT e o arquivo. Resposta (trecho):
Declare e faça o upload dos documentos de origem dos fundos e, para B2C, do comprovante de titularidade da mesma forma:

  1. Crie cada pessoa

Um INDIVIDUAL por proprietário e para o representante legal, com POST /api/entity/v1/entities. O documento de identidade pode ser o documento principal:
Request
Response
A resposta é 201 Created (trecho).

  1. Faça o upload do documento de identidade de cada pessoa.

Frente e verso vão para o mesmo documento: POST /api/entity/v1/documents/{documentId}/proofs com proofType=FRONT, e depois com proofType=BACK (passaporte: somente FRONT). Trecho de GET /api/entity/v1/documents/{documentId}/proofs após os dois uploads:
Um POST /api/entity/v1/entities/{companyId}/ubos por pessoa. Jane Doe detém 60% e também é a representante legal:
Request
Response
John Doe detém 40%, com o cargo em letras maiúsculas:
GET /api/entity/v1/entities/{companyId}/ubos lista ambos:
Guarde o internalId da empresa: ele identifica o beneficiário na Localpayment.

  1. Informe à Localpayment que o upload foi concluído.

Quando a empresa, seus documentos e todas as pessoas estiverem carregados e vinculados, chame POST /api/entity/v1/entities/{companyId}/verify na empresa (Solicitar verificação). Isso informa à Localpayment que o upload da documentação foi concluído. A resposta é 202 Accepted (trecho):
Enquanto a empresa está IN_REVIEW, ela fica bloqueada (409 ENTITY_IN_REVIEW). Com verify, a sua parte do upload termina: você não precisa consultar o status da entidade depois.

Lista de verificação

  • Todos os documentos que você declarou (constituição da empresa, comprovante de origem dos fundos, documentos de identidade) possuem seus respectivos arquivos. O documento principal de identificação fiscal não precisa de arquivo.
  • Cada proprietário está vinculado à empresa com seu ownershipPercentage, e o representante legal com controlRole: LEGAL_REPRESENTATIVE.
  • attributes.businessProfile está definido na empresa.
  • Depois que tudo foi carregado, você chamou verify na empresa.
  • Os números de identificação fiscal contêm apenas dígitos, e os nomes correspondem exatamente aos documentos.
  • Todos os arquivos estão em formato PDF, PNG, JPG ou JPEG e têm menos de 10 MB.
Após a conclusão da lista de verificação, a Localpayment analisa a empresa e cada pessoa, e informa se algo precisa ser corrigido. Consulte Acompanhar a Análise e Corrigir Rejeições.

Próximos passos

Acompanhe a revisão e corrija as rejeições.

Siga as instruções da revisão e corrija o que a Localpayment solicitar.

Gerenciar UBOs

Atualize ou finalize os links do proprietário.
Última modificação em 10 de novembro de 2026