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.

Endpoint público de confirmação. Usado pelo browser do comprador (na hosted page ou no seu frontend custom) pra finalizar o pagamento. A sessão transiciona de status: "open" pra status: "complete". Para PIX e boleto, complete significa que o comprador fechou o form — o pagamento real chega de forma assíncrona via webhook checkout.session.async_payment_succeeded. Para cartão, a transação é processada síncrona aqui mesmo.

​
Autenticação

Nenhuma. O client_secret na URL é a credencial.

​
Corpo

​
payment_method
string
required
Um de: pix, boleto, credit_card. Deve estar incluído em payment_method_types da sessão (caso contrário 400).
​
customer_email
string
required
Email do comprador. Obrigatório se ainda não estiver preenchido na sessão.
​
customer_name
string
required
Nome completo.
​
customer_tax_id
string
required
CPF ou CNPJ.
​
customer_billing_address
object
Endereço de cobrança. Obrigatório se a sessão tem require_billing_address: true.
​
boleto_due_date
string
Data de vencimento do boleto (YYYY-MM-DD). Default: 3 dias depois da confirmação. Aplica só quando payment_method: "boleto".
​
card_id
string
Token do cartão tokenizado. Obrigatório quando payment_method: "credit_card". Veja tokenização abaixo.
​
installments
integer
default:"1"
Número de parcelas (1–12). Aplica só com credit_card.
​
card_brand
string
Bandeira do cartão (visa, mastercard, elo, etc). Usado pra cálculo de juros — opcional, a Chargefy infere quando ausente.
​
discount_code
string
Cupom de desconto aplicado pelo comprador.

​
Três variantes

​
(a) PIX

Mais simples: só dados do comprador. A resposta traz payment_data.qr_code (string EMV pra colar no app do banco) e payment_data.qr_code_url (PNG hospedado). 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/public/{{CLIENT_SECRET}}/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pix",
    "customer_email": "nome@email.com",
    "customer_name": "Cliente",
    "customer_tax_id": "123.456.789-00"
  }'

​
(b) Boleto

Como PIX, opcionalmente com data de vencimento custom. A resposta traz payment_data.barcode, payment_data.digitable_line e payment_data.pdf_url. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/public/{{CLIENT_SECRET}}/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "boleto",
    "customer_email": "nome@email.com",
    "customer_name": "Cliente",
    "customer_tax_id": "123.456.789-00",
    "boleto_due_date": "2026-05-10"
  }'

​
(c) Cartão de crédito

Exige card_id (token tokenizado client-side — nunca envie número de cartão direto pra esse endpoint). A transação é autorizada na hora; payment_status: "paid" na resposta indica sucesso. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/public/{{CLIENT_SECRET}}/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "credit_card",
    "customer_email": "nome@email.com",
    "customer_name": "Cliente",
    "customer_tax_id": "123.456.789-00",
    "card_id": "{{CARD_TOKEN}}",
    "installments": 3
  }'

​
Tokenização do cartão

A Chargefy não aceita número de cartão em texto plano neste endpoint. O card_id precisa ser um token gerado client-side por uma das duas vias:
  • Hosted page (recomendado) — você redireciona o comprador pra response.url e o form de cartão da Chargefy tokeniza, confirma e devolve em success_url. Sem PCI no seu lado.
  • Frontend custom — use o pacote @chargefy/checkout (npm) que expõe a função de tokenização. Roda inteiramente no browser; o cartão nunca toca seu servidor.

​
Resposta

Retorna o DTO completo da sessão com payment_data preenchido conforme o método.

​
PIX

{
  "id": "id_111",
  "client_secret": "...",
  "url": "https://pay.chargefy.io/session/...",
  "status": "complete",
  "mode": "payment",
  "payment_status": "unpaid",
  "currency": "brl",
  "amount_total": 19990,
  "...": "outros campos do DTO",
  "payment_data": {
    "payment_method": "pix",
    "status": "pending",
    "qr_code": "00020126360014BR.GOV.BCB.PIX0114+5511...",
    "qr_code_url": "https://api.chargefy.io/qr/abc123.png",
    "expiration_date": "2026-05-03T19:01:00Z"
  }
}

​
Boleto

{
  "...": "campos do DTO",
  "status": "complete",
  "payment_status": "unpaid",
  "payment_data": {
    "payment_method": "boleto",
    "status": "pending",
    "pdf_url": "https://api.chargefy.io/boletos/abc123.pdf",
    "barcode": "23793.38128 60082.345678 90000.123456 7 89230000019990",
    "digitable_line": "23791234567890123456789012345678901234567890",
    "due_date": "2026-05-10T03:00:00Z"
  }
}

​
Cartão de crédito (sucesso)

{
  "...": "campos do DTO",
  "status": "complete",
  "payment_status": "paid",
  "payment_data": {
    "payment_method": "credit_card",
    "status": "succeeded",
    "installments": 3
  }
}

​
Webhooks disparados

QuandoEvento
Imediatamente após confirmcheckout.session.completed
PIX/boleto compensados (async)checkout.session.async_payment_succeeded
Boleto vencido / PIX expiroucheckout.session.async_payment_failed

​
Erros

HTTPRazão
400client_secret ausente; payment_method não está em payment_method_types da sessão
400Campos obrigatórios do comprador faltando (customer_email/customer_name/customer_tax_id)
400card_id faltando quando payment_method: "credit_card"
400installments excede o máximo permitido pelo valor da sessão
403Sessão não está em status: "open" (já confirmada, expirou ou foi soft-deletada)
404Checkout session não encontrada
422Cartão recusado pelo emissor; cupom inválido; CPF/CNPJ inválido