Skip to main content
Uma checkout session é uma sessão temporária de compra. A Chargefy devolve url (página hospedada onde o cliente paga) e client_secret (lido pelo browser do comprador na hosted page). 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 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.

​
Autenticação

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

​
Attributes

​
boolean
default:"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).
​
string
Referência sua para conciliar a sessão com o seu sistema — um ID de pedido ou de carrinho, por exemplo. Até 200 caracteres com letras, números, - e _; fora desse formato a criação retorna 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
default:"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
default:"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
required
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. 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
default:"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.
​
string
default:"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. Se houver endpoint inscrito em checkout.session.completed, a Chargefy aguarda um 2xx por até 10 segundos antes do redirect e segue mesmo sem confirmação ao fim desse prazo. 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.
  • client_secret e url são gerados na criação; redirecione o comprador para url.
  • Configuração do checkout não é copiada para a sessão: a página hospedada usa a única 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.

​
(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.

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

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

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

​
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.
  • 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).

​
Checkout Builder

A aparência, os campos exigidos, os meios de pagamento, os descontos digitáveis e a apresentação do parcelamento são definidos uma vez em Configurações → Checkout. Eles não fazem parte do payload desta sessão. A página hospedada lê a configuração atual da organização quando é aberta, e o confirm usa a mesma política. Veja Checkout Builder. 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.
​
string
String opaca de 64 caracteres hex, sem prefixo. Usada pela hosted page pra abrir a sessão sem precisar do token de API. Não é segredo de servidor — é runtime do browser.
​
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
Política de coleta de cartão da sessão. Em sessões payment, o valor é always.
​
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
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.
O frontend da hosted page chama POST /v1/checkout-sessions/public/:client_secret/confirm sozinho. Seu servidor não precisa criar nem confirmar uma movimentação interna de processamento para uma checkout session.

​
Erros

Uma organização precisa estar apta a receber pagamentos para criar a sessão. Os meios oferecidos ao comprador são os que estiverem ativos no Checkout Builder no momento em que a página for carregada.