> ## 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.
# Checkout Sessions
> Entenda o objeto que representa uma tentativa de compra, de onde ele nasce e quais dados e comportamentos pode coordenar.
Uma **Checkout Session** representa uma tentativa individual de compra. Ela
reúne os itens, os valores, o comprador, as regras comerciais e o estado daquela
experiência de pagamento — do momento em que a página é aberta até a conclusão
ou a expiração.
Cada sessão é descartável. Ela nasce para uma compra específica, expira em 24
horas e não volta a ficar aberta depois de concluída ou expirada.
Crie uma sessão pela API, escolha os itens e redirecione o comprador para a
página hospedada.
## O que pertence a uma sessão
A Checkout Session funciona como o contexto da compra. Ela mantém juntos os
dados que precisam acompanhar aquela tentativa:
| Área | O que a sessão representa |
| ------------- | ----------------------------------------------------------------------------- |
| Oferta | Itens, quantidades, moeda, subtotal, desconto, taxas e total. |
| Comprador | Customer vinculado ou dados usados para pré-preencher o checkout. |
| Experiência | URLs de retorno, texto do botão e acesso à página hospedada. |
| Recorrência | A intenção de criar uma assinatura, incluindo trial e prazo quando aplicável. |
| Aquisição | Primeiro contexto de campanha capturado para aquela compra. |
| Reconciliação | `metadata` definida pelo seu sistema para relacionar a sessão ao pedido. |
| Estado | Progresso do checkout, resultado financeiro refletido e prazo de expiração. |
A sessão coordena a experiência, mas não substitui os objetos financeiros. O
Payment Intent controla a cobrança; uma Charge representa cada tentativa de
mover dinheiro; invoices e subscriptions entram no fluxo quando a venda exige
faturamento ou recorrência.
## Quando uma Checkout Session é criada
Hoje existem duas origens:
| Origem | O que acontece |
| ----------------- | ------------------------------------------------------------------------------- |
| Seu backend | `POST /v1/checkout-sessions` cria uma sessão com dados próprios daquele pedido. |
| Link de pagamento | Cada abertura válida do link materializa uma sessão nova e independente. |
**Invoice não cria Checkout Session.** Uma invoice tem sua própria página
hospedada e seu próprio ciclo de cobrança. No sentido inverso, uma sessão de
pagamento avulso pode materializar uma invoice depois do pagamento quando
`invoice_creation: true`; sessões recorrentes criam uma subscription, e o
ciclo dessa assinatura materializa invoices.
Essa diferença evita misturar uma tentativa de compra com uma cobrança já
formalizada. Para cobrar uma invoice existente, compartilhe a
`hosted_invoice_url`; para iniciar uma compra nova, use uma Checkout Session ou
um [Link de pagamento](/payments/payment-links).
## Checkout Session ou Link de pagamento
| Decisão | Checkout Session | Link de pagamento |
| ----------------------- | ---------------------------- | ---------------------------------------- |
| Unidade | Uma tentativa de compra. | Uma oferta reutilizável. |
| Quem inicia | Seu backend cria pela API. | Você compartilha a mesma URL. |
| Dados por compra | Podem mudar em cada request. | A oferta fica definida no link. |
| O que acontece ao abrir | Abre a própria sessão. | Cria uma sessão nova para aquele acesso. |
| Validade | Expira em 24 horas. | Continua ativo até ser desativado. |
Veja [Link de pagamento vs. Sessão de
checkout](/payments/payment-link-vs-checkout-session) para escolher o recurso
certo antes de integrar.
## O que você pode personalizar
Parte da experiência pertence à tentativa de compra; outra parte pertence à
organização e é reutilizada em todos os checkouts.
### Por sessão
| Necessidade | Parâmetros principais | Comportamento |
| ------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Definir o que será vendido | `line_items` | Use preço do catálogo, produto com preço ad-hoc ou produto e preço totalmente ad-hoc. |
| Permitir ajuste de quantidade | `line_items[].adjustable_quantity` | O comprador altera a quantidade dentro dos limites definidos. |
| Vincular ou pré-preencher o comprador | `customer_id`, `customer_name`, `customer_email`, `customer_document` | Fixe um Customer existente ou antecipe dados do formulário. |
| Aplicar desconto | `discount_id` | A sessão nasce com um desconto pré-aplicado. |
| Repassar tarifa | `has_surcharge` | Acrescenta o repasse ao total de uma cobrança avulsa. |
| Criar invoice no pagamento avulso | `invoice_creation` | Materializa uma invoice após o pagamento bem-sucedido. |
| Criar assinatura | preço recorrente e `subscription_data` | Define trial, política sem cartão e prazo da subscription que nascerá. |
| Controlar o retorno | `success_url`, `cancel_url` | Leva o comprador de volta ao seu site após concluir ou sair. |
| Alterar a ação do botão | `submit_type` | Exibe uma ação equivalente a pagar, assinar, reservar ou doar. |
| Registrar aquisição | `marketing_attribution` | Preserva o primeiro contexto de campanha da compra. |
| Relacionar ao seu pedido | `metadata` | Ecoa dados livres do seu sistema nos eventos da sessão. |
O `mode` não é enviado. A Chargefy o deriva dos itens: preços avulsos criam uma
sessão `payment`; preços recorrentes criam uma sessão `subscription`. Itens
avulsos e recorrentes não podem ser misturados na mesma sessão.
### Para toda a organização
O [Checkout Builder](/payments/configure-checkout-page) define a configuração
compartilhada pela página hospedada:
* identidade visual, tema, fonte, bordas e template;
* cartão, Pix e boleto disponíveis;
* campos adicionais exigidos do comprador;
* regras de parcelamento;
* exibição do resumo do pedido.
Essas escolhas não são copiadas para o objeto. A página lê a configuração atual
da organização quando é aberta, inclusive em sessões que já existiam. A
aceitação de códigos de desconto é a exceção: ela é decidida por sessão, pelo
campo `allow_discount_codes` do create (ou herdada do payment link de origem).
## Como o comprador acessa
A resposta de criação entrega dois identificadores para usos diferentes:
| Campo | Uso |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `url` | Página hospedada e pronta. Redirecione o navegador do comprador para ela. |
| `client_secret` | Credencial limitada ao runtime daquela sessão no navegador. Permite consultar e confirmar a sessão sem expor sua API key. |
Na integração hospedada, normalmente você usa apenas `url`. Uma experiência
própria pode usar `client_secret`, mas precisa renderizar campos, estados,
validações e tokenização de forma segura no navegador.
## Estados e resultado financeiro
A sessão acompanha dois eixos independentes:
| Campo | Valores | O que responde |
| ---------------- | --------------------------------------- | ------------------------------------- |
| `status` | `open`, `complete`, `expired` | O comprador ainda pode usar a sessão? |
| `payment_status` | `unpaid`, `paid`, `no_payment_required` | O dinheiro já foi confirmado? |
Uma sessão de Pix ou boleto pode ficar `complete` e `unpaid`: o comprador
terminou o formulário, mas o pagamento ainda aguarda compensação. Por isso,
chegar à página de sucesso não é prova de pagamento.
| Evento | Interpretação |
| ------------------------------------------ | ---------------------------------------------------------- |
| `checkout.session.created` | A tentativa foi criada. |
| `checkout.session.completed` | O comprador concluiu o checkout; confira `payment_status`. |
| `checkout.session.async.payment.succeeded` | Um pagamento assíncrono foi confirmado. |
| `checkout.session.async.payment.failed` | Um pagamento assíncrono falhou ou venceu. |
| `checkout.session.expired` | A sessão aberta chegou ao prazo ou foi expirada. |
Use webhooks assinados para liberar produto, ativar acesso e reconciliar a
compra. A presença do comprador no frontend nunca substitui essa confirmação.
## Vantagens da Checkout Session
* isola cada pedido em uma tentativa com valores e comprador próprios;
* entrega uma página hospedada sem exigir que você construa o formulário;
* aplica a mesma configuração de checkout em todos os canais;
* coordena pagamentos avulsos, assinaturas, descontos, parcelamento e dados do
comprador;
* mantém API key e decisões comerciais no backend;
* oferece webhooks e `metadata` para reconciliação confiável.
## Próximos passos
Implemente o fluxo via API e conheça todas as variantes de itens e
customizações.
Consulte o schema completo retornado pela API e pelos webhooks.
Defina identidade, métodos, campos, parcelamento e templates.
Combine pedido, página de retorno, webhooks e entrega idempotente.