> ## Documentation Index
> Fetch the complete documentation index at: https://dev.valorapayments.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Valora Payments API (Brazil: Pix, card, boleto). Base URL https://api.valorapayments.com.br, Authorization: Bearer sk_vl_... used only on the server. Request amounts are reais as strings ("149.90"); response amounts are integer cents (14990). Use POST /v1/checkouts for card and boleto; POST /v1/payments only creates Pix and should send an Idempotency-Key. Confirm payments only through the payment.succeeded webhook after verifying X-Valora-Signature (hex HMAC-SHA256 of "<t>.<raw body>"), dedupe by event.id and check livemode. Never invent endpoints or fields: check /llms.txt and /openapi.json.

# Clientes

> Guarde os dados de quem compra para reutilizar em cobranças e checkouts.

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

```bash theme={null}
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

> [tab] No checkout
>
> Passe o `customer_id` e o formulário do checkout já abre preenchido:
>
> ```json theme={null}
> {
>   "product_cart": [{ "product_id": "prod_Ab12Cd34Ef56Gh78" }],
>   "customer": { "customer_id": "cus_Zx98Cv76Bn54Mq32" }
> }
> ```

> [tab] No Pix
>
> Associe o pagamento ao cliente:
>
> ```json theme={null}
> { "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`:

```bash theme={null}
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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.