Pular para o conteúdo principal
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 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.
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:
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.
string
obrigatório
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.
array
obrigatório
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.
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, na menor unidade da moeda (centavos em brl).
integer
Soma dos line_items, na menor unidade da moeda (centavos em brl), antes de descontos e impostos.
integer
Impostos aplicados, na menor unidade da moeda (centavos em brl).
integer
Total cobrado, na menor unidade da moeda (centavos em brl). 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. 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.
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.
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.
string | null
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.
boolean
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.
array
Itens cobrados na sessão, com produto, preço e recorrência já resolvidos.
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.
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.
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.
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.
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. 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.
string
Estado atual da sessão.

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.
  • Depois de um Pix, a sessão fica complete com payment_status: "unpaid" e ainda aceita o cartão até o prazo dela. A tentativa do Pix é encerrada com payment_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 com reason: "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 fica complete e unpaid e aceita cartão ou Pix até o prazo dela. A tentativa do boleto é encerrada do mesmo jeito, com payment_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 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.
string | null
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.
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.