Sessões de checkout

Uma checkout.session representa uma única tentativa de compra. Ela nasce com seus itens e valores e devolve uma url para a página hospedada e um client_secret para o browser do comprador. A apresentação e a política de coleta não são armazenadas neste objeto: o checkout usa a configuração atual da organização. 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 — o Payment Intent registra o estado da cobrança, e payment_status projeta esse resultado na session. 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.

Regenerar PIX ou boleto na mesma session mantém a compra e o Payment Intent, mas cria outra Charge para a nova tentativa. Se a nova Charge pagar, payment_status muda para paid e não volta para unpaid quando a tentativa antiga expirar ou falhar depois.

O termo session representa o contexto transacional da página hospedada: itens, total, comprador e URLs de retorno. Você cria a sessão no servidor, recebe uma url como a abaixo e redireciona o comprador:

https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f

Use checkout session quando o comprador precisa passar por uma experiência completa de pagamento hospedada: venda única, checkout de assinatura, PIX ou boleto com instruções, ou cobrança de cartão com parcelamento. Se você precisa de um link público reutilizável, use Payment Links.

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. marketing_attribution contém o primeiro contexto de aquisição capturado para a sessão e permanece null até existir uma captura.

{
  "id": "cs_3cv3LYf5YMF91kvr",
  "object": "checkout.session",
  "allow_discount_codes": false,
  "amount_discount": 2000,
  "amount_subtotal": 19990,
  "amount_tax": 0,
  "amount_total": 17990,
  "cancel_url": "https://meusite.com/cancelado",
  "client_reference_id": null,
  "client_secret": "28c1521221ae82e1b5773a92d9140785c78a817ac8128a233f44e67a22443eb4",
  "created_at": "2026-05-03T18:31:00Z",
  "currency": "brl",
  "customer": "cus_KLxbi41dK5j2cPbX",
  "customer_document": "12345678901",
  "customer_document_type": "cpf",
  "customer_email": "nome@email.com",
  "customer_name": "Cliente Exemplo",
  "discount": "disc_WKLVWKbfE7d5LYhv",
  "expires_at": "2026-05-04T18:31:00Z",
  "has_surcharge": false,
  "invoice_creation": false,
  "line_items": [
    {
      "id": "li_DNGgw8VAc62BgCxP",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 2000,
      "amount_subtotal": 19990,
      "amount_tax": 0,
      "amount_total": 17990,
      "currency": "brl",
      "description": "Plano Pro mensal",
      "metadata": {},
      "position": 0,
      "price": "price_t61Ft1kSr3hX2Y9L",
      "price_data": null,
      "product": "prod_ZJ8tiZb4t1RyTVq6",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "unit_amount": 19990
    }
  ],
  "livemode": true,
  "marketing_attribution": {
    "attribution_id": "campaign-order-123",
    "capture_point": "checkout_session_create",
    "captured_at": "2026-05-03T18:31:00Z",
    "click_ids": {
      "fbclid": null,
      "gbraid": null,
      "gclid": null,
      "msclkid": null,
      "ttclid": null,
      "wbraid": null
    },
    "landing_page_url": "https://meusite.com/oferta",
    "meta": {
      "fbc": null,
      "fbp": null
    },
    "model": "first_touch",
    "referrer_url": "https://conteudo.exemplo/anuncio",
    "source": "paid_social",
    "utm": {
      "id": "spring_launch_2026",
      "campaign": "lancamento_2026",
      "content": "video_a",
      "creative_format": "video",
      "marketing_tactic": "remarketing",
      "medium": "paid_social",
      "source": "paid_social",
      "source_platform": "feed",
      "term": "checkout"
    }
  },
  "metadata": {},
  "mode": "subscription",
  "payment_data": {
    "installments": 3,
    "payment_method": "credit_card",
    "status": "succeeded"
  },
  "payment_method_collection": "always",
  "payment_status": "paid",
  "status": "complete",
  "submit_type": "auto",
  "subscription": "sub_jTHQAyZTtPaWuKPP",
  "success_url": "https://meusite.com/sucesso",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f"
}

string

Identificador da checkout session.

string

Sempre "checkout.session".

boolean

Se a página hospedada desta sessão mostra o campo de código de desconto. Snapshot do payment link de origem ou do valor enviado no create. Padrão: false.

integer

Desconto aplicado, em centavos.

integer

Soma dos line_items, em centavos, antes de descontos e impostos.

integer

Impostos aplicados, em centavos.

integer

Total cobrado, em centavos. Igual a subtotal − discount + tax.

string | null

URL para onde a Chargefy redireciona se o comprador abandonar a sessão. null quando não informado.

string | null

Referência do integrador anexada no create da sessão ou pela URL do payment link (?client_reference_id=…). null quando não informada. Ecoada nos webhooks checkout.session.* para conciliação.

string

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.

string

Data de criação em ISO 8601.

string

Moeda em ISO 4217 minúsculo, como brl.

string | null

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.

string | null

CPF ou CNPJ do comprador, apenas dígitos. Mesmo padrão de customer_email.

string | null

Tipo do documento. Vem null quando não informado.

Valor	Descrição
`cpf`	Documento de pessoa física.
`cnpj`	Documento de pessoa jurídica.

string | null

Email do comprador. Pré-preenchido se enviado no create; senão null. Atualizado quando o comprador preenche o formulário.

string | null

Nome do comprador. Mesmo padrão de customer_email.

string | null

ID de um desconto pré-aplicado à sessão. null quando não houver.

string

Data de expiração em ISO 8601. 24h depois do created_at.

boolean

true quando o comprador cobre a taxa da organização: o total é acrescido do repasse para que a organização receba líquido o valor da venda. Herdado do payment link quando a sessão nasce de um clique; enviável diretamente no create. Veja Repassar a tarifa de venda ao comprador.

boolean

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.

array

Itens cobrados na sessão, com produto, preço e recorrência já resolvidos.

Show Campos de cada line_item

string

Identificador do item.

integer

Desconto aplicado ao item, em centavos.

integer

Subtotal do item (unit_amount × quantity), em centavos.

integer

Impostos aplicados ao item, em centavos.

integer

Total do item, em centavos.

string

Moeda do item em ISO 4217 minúsculo.

string | null

Descrição do item exibida ao comprador. null quando não informada.

object

Objeto livre do item. Quando vazio, retorna {}.

integer

Posição do item na sessão, começando em 0.

string | null

ID do preço do catálogo, quando o item veio de um preço cadastrado. null quando o valor foi informado ad-hoc.

object | null

Dados de preço ad-hoc usados quando o item não aponta para um price. null quando o item veio do catálogo.

string | null

ID do produto do catálogo, quando o item veio de um produto cadastrado. null em itens totalmente ad-hoc.

integer

Quantidade do item.

string | null

Intervalo de recorrência quando o item é recorrente. null em itens de cobrança única.

Valor	Descrição
`day`	Intervalo diário.
`week`	Intervalo semanal.
`month`	Intervalo mensal.
`year`	Intervalo anual.

integer | null

Número de intervalos entre cada cobrança. null em itens de cobrança única.

integer

Valor unitário, em centavos.

boolean

true em produção; false em ambiente de teste.

object | null

Primeiro contexto de aquisição capturado para a sessão. Retorna null quando nenhum dado foi enviado na criação e a página hospedada ainda não registrou a origem. Depois da primeira captura, o objeto é imutável para aquela sessão.

Show Campos de marketing_attribution

string | null

Identificador de correlação definido pelo parceiro. Não identifica um recurso da API.

string

Fronteira que persistiu o primeiro toque.

Valor	Descrição
`checkout_session_create`	Dados enviados em `POST /v1/checkout-sessions`.
`checkout_session_open`	Primeira abertura direta da página hospedada.
`payment_link_redirect`	Entrada por um payment link.

string

Momento da captura em ISO 8601.

object

Identificadores de clique disponíveis na entrada. Todas as chaves declaradas (fbclid, gbraid, gclid, msclkid, ttclid e wbraid) aparecem; valores ausentes retornam null.

string | null

Origem e caminho da landing page. Query string e fragmento não são persistidos.

object

Valores fbc e fbp quando disponíveis; cada chave retorna null quando ausente.

string

Sempre first_touch nesta versão: a primeira captura válida vence.

string | null

Origem e caminho do referrer. Query string e fragmento não são persistidos.

string

Fonte normalizada. Usa utm.source quando presente; caso contrário, deriva o canal de um identificador de clique conhecido e retorna direct quando não há sinal de campanha.

object

Snapshot com campaign, content, creative_format, id, marketing_tactic, medium, source, source_platform e term. Todas as chaves aparecem e valores ausentes retornam null.

object

Objeto livre para correlacionar a sessão com o seu sistema. Ecoado em todos os webhooks checkout.session.*. Quando vazio, retorna {}.

string

Modo da sessão. É derivado dos line_items.

Valor	Descrição
`payment`	Compra única.
`subscription`	Cobrança recorrente.

object | null

Dados do pagamento expostos após o confirm, conforme o método escolhido. Vem null enquanto a sessão não foi confirmada.

Show Campos de payment_data

string | null

Código de barras do boleto. Presente apenas em boleto.

string | null

Categoria da recusa em uma tentativa de credit_card malsucedida. null quando não houve recusa. Veja Códigos de falha.

Valor	Descrição
`issuer_declined`	O banco emissor recusou (saldo, validade, bloqueio, limite).
`invalid`	Dados do cartão incorretos.
`blocked`	Recusa por restrição ou suspeita de fraude.
`processing_error`	Falha técnica ou de conectividade na rede.

string | null

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.

string | null

Linha digitável do boleto. Presente apenas em boleto.

string | null

Data de vencimento do boleto em ISO 8601. Presente apenas em boleto.

string | null

Data de expiração do PIX em ISO 8601. Presente apenas em pix.

integer | null

Número de parcelas. Presente apenas em credit_card.

string

Método confirmado pelo comprador.

Valor	Descrição
`credit_card`	Cartão de crédito.
`pix`	PIX.
`boleto`	Boleto bancário.

string | null

URL do PDF do boleto. Presente apenas em boleto.

string | null

Código PIX (string EMV) para colar no app do banco. Presente apenas em pix.

string | null

URL da imagem do QR Code PIX. Presente apenas em pix.

string

Status do pagamento para esse método.

string

Em sessões subscription, controla se o checkout coleta um método de pagamento quando não há cobrança no momento.

Valor	Descrição
`always`	Coleta o método de pagamento mesmo sem cobrança no momento.
`if_required`	Coleta apenas quando há valor devido na confirmação.

string

Estado do pagamento da sessão. Para PIX e boleto permanece unpaid até a compensação assíncrona.

Valor	Descrição
`unpaid`	Pagamento ainda não compensado.
`paid`	Pagamento confirmado.
`no_payment_required`	Não há valor devido (total igual a zero).

string

Estado atual da sessão.

Valor	Descrição
`open`	Criada, aguardando o comprador.
`complete`	O comprador confirmou a sessão.
`expired`	Expirou após 24h sem confirmação, ou foi expirada por POST /v1/checkout-sessions/:id/expire (estado terminal).

A sessão é dona do ciclo de vida do payment intent

A sessão e o payment_intent dela são uma única tentativa de compra: a sessão é o que o comprador usa, e o intent existe para servi-la. Quem encerra a tentativa, portanto, é a sessão.

Enquanto a sessão está open, o intent fica aberto. É isso que permite ao comprador voltar ao link, trocar de meio de pagamento ou pedir um novo código PIX dentro do prazo.
Quando a sessão vira expired, o intent em andamento é cancelado com cancellation_reason: "expired".
Por isso não se cancela esse intent direto: POST /v1/payment-intents/:id/cancel responde 409 e indica qual sessão expirar. A única exceção é requires_capture, em que existe valor autorizado no cartão para liberar.

string

Tipo semântico do botão de finalização. Controla a cópia do botão, que a página hospedada renderiza no idioma do comprador.

Valor	Descrição
`auto`	Escolhe a cópia pelo tipo da sessão.
`pay`	Botão de pagamento.
`subscribe`	Botão de assinatura.
`book`	Botão de reserva.
`donate`	Botão de doação.

string | null

Subscription criada por uma sessão mode=subscription. Vem null antes da confirmação ou em sessões mode=payment.

string | null

URL para onde a Chargefy redireciona o comprador após a conclusão do checkout. O placeholder {CHECKOUT_SESSION_ID}, quando presente, é substituído pelo ID da sessão. null quando não informado.

string

URL da página hospedada da Chargefy. Redirecione o comprador para essa URL. Aceita o parâmetro opcional ?locale= (pt-BR ou en-US; atalhos pt e en) para definir o idioma da página; valor inválido é ignorado.

Operações

Testar em sandbox

Para PIX e boleto, preencha customer_email com um dos e-mails de teste do sandbox. Cenários delayed começam com payment_status: "unpaid" e emitem o webhook assíncrono correspondente quando o resultado muda.

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

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.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Sessões de checkout

Data Object

A sessão é dona do ciclo de vida do payment intent

Operações

Testar em sandbox

Eventos

​Data Object

​A sessão é dona do ciclo de vida do payment intent

​Operações

​Testar em sandbox

​Eventos

Data Object

A sessão é dona do ciclo de vida do payment intent

Operações

Testar em sandbox

Eventos