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 e
aparência), 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.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:
Data Object
Este é o formato completo retornado emcreate, 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.
Escolha da oferta:
inherit aceita indicação por cupom ou clique, explicit usa a lista definida e none desliga a indicação automática. affiliates continua trazendo a divisão efetivamente registrada.Condições de comissão de afiliado registradas: cada item contém
affiliation e
affiliate_fee_rate em pontos-base; [] indica ausência de comissão de afiliado.
Esta seleção não comprova recebimento: o pagamento registra o resultado de
cada participante. Encerrar uma parceria retira sua participação nas
próximas cobranças e preserva os valores e as parcelas já divididos.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.Soma dos
line_items, na menor unidade da moeda (centavos em brl), antes de descontos e impostos.Total cobrado, na menor unidade da moeda (centavos em
brl). Igual a subtotal − discount + tax.URL para onde a Chargefy redireciona se o comprador abandonar a sessão.
null
quando não informado.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.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. success_redirect informa quando o comprador segue para a success_url: { "delay_seconds": 10, "type": "automatic" } redireciona ao fim da contagem, delay_seconds: 0 leva direto do checkout sem a confirmação, e { "delay_seconds": null, "type": "manual" } espera o clique em Continuar. A sessão sempre traz o valor que vale para ela, vindo do link, da criação pela API ou do padrão da organizaçã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.Por exemplo,
show_phone: true com require_phone: false exibe WhatsApp opcional. Com os dois em true, o comprador precisa preenchê-lo. Com os dois em false, o campo fica oculto. Campos obrigatórios continuam visíveis, mesmo com show_*: false.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.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.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.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.Email do comprador. Pré-preenchido se enviado no create; senão
null.
Atualizado quando o comprador preenche o formulário.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.ID da invoice da compra (
inv_). Numa sessão mode=payment criada com
invoice_creation: true, é a invoice paga que nasce quando o pagamento é
confirmado. Numa sessão mode=subscription, é a primeira invoice da
assinatura: no cartão, nasce paga com a aprovação e já vem no
checkout.session.completed. Fica null até a invoice existir: em Pix e
boleto, checkout.session.completed sai com invoice: null e
checkout.session.async.payment.succeeded já sai preenchido.Quando
true e a sessão é mode=payment, a compra paga ganha uma invoice
própria, já paga, com os itens, o desconto e o comprador da sessão (veja
invoice). Nenhuma invoice nasce antes do pagamento nem para tentativa
recusada. Sessões mode=subscription sempre têm invoice pela assinatura e
ecoam true.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.Objeto livre para correlacionar a sessão com o seu sistema. Ecoado em todos os
webhooks
checkout.session.*. Quando vazio, retorna {}.Dados do pagamento expostos após o
confirm, conforme o método escolhido.
Vem null enquanto a sessão não foi confirmada.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.Em sessões
subscription, controla se o checkout coleta um método de
pagamento quando não há cobrança no momento.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.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.Estado do pagamento da sessão. Para Pix e boleto permanece
unpaid até a
compensação assíncrona. Depois de gerar o Pix, o comprador pode pagar com
cartão na mesma página: a sessão continua complete e passa a paid quando
o cartão é aprovado.A sessão é dona do ciclo de vida do payment intent
A sessão e opayment_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. - Depois de um Pix, a sessão fica
completecompayment_status: "unpaid"e ainda aceita o cartão até o prazo dela. A tentativa do Pix é encerrada compayment_error.code: "payment_method_switched"antes do cartão, mas o código continua pagável até vencer: pago antes do cartão, ele paga a compra; pago depois, é devolvido sozinho comreason: "duplicate". Voltar ao Pix antes de vencer mostra o mesmo código. - Depois de um boleto numa compra avulsa (
mode: "payment", sem fatura nem funil), a sessão também ficacompleteeunpaide aceita cartão ou Pix até o prazo dela. A tentativa do boleto é encerrada do mesmo jeito, compayment_method_switched, e o boleto continua pagável até vencer. Em assinatura, em funil ou com cancelamento do boleto pedido, a sessão continua reservada ao boleto. - Quando a sessão vira
expired, o intent em andamento é cancelado comcancellation_reason: "expired". - Por isso não se cancela esse intent direto:
POST /v1/payment-intents/:id/cancel
responde
409e indica qual sessão expirar. A única exceção érequires_capture, em que existe valor autorizado no cartão para liberar.
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.
Subscription criada por uma sessão
mode=subscription. No cartão, ela nasce
quando a primeira cobrança é aprovada, já active e com a primeira invoice
paga; um cartão recusado não cria subscription nem invoice, e a sessão segue
aberta para outra tentativa. Em Pix e boleto, nasce incomplete quando o
código é gerado e fica active quando ele é pago. Se o comprador gerar o Pix
e pagar com cartão, a mesma subscription fica active, passa a cobrar
automaticamente no cartão (collection_method: "charge_automatically") e o
guarda como default_payment_method. Trial e cupom de 100%
criam a subscription na conclusão. Use o valor do checkout.session.completed.
null antes disso e em sessões mode=payment.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.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.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, preenchacustomer_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:checkout.session.createdcheckout.session.completedcheckout.session.expiredcheckout.session.async.payment.succeededcheckout.session.async.payment.failed
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.
Revisão dos itens da compra. O checkout usa este valor para impedir que uma seleção desatualizada seja cobrada.
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.
