Referência

Customers representam os clientes finais da sua loja. Cadastrá-los é opcional para criar cobranças, mas traz benefícios:

Identificação

Suas cobranças vinculam ao customer e ficam fáceis de filtrar/relatar.

Reutilização

Use o mesmo customerId em várias cobranças sem reenviar dados.

Personalização

O nome do customer aparece na confirmação do pagamento PIX.

Filtros

Liste cobranças de um customer específico passando customerId no GET.

Campos

Campo	Obrigatório?	Descrição
`email`	Sim	E-mail válido
`name`	Não	Nome completo (1 a 120 caracteres)
`taxId`	Não	CPF (11 dígitos) ou CNPJ (14 dígitos) — único por merchant
`phone`	Não	Telefone/celular (até 20 caracteres)

Não existe um campo separado de “tipo de documento” — taxId aceita CPF ou CNPJ diretamente (a API identifica pelo tamanho).

Exemplo: criar customer

POST /customers
{
  "email": "joao@exemplo.com",
  "name": "João Silva",
  "taxId": "12345678900",
  "phone": "+5511999999999"
}

Resposta:

{
  "data": {
    "id": "cust_018f3a2b7c4d7c40a1b2",
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "taxId": "12345678900",
    "phone": "+5511999999999",
    "createdAt": "2026-04-19T18:32:11.420Z"
  },
  "error": null,
  "success": true
}

Diferente de outros dados sensíveis da API, o taxId volta sem máscara nas respostas — ele pertence ao seu merchant, não é exposto publicamente.

taxId é único por merchant. Se você tentar criar um customer com um taxId já cadastrado, recebe 409 CONFLICT. Use GET /customers?taxId=... para buscar antes de criar.

Operações disponíveis

Operação	Endpoint
Criar	`POST /customers`
Listar	`GET /customers`
Obter por ID	`GET /customers/{id}`
Remover	`DELETE /customers/{id}`

Não existe rota para editar um cliente já cadastrado. Para corrigir um dado, remova (DELETE) e cadastre novamente.

Clientes

Checkout Transparente

Saques

Webhooks

Identificação

Reutilização

Personalização

Filtros

Campos

Exemplo: criar customer

Operações disponíveis

Identificação

Reutilização

Personalização

Filtros

​Campos

​Exemplo: criar customer

​Operações disponíveis

Campos

Exemplo: criar customer

Operações disponíveis