> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://scaleup-c34c4386.mintlify.site/api-reference/checkouts/create.md). 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.

```typescript theme={null}
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "joao@email.com",
  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.

```typescript theme={null}
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "joao@email.com",
  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
});
```

> [!NOTE]
>
> 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.

```typescript theme={null}
const confirmed = await chargefy.checkouts.confirm(checkoutId, {
  customer_name: "João Silva",
  customer_email: "joao@email.com",
  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](https://scaleup-c34c4386.mintlify.site/features/seat-based-pricing.md).

> [!WARNING]
>
> 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.

![](https://mintlify.s3.us-west-1.amazonaws.com/scaleup-c34c4386/assets/features/checkout/session/checkout_multiple_products.light.png)

## 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)

```typescript theme={null}
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"):

```typescript theme={null}
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:

```typescript theme={null}
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 TypeScript theme={null}
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();
```

```bash cURL theme={null}
curl -X POST https://api.chargefy.io/api/v1/checkouts/ \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price_id": "price_xxx",
    "allow_discount_codes": true
  }'
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.