Sessões de checkout
Criar uma sessão de checkout
Cria uma checkout session.
O valor de cada item e a soma de preço × quantidade devem caber em o teto da moeda (
Se você não enviar esse objeto,
Pagamento one-shot com invoice (
Passe
Para trial em checkout de assinatura, use
Para vender com prazo, o mesmo
A página hospedada confirma a compra sozinha — endereçada e autorizada pelo
999999999 na menor unidade em brl), antes de descontos e juros. Valores acima retornam 400 amount_too_large, com param indicando o campo ou a coleção de itens.
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.
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
HeaderAuthorization: Bearer {{API_KEY}}. Escopo necessário: write.
Attributes
null aceita a indicação por cupom válido ou pelo último clique válido de uma afiliada. Omitir na criação também aceita indicação; omitir na atualização preserva a escolha atual. [] desliga a indicação e uma lista define os afiliados explicitamente.Comissões de afiliados para vínculos ativos: cada item contém affiliation (aff_*) e
affiliate_fee_rate, inteiro de 1 a 10000 pontos-base (3000 = 30%).
Os percentuais incidem em paralelo sobre o valor líquido da venda antes das
comissões de afiliados; a soma não pode ultrapassar 10000. Até 8 afiliados em venda
direta ou 7 com plataforma. Envie [] para remover a seleção.
Veja Comissões de afiliados.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.URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão
“Voltar” na hosted page).
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 (em centavos, a menor unidade da moeda, 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.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.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, volta o redirecionamento ao padrão da organização 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.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 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.*.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.
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.Quando
true e a session é mode=payment, a compra paga ganha uma invoice
própria, já paga. Padrão false — sem o campo, o payment_intent é o único
documento da compra. Sessions mode=subscription sempre têm invoice pela
assinatura e ecoam true (passar false aqui em sub-mode é erro 400). A
seção “Pagamento one-shot com invoice”, abaixo, mostra quando a invoice nasce.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.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.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.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.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.Métodos que esta sessão aceita:
credit_card, pix e boleto, sem
repetição. A ordem da lista é a ordem em que o comprador vê os métodos, e o
primeiro já vem selecionado. Omitido ou null, copia os métodos padrão da
organização (Checkout Builder), na ordem definida lá.
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.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.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).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.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.O que a Chargefy resolve sozinha
Campos que você não envia — a Chargefy calcula e devolve prontos na resposta:modenão é input: qualquer item recorrente →subscription; nenhum →payment.expires_até semprecreated_at+ 24h. Não é configurável.amount_subtotal,amount_discount,amount_taxeamount_totalsão computados a partir dosline_items.payment_statusnasceunpaid— ouno_payment_requiredquando o total é zero.urlé gerada na criação; redirecione o comprador para ela.ui_modehoje é semprehosted;embeddedchega 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 emmarketing_attribution. A captura é first_touch: se a sessão já tiver um
snapshot, uma abertura posterior da página hospedada não o substitui.
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 deline_items aceita exatamente uma destas três formas. Use a mais idiomática pro seu caso.
(a) Preço do catálogo
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 emline_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 um documento próprio por
venda — útil pra reconciliação contábil ou emissão fiscal. Sem o flag,
mode=payment não gera invoice; mode=subscription sempre gera.
A invoice nasce só depois que o dinheiro é confirmado, uma por compra:
- Cartão aprovado: a invoice nasce na própria confirmação, já paga.
- Pix e boleto: nada nasce quando o código é gerado. A invoice aparece quando o pagamento compensa.
- Recusa ou sessão expirada sem pagamento: nenhuma invoice.
surcharge_amount)
quando a sessão tem has_surcharge. Juros de parcelamento ficam no
payment_intent, e a invoice registra o parcelamento em
payment_settings. O billing_reason é manual e subscription é null.
O comprador acessa a invoice pela hosted_invoice_url.
Você recebe invoice.created e invoice.paid, os dois com a invoice já paga e
sem ordem garantida entre eles. O ID chega também em invoice na session, no
payment.intent.succeeded e na charge. Estorno e disputa não alteram a invoice
paga: o estorno fica no payment_intent e na charge.
cURL
Recorrência
Em (a), basta oprice_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:
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".
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. Um item ou uma oferta do funil com outra moeda retorna400 currency_mismatch. - 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
intervaleinterval_count. Cadências diferentes retornam 400 emline_items. - Cada item tem exatamente um entre
price_idouprice_data— os dois juntos ou nenhum retorna 400. - Quando
price_dataé usado, exatamente um entreproduct_ideproduct_datadeve acompanhá-lo — os dois juntos ou nenhum retorna 400. quantityé opcional (padrão1, inteiro >= 1).
Retorno após o pagamento — três formas
checkout_experience.success_redirect decide quando o comprador segue para a
success_url depois do pagamento confirmado. Sem o campo, vale o padrão da
organização, definido em Configurações → Pagamentos → Checkout (automático em 10
segundos, se ela não o alterou). Sem success_url, o comprador permanece na
confirmação. Pix e boleto ainda pendentes nunca redirecionam.
(a) Imediatamente
delay_seconds: 0 leva o comprador direto do checkout para a success_url, sem
passar pela confirmação. Use quando a sua página já mostra o pedido.
cURL
(b) Depois de uma contagem
Mostra a confirmação, com o botão Redirecionar agora, e redireciona ao fim de 1 a 60 segundos.cURL
(c) Só quando o comprador clicar
manual mantém a confirmação na tela até o comprador tocar em Continuar.
Quem fecha a página não chega à success_url: não dependa dela para entregar o
pedido.
cURL
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, estilo, fontes e tema — vem da marca, em Configurações → Branding, e o template, a exibição do produto e o resumo vêm do Checkout Builder, em Configurações → Pagamentos → 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
Soma dos
line_items, na menor unidade da moeda (centavos em brl), antes de descontos e impostos.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.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.Vem
null no create — a Chargefy resolve customer só no confirm (lazy).
Aparece preenchido nos webhooks de checkout.session.completed em diante.Pré-preenchido se enviado no body; senão
null. Atualizado quando o comprador
preenche o formulário.ID da invoice da compra.
null na criação: ela só existe depois do
pagamento. Veja o objeto.Snapshot dos itens da sessão (resolvido com produto/preço/recorrência conforme
a variante usada).
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.Payment Intent da sessão quando
mode=payment. Vem null no create e sempre
em sessões mode=subscription.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.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.Modo de apresentação, imutável. Hoje sempre
hosted; embedded chega junto
com o runtime embedded.Próximo passo
Redirecione o comprador praresposta.url. A Chargefy renderiza a página de pagamento, confirma o método escolhido e devolve o cliente em success_url ao final.
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.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.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.
