Coletar dados do comprador

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.

Abrir o Checkout Builder

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

Abra a configuração do checkout

No Dashboard, acesse Configurações → Checkout.

Defina os dados do cliente

Ative CPF/CNPJ, telefone ou endereço de cobrança conforme a necessidade da sua operação.

Salve e teste

Abra o preview, alterne entre cartão, Pix e boleto e confirme que cada fluxo pede somente os dados esperados.

Controles do Checkout Builder para ativar CPF ou CNPJ, telefone e endereço — Os controles de dados do cliente no Checkout Builder. Nesta configuração, CPF/CNPJ e telefone estão ativos; endereço está desativado.

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.

Campos de nome do titular do cartão, CPF ou CNPJ e telefone no checkout hospedado — Recorte do formulário de cartão: nome do titular, documento e telefone ficam juntos para reduzir mudanças de contexto durante o preenchimento.

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.

{
  "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.

Campos de CEP, rua, número, complemento, bairro, cidade e estado no checkout hospedado — Somente a seção de endereço de cobrança, recortada do checkout para facilitar a leitura de cada campo.

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:

{
  "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

Configurar sua página de checkout

Ajuste template, identidade visual, meios de pagamento e campos do comprador.

Criar uma Checkout Session

Veja todos os campos para pré-preencher e criar a página pelo backend.

Evento checkout.session.completed

Receba o Customer resolvido e processe o resultado com segurança.

Objeto Customer

Consulte nome, email, telefone, documento e endereço de cobrança.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Coletar dados do comprador

Abrir o Checkout Builder

O que o checkout coleta

Escolher os campos adicionais

Nome, email, documento e telefone

Pré-preencher dados conhecidos

Endereço de cobrança

Recuperar os dados coletados

Próximos passos

Configurar sua página de checkout

Criar uma Checkout Session

Evento checkout.session.completed

Objeto Customer

Abrir o Checkout Builder

​O que o checkout coleta

​Escolher os campos adicionais

​Nome, email, documento e telefone

​Pré-preencher dados conhecidos

​Endereço de cobrança

​Recuperar os dados coletados

​Próximos passos

Configurar sua página de checkout

Criar uma Checkout Session

Evento checkout.session.completed

Objeto Customer

O que o checkout coleta

Escolher os campos adicionais

Nome, email, documento e telefone

Pré-preencher dados conhecidos

Endereço de cobrança

Recuperar os dados coletados

Próximos passos