> ## 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. # Overview > O objeto Checkout Session Uma `checkout.session` representa uma única tentativa de compra. Ela nasce para uma cobrança específica — com seus itens, valores e configuração visual já resolvidos — e devolve uma `url` (a página hospedada onde o comprador paga) e um `client_secret` (lido pelo browser do comprador para abrir essa página). É a sessão que coleta os dados do comprador, apresenta os métodos de pagamento disponíveis e confirma a escolha dele. Diferente de um payment link (URL pública reutilizável), a session é descartável: vale para uma compra, expira em 24h e não volta a `open` depois de confirmada. Ela também não é o livro-razão financeiro da cobrança — quem registra o resultado do pagamento são o `payment_status`, as invoices quando aplicável e os webhooks. A session surge quando você a cria pela API ou quando o comprador clica num payment link, e é atualizada conforme o comprador preenche o formulário e confirma o pagamento; para PIX e boleto, a compensação chega depois, de forma assíncrona. ## Data Object Este é o formato completo retornado em `create`, `get`, na confirmação e em `data.object` dos webhooks `checkout.session.*`. O campo `payment_data` vem `null` enquanto a sessão não foi confirmada e é preenchido conforme o método escolhido após o `confirm`. ```json theme={} { "id": "id_123", "object": "checkout.session", "allow_discount_codes": true, "amount_discount": 0, "amount_subtotal": 19990, "amount_tax": 0, "amount_total": 19990, "branding_settings": null, "cancel_url": null, "client_secret": "9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f", "created_at": "2026-05-03T18:31:00Z", "currency": "brl", "customer": null, "customer_document": null, "customer_document_type": null, "customer_email": null, "customer_name": null, "discount": null, "expires_at": "2026-05-04T18:31:00Z", "invoice_creation": false, "line_items": [ { "id": "id_789", "amount_discount": 0, "amount_subtotal": 19990, "amount_tax": 0, "amount_total": 19990, "currency": "brl", "description": "Plano Pro mensal", "metadata": {}, "position": 0, "price": "price_123", "price_data": null, "product": "prod_123", "quantity": 1, "recurring_interval": null, "recurring_interval_count": null, "unit_amount": 19990 } ], "livemode": true, "metadata": { "order_id": "id_456" }, "mode": "payment", "payment_data": null, "payment_method_collection": "always", "payment_method_options": { "credit_card": { "installments": { "has_interest": true, "max_count": 12 } } }, "payment_method_types": ["credit_card", "pix", "boleto"], "payment_status": "unpaid", "require_billing_address": false, "require_document": true, "require_phone": false, "status": "open", "submit_type": "auto", "subscription": null, "success_url": "https://meusite.com/sucesso", "template": null, "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f" } ``` Identificador da checkout session. Sempre `"checkout.session"`. Indica se o comprador pode inserir códigos de cupom na página hospedada. Desconto aplicado, em centavos. Soma dos `line_items`, em centavos, antes de descontos e impostos. Impostos aplicados, em centavos. Total cobrado, em centavos. Igual a subtotal − discount + tax. Override visual **cru** desta sessão sobre a identidade da organização. `null` quando a sessão herda 100% da organização. Cada campo presente sobrescreve só aquele campo; campo ausente vem `null` e herda. A mescla final é resolvida pela página hospedada, nunca aqui. Cor de destaque (botão/foco), hex `#RGB` ou `#RRGGBB`. `null` quando não sobrescrita. `pill`, `rounded`, `sharp` ou `null`. Cor de marca (painel/cabeçalho), hex `#RGB` ou `#RRGGBB`. `null` quando não sobrescrita. `system`, `inter`, `geist`, `bitter` ou `null`. `light`, `dark` ou `null`. URL para onde a Chargefy redireciona se o comprador abandonar a sessão. `null` quando não informado. String opaca de 64 caracteres hex, sem prefixo. Usada pela página hospedada para abrir a sessão sem precisar do token de API. Não é segredo de servidor — é runtime do browser. Data de criação em ISO 8601. Moeda em ISO 4217 minúsculo, como `brl`. Customer resolvido para a sessão. Vem `null` no create — a Chargefy resolve o customer só no confirm — e aparece preenchido a partir de `checkout.session.completed`. CPF ou CNPJ do comprador, apenas dígitos. Mesmo padrão de `customer_email`. Tipo do documento: `cpf`, `cnpj` ou `null`. Email do comprador. Pré-preenchido se enviado no create; senão `null`. Atualizado quando o comprador preenche o formulário. Nome do comprador. Mesmo padrão de `customer_email`. ID de um desconto pré-aplicado à sessão. `null` quando não houver. Data de expiração em ISO 8601. 24h depois do `created_at`. Quando `true` e a sessão é `mode=payment`, o pagamento bem-sucedido materializa uma invoice canônica. Sessões `mode=subscription` sempre materializam invoice via a assinatura, independentemente desse campo. Itens cobrados na sessão, com produto, preço e recorrência já resolvidos. Identificador do item. Desconto aplicado ao item, em centavos. Subtotal do item (`unit_amount` × `quantity`), em centavos. Impostos aplicados ao item, em centavos. Total do item, em centavos. Moeda do item em ISO 4217 minúsculo. Descrição do item exibida ao comprador. `null` quando não informada. Objeto livre do item. Quando vazio, retorna `{}`. Posição do item na sessão, começando em `0`. ID do preço do catálogo, quando o item veio de um preço cadastrado. `null` quando o valor foi informado ad-hoc. Dados de preço ad-hoc usados quando o item não aponta para um `price`. `null` quando o item veio do catálogo. ID do produto do catálogo, quando o item veio de um produto cadastrado. `null` em itens totalmente ad-hoc. Quantidade do item. Intervalo de recorrência (`day`, `week`, `month`, `year`) quando o item é recorrente. `null` em itens de cobrança única. Número de intervalos entre cada cobrança. `null` em itens de cobrança única. Valor unitário, em centavos. `true` em produção; `false` em ambiente de teste. Objeto livre para correlacionar a sessão com o seu sistema. Ecoado em todos os webhooks `checkout.session.*`. Quando vazio, retorna `{}`. `payment` (compra única) ou `subscription` (recorrente). É derivado dos `line_items`. Dados do pagamento expostos após o `confirm`, conforme o método escolhido. Vem `null` enquanto a sessão não foi confirmada. Código de barras do boleto. Presente apenas em `boleto`. Categoria da recusa em uma tentativa de `credit_card` malsucedida (`issuer_declined`, `invalid`, `blocked`, `processing_error`). `null` quando não houve recusa. Veja [Códigos de falha](/api-reference/charges/failure-codes). Código estável do motivo da recusa em uma tentativa de `credit_card` malsucedida (`insufficient_funds`, `expired_card`, …). `null` quando não houve recusa. Veja [Códigos de falha](/api-reference/charges/failure-codes). Linha digitável do boleto. Presente apenas em `boleto`. Data de vencimento do boleto em ISO 8601. Presente apenas em `boleto`. Data de expiração do PIX em ISO 8601. Presente apenas em `pix`. Número de parcelas. Presente apenas em `credit_card`. Método confirmado: `credit_card`, `pix` ou `boleto`. URL do PDF do boleto. Presente apenas em `boleto`. Código PIX (string EMV) para colar no app do banco. Presente apenas em `pix`. URL da imagem do QR Code PIX. Presente apenas em `pix`. Status do pagamento para esse método. Em sessões `subscription`, controla se o checkout coleta um método de pagamento quando não há cobrança no momento. `always` coleta sempre; `if_required` coleta apenas quando há valor devido agora. Opções por método de pagamento oferecidas na página hospedada. Opções do cartão de crédito. Configuração do parcelamento. `true` quando o comprador paga o acréscimo do parcelamento; `false` quando o lojista absorve o acréscimo. Número máximo de parcelas oferecidas (1–12). Métodos disponíveis para o comprador na página hospedada, como `["credit_card", "pix", "boleto"]`. Congelado no momento do create (snapshot imutável) e mantido idêntico em toda leitura — consulta, confirmação e webhooks da sessão refletem exatamente esse conjunto, mesmo que a política de checkout da organização mude depois. Vem vazio quando a organização ainda não concluiu o cadastro financeiro. `unpaid`, `paid` ou `no_payment_required` (total igual a zero). Para PIX e boleto permanece `unpaid` até a compensação assíncrona. Indica se o endereço de cobrança é exigido no formulário. Boleto sempre exige. Indica se o documento (CPF/CNPJ) do comprador é exigido no formulário. Boleto sempre exige. Indica se o telefone do comprador é exigido no formulário. `open` (criada, aguardando o comprador), `complete` (comprador confirmou) ou `expired` (24h sem confirmação — terminal). Tipo semântico do botão de finalização: `auto`, `pay`, `subscribe`, `book` ou `donate`. Controla a cópia do botão, que a página hospedada renderiza no idioma do comprador. `auto` escolhe a cópia pelo tipo da sessão. Subscription criada por uma sessão `mode=subscription`. Vem `null` antes da confirmação ou em sessões `mode=payment`. URL para onde a Chargefy redireciona o comprador após o pagamento confirmado. `null` quando não informado. Template explícito da sessão. `null` significa que a página hospedada usa o padrão da organização. Valores disponíveis: `minimal` e `booking`. URL da página hospedada da Chargefy. Redirecione o comprador para essa URL. ## Operações * [Criar checkout session](/api-reference/checkout-sessions/create) * [Consultar checkout session](/api-reference/checkout-sessions/get) * [Confirmar checkout session](/api-reference/checkout-sessions/confirm) ## Test helpers Em sandbox, você pode simular o resultado de uma `checkout.session` pelo ID da sessão. A Chargefy localiza o `payment_intent` associado, aplica a ação nele e retorna o objeto `payment_intent` completo atualizado. Test helpers só aceitam chaves `ch_test_...`; chamadas em live mode retornam erro `testmode_required`. | Ação | Endpoint | Resultado | | ------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | Succeed | `POST /v1/test-helpers/checkout-sessions/{id}/succeed` | Liquida o pagamento de teste, marca o intent como `succeeded` e emite os webhooks de sucesso. | | Fail | `POST /v1/test-helpers/checkout-sessions/{id}/fail` | Marca a tentativa como falha, registra o erro público no intent e emite os webhooks de falha. | | Expire | `POST /v1/test-helpers/checkout-sessions/{id}/expire` | Expira a sessão de teste, cancela o intent associado e emite os webhooks correspondentes. | ## Webhooks Mudanças nesse objeto disparam os seguintes eventos de webhook: * [`checkout.session.created`](/api-reference/webhooks/checkout.session.created) * [`checkout.session.completed`](/api-reference/webhooks/checkout.session.completed) * [`checkout.session.expired`](/api-reference/webhooks/checkout.session.expired) * [`checkout.session.async.payment.succeeded`](/api-reference/webhooks/checkout.session.async.payment.succeeded) * [`checkout.session.async.payment.failed`](/api-reference/webhooks/checkout.session.async.payment.failed) O payload sempre carrega o objeto `checkout.session` completo em `data.object`; eventos que alteram a sessão também incluem `data.previous_attributes` com os valores anteriores dos campos alterados.