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 da Chargefy, endereçada pelo id da sessão (ui_mode: "hosted"). Os métodos de pagamento, os dados exigidos do comprador e a política de parcelamento são congelados na criação, assim como o template, a exibição dos produtos, o banner, o pós-venda e os destinos de rastreamento. A marca da organização (logo, cores, fonte, tema e cantos), o suporte e os termos permanecem compartilhados e atuais. 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/cs_3cv3LYf5YMF91kvr

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",
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": true,
    "header_shows_name": true,
    "installment_teaser_mode": "maximum_installment",
    "order_summary_mode": "expanded",
    "product_description": null,
    "product_description_mode": "summary",
    "product_image_mode": "thumbnail",
    "product_subtitle_source": "description",
    "require_billing_address": false,
    "require_document": true,
    "require_phone": false,
    "show_compare_at_amount": false,
    "summary_style": "product",
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "client_reference_id": null,
  "client_secret": null,
  "composition_revision": 0,
  "created_at": "2026-05-03T18:31:00Z",
  "currency": "brl",
  "customer": "cus_KLxbi41dK5j2cPbX",
  "customer_document": "12345678901",
  "customer_document_type": "cpf",
  "customer_email": "[email protected]",
  "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": {},
      "optional_item": null,
      "position": 0,
      "price": "price_t61Ft1kSr3hX2Y9L",
      "price_data": null,
      "product": "prod_ZJ8tiZb4t1RyTVq6",
      "quantity": 1,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "role": "main",
      "unit_amount": 19990
    }
  ],
  "livemode": true,
  "marketing_attribution": {
    "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",
  "optional_items": [],
  "payment_data": {
    "installments": 3,
    "payment_method": "credit_card",
    "status": "succeeded"
  },
  "payment_intent": null,
  "payment_method_collection": "always",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "interest_payer": "buyer",
        "max_count": 12
      }
    }
  },
  "payment_method_types": [
    "credit_card",
    "pix"
  ],
  "payment_status": "paid",
  "status": "complete",
  "submit_type": "auto",
  "subscription": "sub_jTHQAyZTtPaWuKPP",
  "success_url": "https://meusite.com/sucesso",
  "template": "split",
  "ui_mode": "hosted",
  "url": "https://pay.chargefy.io/session/cs_3cv3LYf5YMF91kvr"
}

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.

array

Ofertas adicionais na ordem de exibição. Aceitá-las materializa itens de linha com role: "bump"; o cupom alcança somente os itens principais. Os extras são cobrados uma única vez, inclusive durante o trial, e não entram nas renovações. Cada oferta contém o preço e a apresentação congelados, selected e a referência line_item. Alterações posteriores no link ou no produto não mudam esta sessão.

object

show_compare_at_amount habilita o valor de referência riscado, cadastrado no preço. Padrão false. O estilo offer destaca o produto em uma linha horizontal, com product_subtitle_source escolhendo descrição ou organização na segunda linha. cover_image_url é uma imagem de campanha independente acima do produto; product_image_mode controla somente a imagem do produto. Configuração da página. banner é nulo quando desligado, ou contém variant, text, tone, tag, highlight, duration_minutes, duration_seconds, ends_at e background_color. O banner é copiado do link na criação da sessão; mudanças posteriores no link não alteram sessões abertas. A mensagem não modifica as condições de cobrança. confirmation_message é a mensagem personalizada exibida após a conclusão da compra, ou null; a sessão conserva o texto do momento de sua criação. funnel é a referência ao funil escolhido, ou null. A sessão conserva essa escolha; após pagamento elegível confirmado, o funil precede success_url. Desativar o funil impede novas ofertas e preserva a compra original. footer_expanded indica se o checkout exibe suporte e termos da organização; é copiado do link na criação da sessão.Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, null herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.

Campo	Valores
`summary_style`	`product`, `subscription`, `offer` ou `null`
`product_image_mode`	`hidden`, `thumbnail`, `hero` ou `null`
`product_subtitle_source`	`description`, `organization` ou `null`; `null` herda o padrão da organização
`cover_image_url`	URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa
`product_description`	Texto exclusivo do checkout, até 2.000 caracteres. `null` usa a descrição do produto; `""` não exibe descrição. Não altera o catálogo.
`product_description_mode`	`hidden`, `summary`, `full` ou `null`
`order_summary_mode`	`expanded`, `collapsible`, `compact`, `hidden` ou `null`
`installment_teaser_mode`	`hidden`, `maximum_installment`, `lowest_installment` ou `null`
`header_shows_logo`	Booleano ou `null`; exibe o avatar
`header_shows_name`	Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão
`require_document`, `require_phone`, `require_billing_address`	Booleano ou `null`

Os campos pertencem a checkout_experience. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é false. Cores, fonte e arquivo do logo continuam na marca da organização.

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 | null

Credencial do futuro ui_mode: "embedded", consumida pelo SDK. Sempre null em sessões hosted — lá a credencial é o próprio id, carregado por url. As duas credenciais nunca aparecem juntas.

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.

Mostrar 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.

Mostrar Campos de marketing_attribution

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.

Mostrar 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 | null

Payment Intent criado por uma sessão mode=payment. Vem null antes da criação da cobrança e sempre em sessões mode=subscription.

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.

object

Quem paga o juro do parcelamento nesta sessão, em credit_card.installments.interest_payer (buyer ou organization). Snapshot congelado na criação: resolvido payment link → configuração de checkout da organização no clique, ou informado diretamente no create. É a política que precificou as opções de parcelamento e a mesma que a confirmação cobra — mudar o link ou o Builder depois não reprecifica a sessão.

array

Métodos que o comprador pode usar nesta sessão (credit_card, pix, boleto). Snapshot congelado na criação: por padrão copia a configuração atual da organização, e o create pode sobrescrever por sessão. Mudanças na configuração da organização não afetam sessões já criadas.

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

Modo de apresentação da sessão, imutável após a criação. hosted (padrão): o comprador paga na página da Chargefy em url. embedded (em breve): o checkout renderiza no seu site via SDK, autorizado por client_secret.

string

URL da página hospedada da Chargefy, endereçada pelo id da sessão. Redirecione o comprador para ela. Como o endereço é autossuficiente, o comprador pode abri-lo em outro navegador ou aparelho e continuar a mesma compra — útil quando ele quer pagar o Pix pelo celular ou repassar a compra para quem paga. Vale enquanto a sessão puder ser vista e é uma credencial: quem tem o endereço age como o comprador naquela sessão. 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.

integer

Revisão dos itens da compra. O checkout usa este valor para impedir que uma seleção desatualizada seja cobrada.

object

mode indica inherit, custom ou disabled; destinations contém as referências de destinos selecionados. No link, as referências representam suas escolhas explícitas. Na sessão, representam a seleção efetiva congelada na criação. Desativar um destino na organização continua interrompendo seus envios.

string

Layout preservado na criação: split, sidebar ou stacked.

integer | null

Limite de parcelas. No link, null herda a organização; na sessão, é o limite resolvido e congelado na criação. interest_payer também pode ser null no link quando apenas o limite é personalizado.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

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