Pular para o conteúdo principal
POST
Registra uma pessoa física (INDIVIDUAL) ou uma pessoa jurídica (COMPANY) com seu documento de identificação. A entidade é criada com status PENDING_KYC e sem arquivos; envie os arquivos de apoio depois com Enviar uma Prova.
  • Os dados mínimos de KYC são validados na criação: name e lastname para INDIVIDUAL, name para COMPANY. Caso contrário, a API retorna 422 INCOMPLETE_KYC_DATA.
  • Propriedades desconhecidas são rejeitadas com 400 VALIDATION_ERROR. Coloque quaisquer dados adicionais em attributes.
  • Os códigos de país devem estar em ISO 3166-1 alpha-3 (BRA, não BR).
  • Um identificador fiscal (CPF, CNPJ, CUIT, RFC, …) é um documento, não um campo da entidade. Envie-o em document; documents[] não é aceito na criação (400 VALIDATION_ERROR).
  • Adicione os demais documentos (documento de identidade, comprovante de endereço, contrato social) com Adicionar um Documento.
  • Guarde document.documentId da resposta: é o docId usado para enviar arquivos ao documento principal.
Erros usam application/problem+json com um code estável. Catálogo completo: Status de Entidades e Códigos de Erro.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cabeçalhos

Authorization
string
obrigatório

Token de acesso Bearer para autenticação. Este token é obtido nos endpoints Obter token de acesso ou Renovar token de acesso. Sua conta de comerciante e o usuário que realiza a ação são identificados a partir dele.

Exemplo:

"Bearer <your_access_token>"

X-Correlation-ID
string

Identificador de rastreamento (UUID). Exibido na resposta; gerado pelo Localpayment se ausente.

Exemplo:

"0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10"

Corpo

application/json
externalId
string
obrigatório

Seu próprio identificador para a entidade. Único para cada comerciante, de 1 a 64 caracteres.

Exemplo:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

type
enum<string>
obrigatório

PESSOA FÍSICA ou EMPRESA (pessoa jurídica).

Opções disponíveis:
INDIVIDUAL,
COMPANY
Exemplo:

"COMPANY"

name
string
obrigatório

Nome (PESSOA FÍSICA) ou razão social (EMPRESA). Até 255 caracteres.

Exemplo:

"Example Company S.A."

document
object
obrigatório

O documento de identificação da entidade (número de identificação fiscal ou documento de identidade). Ele se torna o documento principal. Outros documentos são adicionados posteriormente através da opção "Adicionar um documento".

lastname
string

Sobrenome. Obrigatório para INDIVIDUAL. Até 255 caracteres.

Exemplo:

"Doe"

birthdate
string<date>

AAAA-MM-DD. Recomendado para uso INDIVIDUAL.

Exemplo:

"1990-01-15"

gender
enum<string>

MALE, FEMALE, OTHER ou UNDISCLOSED.

Opções disponíveis:
MALE,
FEMALE,
OTHER,
UNDISCLOSED
Exemplo:

"FEMALE"

nationality
string

ISO 3166-1 alpha-3 (BRA, ARG, MEX).

Exemplo:

"BRA"

birthCountry
string

ISO 3166-1 alfa-3.

Exemplo:

"BRA"

residenceCountry
string

ISO 3166-1 alfa-3. Para uma EMPRESA, país de residência fiscal.

Exemplo:

"BRA"

occupation
string

Profissão da pessoa. Até 100 caracteres.

Exemplo:

"Engineer"

isPep
boolean

Pessoa politicamente exposta. Valor padrão: falso.

Exemplo:

false

incorporationDate
string<date>

AAAA-MM-DD. Somente para empresas.

Exemplo:

"2020-01-15"

incorporationCountry
string

ISO 3166-1 alfa-3. Somente para empresas.

Exemplo:

"BRA"

website
string

Site da empresa. Até 255 caracteres.

Exemplo:

"https://www.example.com"

Nome do representante legal (COMPANY). Até 255 caracteres.

Exemplo:

"Jane Doe"

email
string

E-mail para contato. Até 255 caracteres.

Exemplo:

"test@example.com"

phone
object

Telefone para contato, somente dígitos em cada parte.

address
object

Endereço postal. Ao enviar, é necessário informar o país.

attributes
object

Campos personalizados definidos pelo seu esquema de campos personalizados (consulte Campos Personalizados). Até 64 KB.

Resposta

Criado.

internalId
string<uuid>

Identificador da entidade na Localpayment. Use-o em todos os outros endpoints de Entities.

Exemplo:

"5aced5da-40c1-4bec-85ff-c8cd1bcb4526"

externalId
string

Seu identificador, conforme enviado.

Exemplo:

"550e8400-e29b-41d4-a716-446655440000"

type
enum<string>

PESSOA FÍSICA ou EMPRESA.

Opções disponíveis:
INDIVIDUAL,
COMPANY
Exemplo:

"INDIVIDUAL"

status
enum<string>

Status da entidade. Consulte Status da entidade e Códigos de erro.

Opções disponíveis:
PENDING_KYC,
IN_REVIEW,
ACTIVE,
REJECTED,
BLOCKED,
CLOSED
Exemplo:

"PENDING_KYC"

name
string
Exemplo:

"Jane"

lastname
string
Exemplo:

"Doe"

birthdate
string<date>
Exemplo:

"1990-01-15"

gender
string | null
nationality
string
Exemplo:

"BRA"

birthCountry
string
Exemplo:

"BRA"

residenceCountry
string
Exemplo:

"BRA"

occupation
string | null
isPep
boolean
Exemplo:

false

incorporationDate
string<date> | null
incorporationCountry
string | null
website
string | null
email
string
Exemplo:

"jane.doe@example.com"

phone
object
address
object
attributes
object | null
documentationStatus
enum<string>

NO_FILES, PARTIAL ou COMPLETE: indica se nenhum, alguns ou todos os documentos declarados possuem pelo menos um arquivo. Mede a presença de arquivos, não a aprovação.

Opções disponíveis:
NO_FILES,
PARTIAL,
COMPLETE
Exemplo:

"NO_FILES"

document
object

O documento principal com seu documentId (necessário para enviar arquivos), o status derivado e as proofs[] atuais.

documents
object[]

Os demais documentos declarados (o principal está apenas em document), com a mesma estrutura.

version
integer

Versão da entidade. Igual ao cabeçalho ETag; envie-o de volta como If-Match no PATCH.

Exemplo:

0

createdAt
string<date-time>

Carimbos de data/hora UTC ISO 8601.

Exemplo:

"2024-01-15T17:03:10Z"

updatedAt
string<date-time>

Carimbos de data/hora UTC ISO 8601.

Exemplo:

"2024-01-15T17:03:10Z"

customFieldSchemaVersion
integer | null

Versão do esquema de campos personalizados usado para validar atributos, ou nulo.

Última modificação em 10 de novembro de 2026