Clientes

O cliente reúne nome, e-mail, documento e celular de quem compra de você. Com o cliente salvo, você cria compras já preenchidas e encontra todos os pagamentos de uma pessoa.

Criar um cliente

curl https://api.valorapayments.com.br/v1/customers \
  -H "Authorization: Bearer $VALORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "email": "ana@example.com",
    "document": "12345678909",
    "phone": "11988887777",
    "external_reference": "usuario-42"
  }'

Campo	Observação
`name`	obrigatório, até 120 caracteres
`email`	único por negócio. Repetir responde `409 email_in_use`
`document`	CPF (11) ou CNPJ (14 dígitos), só números
`phone`	só dígitos, de 8 a 15, com `+` opcional
`external_reference`	o id do cliente no seu sistema
`metadata`	até 20 chaves de texto

Usar o cliente

No checkout
No Pix

Passe o customer_id e o formulário do checkout já abre preenchido:

{
  "product_cart": [{ "product_id": "prod_Ab12Cd34Ef56Gh78" }],
  "customer": { "customer_id": "cus_Zx98Cv76Bn54Mq32" }
}

Associe o pagamento ao cliente:

{ "method": "pix", "amount": "49.90", "customer_id": "cus_Zx98Cv76Bn54Mq32" }

Depois, liste os pagamentos dele com GET /v1/payments?customer_id=cus_Zx98Cv76Bn54Mq32.

Encontrar um cliente

GET /v1/customers aceita os filtros email e external_reference:

curl "https://api.valorapayments.com.br/v1/customers?email=ana@example.com" \
  -H "Authorization: Bearer $VALORA_API_KEY"

Atualizar

Use PATCH /v1/customers/{customer_id} com só os campos que mudam. Envie null para limpar um campo opcional.

O documento do cliente nunca é enviado ao checkout para preencher o formulário. O cliente sempre digita o CPF ou CNPJ na hora de pagar.

Começando

Recursos

Integrar

Frameworks

IA e agentes

Ajuda

Criar um cliente

Usar o cliente

Encontrar um cliente

Atualizar