> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Coletar dados do comprador
> Defina quais dados o checkout hospedado deve pedir, pré-preencha informações conhecidas e recupere o customer resolvido após a compra.
O checkout hospedado sempre coleta o **nome** e o **email** necessários para
identificar o comprador e processar o pagamento. Pelo Checkout Builder, você
pode acrescentar **CPF/CNPJ**, **telefone** e **endereço de cobrança** a todos
os meios de pagamento.
Peça apenas o que será usado no atendimento, na cobrança ou no cumprimento da
venda. Cada campo adicional aumenta o esforço para concluir a compra.
Entre no Dashboard, escolha a organização e acesse **Configurações → Checkout
→ Dados do cliente**.
## O que o checkout coleta
As exigências do meio de pagamento vêm primeiro. A configuração da organização
pode adicionar campos, mas nunca remover um dado necessário para processar o
pagamento.
| Meio de pagamento | Sempre obrigatório | Você pode acrescentar |
| ----------------- | ----------------------------------------- | ----------------------------- |
| Cartão | Nome do titular e email | CPF/CNPJ, telefone e endereço |
| Pix | Nome e email | CPF/CNPJ, telefone e endereço |
| Boleto | Nome, email, CPF/CNPJ e endereço completo | Telefone |
Boleto sempre exige CPF/CNPJ e endereço de cobrança. Mesmo que esses campos
estejam desligados no Builder, eles aparecem quando o comprador escolhe
boleto.
## Escolher os campos adicionais
No Dashboard, acesse **Configurações → Checkout**.
Ative CPF/CNPJ, telefone ou endereço de cobrança conforme a necessidade da
sua operação.
Abra o preview, alterne entre cartão, Pix e boleto e confirme que cada fluxo
pede somente os dados esperados.
A configuração pertence à organização. Checkout Sessions e Payment Links
carregam a política atual quando a página é aberta; não é necessário recriar
links ou sessões depois de salvar uma alteração.
## Nome, email, documento e telefone
O email aparece no início do formulário. O nome é coletado dentro do fluxo do
meio de pagamento — no cartão, por exemplo, ele é o nome do titular. CPF/CNPJ e
telefone aparecem logo depois quando estão habilitados.
| Dado | Comportamento no checkout | Onde fica depois da confirmação |
| -------- | ------------------------------------------------------------------------------------------- | ------------------------------- |
| Nome | Sempre solicitado; pode chegar pré-preenchido pela sessão ou pelo customer. | Checkout Session e Customer |
| Email | Sempre solicitado. Fica somente leitura quando a sessão já está vinculada a uma identidade. | Checkout Session e Customer |
| CPF/CNPJ | Opcional pela configuração; obrigatório no boleto. | Checkout Session e Customer |
| Telefone | Solicitado quando habilitado. O seletor de país normaliza o código internacional. | Customer |
### Pré-preencher dados conhecidos
Envie os dados que seu backend já conhece ao criar a Checkout Session. Isso
reduz digitação e evita que o mesmo comprador seja identificado de formas
diferentes.
```json theme={"theme":"css-variables"}
{
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "ana@exemplo.com",
"customer_name": "Ana Souza",
"line_items": [
{
"price_id": "price_7Dk3mP9qR2vL5xN8",
"quantity": 1
}
],
"metadata": {},
"success_url": "https://meusite.com/pedido/confirmado"
}
```
Se você já mantém um Customer na Chargefy, envie `customer_id` no lugar de
repetir sua identidade. A sessão fica vinculada a esse cadastro; o checkout
preenche o email e atualiza telefone e endereço quando o comprador informar
valores diferentes.
A resolução é isolada por organização e ambiente. Sem `customer_id`, a
Chargefy procura primeiro um Customer ativo com o mesmo CPF/CNPJ e depois com
o mesmo email; só cria outro cadastro quando não encontra correspondência.
## Endereço de cobrança
Ao habilitar endereço, o checkout pede CEP, rua, número, complemento, bairro,
cidade e estado. Complemento e bairro podem ficar vazios quando não forem
aplicáveis; CEP, rua, número, cidade e estado precisam estar completos para a
confirmação.
O Checkout Builder coleta **endereço de cobrança**. Se sua venda exige endereço
de entrega, instruções de acesso ou outro dado operacional, colete essas
informações no seu site e relacione-as ao pedido com `metadata` ou com o ID da
Checkout Session.
## Recuperar os dados coletados
Quando o comprador confirma, a Checkout Session recebe o Customer resolvido.
Use o evento `checkout.session.completed` para obter `customer`,
`customer_name`, `customer_email`, `customer_document` e
`customer_document_type`. Em seguida, consulte o Customer para ler telefone e
endereço de cobrança.
| Informação | Fonte recomendada |
| -------------------------------- | ---------------------------------------- |
| Resultado e identidade da compra | `checkout.session.completed` |
| Telefone e endereço atualizados | `GET /v1/customers/{customer}` |
| Mudança no cadastro do comprador | `customer.created` ou `customer.updated` |
O Customer retornado pela API tem este formato completo:
```json theme={"theme":"css-variables"}
{
"id": "cus_Y5n5wQ4F11JkgT7Z",
"object": "customer",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Rua Exemplo, 100",
"line2": null,
"postal_code": "01000-000",
"state": "SP"
},
"billing_name": "Ana Souza",
"created_at": "2026-08-08T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "ana@exemplo.com",
"livemode": true,
"metadata": {},
"name": "Ana Souza",
"phone": "+5511999990000",
"updated_at": "2026-08-08T15:02:10Z"
}
```
Trate o webhook como a fonte confiável para o resultado da compra. O retorno
do navegador serve para a experiência do comprador, não para liberar produto
ou serviço no backend.
## Próximos passos
Ajuste template, identidade visual, meios de pagamento e campos do
comprador.
Veja todos os campos para pré-preencher e criar a página pelo backend.
Receba o Customer resolvido e processe o resultado com segurança.
Consulte nome, email, telefone, documento e endereço de cobrança.