Pular para o conteúdo principal
Os campos personalizados permitem que sua conta de comerciante armazene dados de KYC/KYB que o modelo de entidade padrão não inclui, como atividade comercial, origem dos fundos, volumes estimados ou identificadores locais. A Localpayment define um esquema para o seu comerciante, e você envia os valores em attributes ao criar ou atualizar uma entidade.

Pré-requisitos

  • Um esquema de campos personalizados acordado com o seu gestor de conta e publicado pela Localpayment.
  • Um token de acesso do ambiente Stage. Consulte Obter token de acesso.

Como funciona

  • Nenhum esquema publicado: attributes é aceito como enviado, e Obter esquema de campos personalizados retorna 404 CUSTOM_FIELD_SCHEMA_NOT_FOUND.
  • Esquema publicado: a validação é estrita. Chaves desconhecidas, chaves obrigatórias ausentes, tipos, comprimentos, padrões e intervalos incorretos são rejeitados com 400 CUSTOM_FIELDS_INVALID. Cada entidade registra o customFieldSchemaVersion com o qual foi validada.
  • Um esquema por comerciante se aplica tanto a INDIVIDUAL quanto a COMPANY. Os campos que só fazem sentido para empresas são definidos como opcionais.

Tipos de campo

As chaves usam camelCase e começam com uma letra minúscula (^[a-z][a-zA-Z0-9_]{0,63}$). attributes pode ter até 64 KB (413 PAYLOAD_TOO_LARGE).

Leia o esquema

Request
Response
A resposta padrão é um JSON Schema (2020-12). Adicione ?format=definition para obter a lista de campos nativa.

Envie os valores

Os valores trafegam em attributes em Criar uma entidade e Atualizar uma entidade:
Um valor fora do esquema retorna 400 CUSTOM_FIELDS_INVALID, com uma entrada por campo inválido em details:
Valide attributes em relação ao esquema do seu lado antes de chamar a API e associe cada entrada de details de volta ao seu formulário para que o usuário possa corrigir o valor.

Alterar o esquema

A Localpayment publica as alterações de esquema como uma nova versão. As entidades existentes mantêm seu customFieldSchemaVersion, e as novas gravações são validadas em relação à versão publicada mais recente. Peça ao seu gestor de conta para adicionar, flexibilizar ou remover campos.
Após a publicação de um esquema, qualquer chave não definida nele será rejeitada. Coordene as alterações de esquema antes de enviar novos campos da sua integração.

Próximos passos

Obter esquema de campos personalizados

Formatos de resposta e códigos de erro.

Compartilhar informações KYB por meio de entidades

Os campos personalizados usados para os beneficiários da Conta Virtual.
Última modificação em 10 de novembro de 2026