Skip to main content
Um cliente representa a pessoa física ou jurídica que realiza pagamentos no seu projeto. Ele é identificado pelo CPF ou CNPJ e pode ser vinculado a múltiplas transações.

​
O objeto cliente

{
  "id": "cly1234567890",
  "name": "João Silva",
  "document": "12345678900",
  "email": "[email protected]",
  "phone": "11999999999",
  "street": "Rua Exemplo",
  "streetNumber": "123",
  "complement": null,
  "neighborhood": "Centro",
  "zipCode": "01310100",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "isBlocked": false,
  "blockedAt": null,
  "blockedReason": null,
  "blockExpiresAt": null,
  "blockType": null,
  "createdAt": "2026-01-16T10:00:00.000Z",
  "updatedAt": "2026-01-16T10:00:00.000Z"
}

​
Campos

CampoTipoDescrição
idstringIdentificador único do cliente (CUID)
namestringNome completo
documentstringCPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
emailstringEmail do cliente
phonestringTelefone (10-15 dígitos)
streetstringRua/logradouro
streetNumberstringNúmero
complementstring | nullComplemento do endereço
neighborhoodstringBairro
zipCodestringCEP
citystringCidade
statestringUF (2 caracteres)
countrystringPaís (2 caracteres). Default: BR
isBlockedbooleantrue se o cliente está bloqueado
blockedAtstring | nullData/hora do bloqueio (ISO 8601)
blockedReasonstring | nullMotivo do bloqueio
blockExpiresAtstring | nullData/hora de expiração do bloqueio. null se permanente
blockTypestring | nullTipo do bloqueio (manual, fraud)
createdAtstringData/hora de criação (ISO 8601)
updatedAtstringData/hora da última atualização (ISO 8601)

​
Regras importantes

  • Upsert por documento: criar um cliente com um CPF/CNPJ já existente atualiza os dados — nunca duplica.
  • Criação automática: ao criar uma transação PIX, o cliente é criado automaticamente se ainda não existir.
  • Clientes bloqueados não podem gerar novas transações. O bloqueio pode ser manual ou automático (detecção de fraude).
  • Isolamento por projeto: clientes são exclusivos do seu projeto — o mesmo CPF pode existir em projetos diferentes sem conflito.

Precisa de ajuda?

Nossa equipe está disponível para auxiliar no processo de desenvolvimento. Entre em contato pelo e-mail [email protected].