Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt

Use this file to discover all available pages before exploring further.

Uma checkout session é uma tentativa única de pagamento. Você cria a sessão pela API, leva o cliente pra página hospedada da Chargefy (ou pro seu próprio frontend), e recebe webhook quando ele paga. Diferente de um payment link (URL pública reutilizável), a session nasce ligada a um buying attempt específico — 1 cliente, 1 tentativa, expira em 24h.

​
Fluxo

1

Criar a sessão

Server-side, com sua API key. Devolve url (hosted page), client_secret (pra leitura no browser) e o DTO completo.Veja POST /v1/checkout-sessions.
2

Levar o cliente

Redirecione pra response.url. A Chargefy renderiza form, processa pagamento, e devolve o cliente em success_url.
window.location.assign(response.url)
3

Confirm (automático na hosted page)

O frontend da Chargefy chama POST .../public/:client_secret/confirm sozinho. Você não precisa fazer essa chamada — está documentada caso esteja construindo seu próprio frontend.
4

Webhooks

Sua org recebe os eventos checkout.session.* que você assinou. Trate completed (pedido fechado) + async_payment_succeeded (PIX/boleto creditado) pra liberar o produto.

​
Como descrever o que cobrar

line_items aceita três formas. Use a mais idiomática pro seu caso. Documentação completa em POST /v1/checkout-sessions.
FormaQuando usar
price_id do catálogoVocê cadastrou produtos+preços no dashboard. Mais curto.
price_data + product_id do catálogoReusa produto cadastrado, valor único nessa sessão (sem poluir o catálogo).
price_data + product_data ad-hocHeadless — nada vem do catálogo.
Recorrência: se o price_id apontar pra um preço com interval, a sessão nasce em mode: subscription automaticamente. Em price_data, basta adicionar recurring: { interval, interval_count? }.

​
Métodos de pagamento

Quais métodos aparecem na hosted page é determinado pelo cadastro financeiro da sua organização. A resposta da criação inclui payment_method_types: ["credit_card", "pix", "boleto"] indicando o que está disponível. Lista vazia significa cadastro não concluído — a sessão nasce mas o comprador não consegue pagar.
MétodoConfirmaçãoLatência típica
Cartão de créditoSíncrona — autoriza no confirmImediato
PIXAssíncrona — comprador paga via app, PSP confirmaSegundos a minutos
BoletoAssíncrona — comprador paga em banco, compensação1–3 dias úteis

​
Status

statusSignificado
openCriada, aguardando comprador preencher e confirmar
completeComprador confirmou. Cartão = aprovado. PIX/boleto = aguarda async
expired24h sem confirm. Terminal
payment_status evolui: unpaid → paid (ou permanece unpaid se PIX/boleto não compensar).

​
Tracking de pedido

Use metadata pra correlacionar com seu sistema. Bag de string→string, livre, ecoada em todos os webhooks checkout.session.* daquela sessão. 
"metadata": {
  "order_id": "ord_123",
  "campaign": "blackfriday-2026"
}
metadata é livre, opcional, decidido pelo parceiro. Campos obrigatórios nunca moram em metadata — se algo é obrigatório, vira top-level com tipagem (ex: customer_email, success_url).

​
Customer (lazy)

Você não precisa criar customer antes da sessão. A Chargefy resolve no momento do confirm — usando email + CPF/CNPJ informados pelo comprador. Customer existente é reaproveitado; novo é criado on-demand. Se você já tem o customer, passe customer_id no body do create — a sessão referencia direto. O customer_id resolvido aparece em checkout.session.completed em diante.

​
Próximos passos