Skip to main content
Uma checkout session é uma sessão temporária de compra. A Chargefy devolve url — a página hospedada onde o cliente paga, endereçada pelo id da sessão. Ela coleta os dados do comprador, mostra os métodos disponíveis e confirma a escolha dele. Diferente de um payment link (URL pública reutilizável), a session nasce para uma compra específica e expira em 24h. Ela não é o livro-razão financeiro da cobrança; o resultado do pagamento é acompanhado por payment_status, payment_intent quando fizer parte do fluxo, invoices quando aplicável e webhooks. Só line_items é obrigatório. mode é derivado dos itens (não é input) e expires_at é sempre criação + 24h. A experiência da página hospedada vem da marca e do Checkout Builder da organização, não deste payload.
Veja Ciclo de pagamento para entender a relação entre checkout sessions, payment intents, invoices e payment methods.
Trial gratuito não permite Pix ou boleto, inclusive quando esses métodos estão na configuração da organização. Forçar essa escolha na confirmação retorna payment_method_not_allowed. O mínimo de uma cobrança positiva é calculado pelo plano efetivo e pelo método, depois de descontos, juros e repasse; não pelo valor isolado de cada item.

​
Autenticação

Header Authorization: Bearer {{API_KEY}}. Escopo necessário: write.

​
Attributes

​
boolean
padrão:"false"
Quando true, a página hospedada desta sessão mostra o campo de código de desconto. Valor que não seja booleano retorna 400.
​
string
URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão “Voltar” na hosted page).
​
array
Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe price, title e call_to_action; aceita description, tag (recommended, special_offer ou null), product_name, image (arquivo com propósito order_bump_image) e compare_at_amount (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie id na criação.
​
string | null
Layout: split, sidebar ou stacked. Ausente ou null herda o padrão da organização na criação; o layout fica preservado na sessão.
​
object | null
Configuração da página. Omitir um campo preserva sua configuração; banner: null desliga o banner. checkout_experience: null restaura a herança da apresentação, coleta e trackeamento, limpa a capa, a descrição personalizada e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preç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.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
Referência sua para conciliar a sessão com o seu sistema — um ID de pedido ou de carrinho, por exemplo (order:2026/123 é válido). Até 200 caracteres imprimíveis; caracteres de controle ou tamanho fora do limite retornam 400. O valor volta no objeto da sessão e nos webhooks checkout.session.*.
​
string
CPF ou CNPJ do comprador (pré-preenche).
​
string
Tipo do documento. Envie junto de customer_document.
​
string
Email do comprador (pré-preenche o formulário da hosted page).
​
string
ID de um customer já existente na organização. Quando informado, fixa a sessão nesse cadastro. Se omitido, o confirm reutiliza o customer ativo mais antigo com o mesmo CPF/CNPJ, depois o mais antigo com o mesmo email, e cria outro apenas quando não encontra correspondência. A resolução é isolada por organização e ambiente.
​
string
Nome do comprador (pré-preenche).
​
string
ID de um desconto pré-aplicado da organização conectada alvo.
​
boolean
padrão:"false"
Quando true, 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. Vale para qualquer método escolhido pelo comprador, somente em cobrança avulsa: uma sessão com item recorrente não aceita repasse e a criação retorna 400. Veja Repassar a tarifa de venda ao comprador.
​
boolean
padrão:"false"
Quando true e a session é mode=payment, o pagamento bem-sucedido materializa uma invoice canônica. Padrão false — pagamentos one-shot não geram invoice. Sessions mode=subscription sempre materializam invoice via a assinatura, independente desse campo (passar false aqui em sub-mode é erro 400).
​
array
obrigatório
Array não-vazio de itens. Cada item descreve um produto/preço cobrado nessa sessão e inclui exatamente um entre price_id e price_data — os dois juntos ou nenhum retorna 400. Todos compartilham a mesma moeda e o mesmo tipo de cobrança. Quando forem recorrentes, todos também precisam usar exatamente o mesmo interval e interval_count. Aceita três formas — veja Três variantes.
​
object
Snapshot opcional de aquisição capturado pelo seu servidor. A primeira captura válida vence e permanece associada à sessão, inclusive em checkout.session.completed, checkout.session.expired e nos eventos assíncronos de pagamento.
​
object
Objeto livre string → string, opcional e definido pelo parceiro. É ecoado em todos os webhooks checkout.session.* correspondentes. Limite: 50 chaves, chave com 40 caracteres e valor com 500 caracteres.
​
string
padrão:"always"
Só válido em sessões mode=subscription — enviar em sessão payment retorna 400. Controla a coleta de cartão quando não há cobrança no momento da confirmação, como trial gratuito ou preço recorrente gratuito. Padrão: always.
​
object | null
padrão:"null"
Quem paga o juro do parcelamento nesta sessão, em credit_card.installments.interest_payer: buyer comprador, organization a própria organização — o comprador parcela o valor à vista e o juro sai do líquido dela. Omitido ou null herda a configuração de checkout da organização; o valor resolvido congela no snapshot da sessão. A quantidade de parcelas é escolha do comprador — enviar plan retorna 400.
​
array | null
Métodos que esta sessão aceita: credit_card, pix e boleto, sem repetição. Omitido ou null, copia os métodos padrão da organização (Checkout Builder). A lista enviada vale exatamente como está — ela pode ampliar ou restringir o padrão, e fica congelada na sessão: mudar o Builder depois não afeta sessões já criadas. Lista vazia, repetição ou valor desconhecido retornam 400.
​
string
padrão:"hosted"
Modo de apresentação da sessão, imutável após a criação. Hoje só hosted é aceito — o comprador paga na página da Chargefy em url. embedded (o checkout renderizado no seu site via SDK) retorna 400 até o runtime embedded existir; quando chegar, será pedido explicitamente aqui.
​
string
padrão:"auto"
Tipo semântico do botão de finalização. Controla a cópia do botão, que a hosted page renderiza no idioma do comprador. Use um valor explícito quando a transação for reserva (book) ou doação (donate).
​
object
Input transitório usado apenas quando a sessão é mode=subscription — enviar em sessão payment retorna 400. A session guarda esse snapshot para audit/debug, mas o estado durável de trial e de prazo fica na subscription criada no confirm. trial_period_days na raiz do body também retorna 400 — o campo mora aqui dentro.É por aqui que a intenção de contrato viaja: além do trial, o prazo (cancel_at, cancel_at_period_end) é aplicado à assinatura no momento em que ela nasce, antes do subscription.created — quem escuta o evento já recebe a data de término.
​
string
URL pra onde a Chargefy redireciona o cliente após a conclusão do checkout. Use o placeholder {CHECKOUT_SESSION_ID} quando sua página de retorno precisar consultar a sessão correta. Após o sucesso, o comprador pode redirecionar imediatamente ou aguardar o contador de 10 segundos. Esse fluxo não espera a entrega de checkout.session.completed: se sua aplicação ainda estiver liberando acesso, a página de destino deve consultar seu backend e manter o gate até o fulfillment terminar. Veja como combinar redirect, webhook e reconciliação em Após receber com um Checkout.
Quando criar campo na raiz vs. usar metadata? Tudo que é estrutural (com tipagem, validação, semântica concreta na Chargefy) é na raiz. metadata é livre, opcional, parceiro decide. Campos obrigatórios nunca moram em metadata.

​
O que a Chargefy resolve sozinha

Campos que você não envia — a Chargefy calcula e devolve prontos na resposta:
  • mode não é input: qualquer item recorrente → subscription; nenhum → payment.
  • expires_at é sempre created_at + 24h. Não é configurável.
  • amount_subtotal, amount_discount, amount_tax e amount_total são computados a partir dos line_items.
  • payment_status nasce unpaid — ou no_payment_required quando o total é zero.
  • url é gerada na criação; redirecione o comprador para ela.
  • ui_mode hoje é sempre hosted; embedded chega junto com o runtime embedded e será pedido explicitamente na criação.
  • Configuração da experiência — template, apresentação, banner, pós-venda, rastreamento, métodos, dados exigidos e parcelamento — é resolvida e congelada na criação. A marca, o suporte e os termos usam a configuração atual da organização.

​
Atribuição de marketing na criação

Quando seu servidor já recebeu as UTMs e os identificadores de clique, envie-os em marketing_attribution. A captura é first_touch: se a sessão já tiver um snapshot, uma abertura posterior da página hospedada não o substitui.
Se você não enviar esse objeto, marketing_attribution nasce null. A Chargefy ainda pode preencher o primeiro toque quando o comprador entra por um payment link ou abre a sessão hospedada com parâmetros de campanha.

​
line_items — três variantes

Cada item de line_items aceita exatamente uma destas três formas. Use a mais idiomática pro seu caso. Caminho mais curto — e também o menor request válido: só line_items. Resolve produto, valor e (se for o caso) recorrência automaticamente a partir do price_id.
cURL

​
(b) Produto do catálogo + preço ad-hoc

Reusa nome/descrição do produto cadastrado, mas com valor único pra essa sessão. Não cria preço novo no catálogo.
cURL

​
(c) Produto e preço ad-hoc

Nada vem do catálogo. Útil pra integrações headless que não cadastram produto.
cURL

​
Vários produtos na mesma sessão

Envie mais de um objeto em line_items. Neste exemplo, os dois produtos entram na mesma assinatura mensal; por isso, usam a mesma moeda, interval e interval_count.
cURL

​
Pagamento one-shot com invoice (invoice_creation)

Passe invoice_creation: true quando precisar de uma invoice canônica materializada no sucesso da cobrança — útil pra reconciliação contábil ou emissão fiscal a partir de um documento próprio. Sem o flag, mode=payment não gera invoice; mode=subscription sempre gera independentemente.
cURL

​
Recorrência

Em (a), basta o price_id apontar pra um preço com recurring preenchido — a sessão nasce em mode: subscription sem campos extras. Em (b) e (c), adicione price_data.recurring:
Para trial em checkout de assinatura, use subscription_data. A session guarda esse input como snapshot, mas a assinatura criada no confirm passa a ser a fonte de verdade (trial_start, trial_end, trial_settings). Por padrão, a hosted page coleta cartão quando a assinatura não tem cobrança no momento da confirmação (payment_method_collection: "always"), preparando a cobrança automática de ciclos pagos futuros. Para permitir concluir sem cartão quando nada é devido agora, envie payment_method_collection: "if_required".
Para vender com prazo, o mesmo subscription_data carrega a duração. A assinatura nasce já com a data de término, sem nenhuma ação posterior — não é preciso lembrar de cancelar depois.

​
Restrições do array

  • Todos os itens compartilham a mesma currency. Moedas divergentes retornam 400.
  • Ou todos os itens são recorrentes, ou nenhum é. Misturar one-shot com recorrente retorna 400.
  • Em uma sessão recorrente, todos os itens usam exatamente o mesmo interval e interval_count. Cadências diferentes retornam 400 em line_items.
  • Cada item tem exatamente um entre price_id ou price_data — os dois juntos ou nenhum retorna 400.
  • Quando price_data é usado, exatamente um entre product_id e product_data deve acompanhá-lo — os dois juntos ou nenhum retorna 400.
  • quantity é opcional (padrão 1, inteiro >= 1).

​
Marca e Checkout Builder

A aparência é definida uma vez na organização e a página hospedada lê a versão atual ao abrir: a identidade visual — logo, cores, fonte, tema e cantos — vem da marca, em Configurações → Marca, e o template, a exibição do produto e o resumo vêm do Checkout Builder, em Configurações → Checkout. As regras transacionais — meios de pagamento, campos exigidos e parcelamento — são copiadas do Builder para a sessão na criação e não mudam mais: a tela e o confirm aplicam exatamente o snapshot da sessão (payment_method_types pode sobrescrever os métodos por request). Veja Configurar sua página de checkout. O campo submit_type continua no request porque descreve a ação comercial desta compra — pagar, assinar, reservar ou doar — e não uma configuração do layout.

​
Resposta

​
string
ID da checkout session.
​
string
Sempre checkout.session.
​
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. = subtotal − discount + tax.
​
string | null
Eco do que veio no body.
​
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.
​
string | null
Sempre null em sessões hosted — a credencial da página hospedada é o próprio id, carregado por url. Voltará populado apenas no futuro ui_mode: "embedded", consumido pelo SDK.
​
string
ISO-8601.
​
string
Moeda em ISO 4217 minúsculo (ex: brl).
​
string | null
Vem null no create — a Chargefy resolve customer só no confirm (lazy). Aparece preenchido nos webhooks de checkout.session.completed em diante.
​
string | null
Mesmo padrão de customer_email.
​
string | null
Tipo do documento. Vem null quando não informado.
​
string | null
Pré-preenchido se enviado no body; senão null. Atualizado quando o comprador preenche o formulário.
​
string | null
Mesmo padrão de customer_email.
​
string | null
Eco do body.
​
string
ISO-8601. 24h depois do created_at.
​
boolean
Eco do body. true quando o comprador cobre a taxa da organização.
​
boolean
Eco do body (default false em mode=payment).
​
array
Snapshot dos itens da sessão (resolvido com produto/preço/recorrência conforme a variante usada).
​
boolean
Indica se a sessão foi criada em modo live.
​
object | null
Snapshot first_touch persistido para a sessão. Quando enviado no body, retorna com capture_point: "checkout_session_create". Quando não existe captura, retorna null. Veja o objeto Checkout Session para o shape completo.
​
object
Eco do body (default {}).
​
string
Modo da sessão, derivado dos line_items.
​
object | null
null no create. Aparece preenchido depois do confirm.
​
string | null
Payment Intent da sessão quando mode=payment. Vem null no create e sempre em sessões mode=subscription.
​
object
Quem paga o juro do parcelamento (credit_card.installments.interest_payer), congelado na sessão. Eco do body quando enviado; caso contrário, a configuração de checkout da organização na criação.
​
string
Política de coleta de cartão da sessão. Em sessões payment, o valor é always.
​
array
Métodos aceitos pela sessão — a lista efetiva, nunca null: o que você enviou no create ou, omitido, o padrão da organização no momento da criação.
​
string
Estado do pagamento da sessão.
​
string
Estado atual da sessão.
​
string
Eco do body (default auto).
​
string | null
Subscription criada por uma sessão mode=subscription. Vem null no create.
​
string | null
Eco do que veio no body.
​
string
Modo de apresentação, imutável. Hoje sempre hosted; embedded chega junto com o runtime embedded.
​
string
URL hospedada da Chargefy. Redirecione o comprador pra essa URL.

​
Próximo passo

Redirecione o comprador pra resposta.url. A Chargefy renderiza a página de pagamento, confirma o método escolhido e devolve o cliente em success_url ao final.
A página hospedada confirma a compra sozinha — endereçada e autorizada pelo id da sessão, que viaja na própria url. Seu servidor não cria nem confirma nenhuma movimentação interna de processamento para uma checkout session; acompanhe o resultado pelos webhooks checkout.session.*.

​
Erros

Você pode criar a sessão antes de concluir a ativação financeira da organização. Em modo live, o bloqueio acontece somente quando o comprador tenta pagar: se a organização ainda não puder receber, a confirmação retorna 409 organization_not_activated. O sandbox não aplica esse bloqueio.
​
object | null
Define os destinos de conversão desta experiência. mode aceita inherit (padrões da organização), custom (somente destinations) ou disabled (nenhum envio). custom exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. null restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.
​
integer | null
Máximo de parcelas oferecido ao comprador, entre 1 e 12; 1 permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. null restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva interest_payer e vice-versa. A sessão guarda o limite resolvido na criação.