Checkout API

Crie sessões de checkout programaticamente para controle total

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: "[e-mail]",
  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: "[e-mail]",
  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: "[e-mail]",
  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

Status	Descrição
open	Criado, aguardando pagamento
confirmed	Pagamento em processamento (PIX/Boleto aguardando confirmação)
succeeded	Pagamento confirmado com sucesso
failed	Pagamento falhou ou foi recusado
expired	Checkout expirou (24h padrão)

open → confirmed → succeeded
  ↓       ↓
expired  failed

Recorrência e assinaturas

Quando o preço selecionado tem type = 'recurring', a Chargefy automaticamente:

1. Detecta pelo campo price.type === 'recurring' e lê price.interval + price.interval_count
2. Cria um plano de recorrência Zoop (ou reusa um existente via price.zoop_recurrence_plan_id)
3. Vincula o cartão do cliente ao plano
4. Gera cobranças automáticas no ciclo definido

Quantidade

O checkout aceita quantity (default 1). O total cobrado é unit_amount × quantity. Quando o checkout converte numa assinatura, o quantity é persistido em subscription_product_prices.quantity e reutilizado em toda renovação.

Ver Precificação por Quantidade.

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:

Parcelas	Comportamento
1	Pagamento à vista
2-12	Parcelado (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$ 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

TypeScript

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.