Skip to main content
Se você quer integrar o processo de checkout mais profundamente com seu site ou aplicação, use nossa API dedicada. O primeiro passo é criar uma sessão de Checkout. Para isso, você precisa pelo menos do ID do Produto. Você pode obter o Product ID na seção Produtos do dashboard — clique no menu de contexto do produto e selecione “Copiar Product ID”. A API retorna um objeto com todas as informações da sessão, incluindo uma URL onde você deve redirecionar seu cliente para completar a compra.

​
Fluxo de checkout

1

Criar sessão

POST /api/v1/checkouts/ — Cria uma sessão de checkout com os produtos selecionados.
2

Cliente acessa

Redirecione o cliente para a URL do checkout ou use o checkout embarcado.
3

Escolha do pagamento

O cliente escolhe o método de pagamento: PIX, Cartão de Crédito ou Boleto.
4

Confirmação

POST /api/v1/checkouts/:id/confirm — Confirma o pagamento com os dados do método escolhido.
5

Resultado

O status do checkout é atualizado para succeeded (imediato para cartão) ou confirmed (aguardando para PIX/Boleto).

​
Métodos de pagamento

​
PIX

Ao confirmar com PIX, nenhum parâmetro extra de pagamento é necessário. A Chargefy gera automaticamente o QR Code. 
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "[email protected]",
  customer_tax_id: "123.456.789-00",
  payment_method: "pix",
});

// Response inclui:
// confirmed.payment_data.pix_qr_code
// confirmed.payment_data.pix_emv
// confirmed.payment_data.pix_expiration

​
Cartão de Crédito

Para cartão, envie os dados do cartão e número de parcelas. 
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "[email protected]",
  customer_tax_id: "123.456.789-00",
  payment_method: "credit_card",
  card: {
    holder_name: "JOAO SILVA",
    card_number: "4111111111111111",
    expiry_month: "12",
    expiry_year: "2028",
    cvv: "123",
  },
  installments: 1, // 1 a 12
});
Os dados do cartão são tokenizados de forma segura. A Chargefy nunca armazena dados sensíveis do cartão.

​
Boleto Bancário

Para boleto, envie a data de vencimento desejada. 
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "[email protected]",
  customer_tax_id: "123.456.789-00",
  payment_method: "boleto",
  boleto: {
    due_date: "2026-03-20",
  },
});

// Response inclui:
// confirmed.payment_data.barcode
// confirmed.payment_data.digitable_line
// confirmed.payment_data.pdf_url

​
Status do checkout

StatusDescrição
openCriado, aguardando pagamento
confirmedPagamento em processamento (PIX/Boleto aguardando confirmação)
succeededPagamento confirmado com sucesso
failedPagamento falhou ou foi recusado
expiredCheckout expirou (24h padrão)
open → confirmed → succeeded
  ↓       ↓
expired  failed

​
Recorrência e assinaturas

Quando o produto selecionado tem preço recorrente, a Chargefy automaticamente:
  1. Detecta que é um produto recorrente (via recurring_interval)
  2. Cria um plano de recorrência automaticamente
  3. Vincula o cartão do cliente ao plano
  4. Gera cobranças automáticas no ciclo definido
Assinaturas recorrentes funcionam apenas com cartão de crédito. Se o checkout de um produto recorrente for acessado com PIX ou Boleto, o pagamento falhará.

​
Múltiplos produtos

Você pode criar uma sessão de checkout com múltiplos produtos. O cliente poderá alternar entre eles na página de checkout.

​
Parcelamento

Para pagamentos únicos com cartão de crédito, o cliente pode parcelar de 1 a 12 vezes:
ParcelasComportamento
1Pagamento à vista
2-12Parcelado (com ou sem juros, conforme configuração)
O parcelamento é enviado no campo installments na confirmação do checkout.

​
Descontos

Descontos podem ser aplicados ao checkout de duas formas:
  • Desconto fixo — Valor absoluto em R(ex:R (ex: R 10,00 off)
  • Desconto percentual — Porcentagem do valor total (ex: 15% off)
const checkout = await chargefy.checkouts.create({
  product_price_id: "price_xxx",
  discount_id: "discount_xxx", // Desconto predefinido
  allow_discount_codes: true, // Permitir códigos de desconto
});

​
Valor customizado

Com amount_is_custom: true, o cliente define o valor do pagamento (modelo “pague quanto quiser”): 
const checkout = await chargefy.checkouts.create({
  product_price_id: "price_xxx",
  amount: 5000, // R$ 50,00 como valor padrão (em centavos)
  amount_is_custom: true,
});

​
External Customer ID

Se você tem seu próprio sistema de usuários, informe o ID do cliente para facilitar a reconciliação: 
const checkout = await chargefy.checkouts.create({
  product_price_id: "price_xxx",
  external_customer_id: "seu-customer-id-123",
});
Após um checkout bem-sucedido, o cliente na Chargefy terá o external_id definido. Esse ID será informado via webhooks em customer.external_id.

​
Exemplos com SDK

import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env["CHARGEFY_ACCESS_TOKEN"] ?? "",
});

async function criarCheckout() {
  const checkout = await chargefy.checkouts.create({
    product_price_id: "price_xxx",
    allow_discount_codes: true,
  });

  console.log(checkout.url); // URL do checkout
  console.log(checkout.client_secret); // Secret para embed
}

criarCheckout();

​
Atualização em tempo real (SSE)

A Chargefy oferece um endpoint de Server-Sent Events para acompanhar atualizações do checkout em tempo real: 
GET /api/v1/checkouts/client/:client_secret/stream
Eventos disponíveis:
  • connected — Conexão estabelecida
  • checkout.updated — Status do checkout atualizado
  • terminal — Estado final alcançado (succeeded/failed/expired)
Isso é especialmente útil para pagamentos via PIX e Boleto, onde o cliente aguarda a confirmação assíncrona.