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

# POST /api/v1/checkouts/

> Cria uma nova sessão de checkout para processamento de pagamento

Cria uma sessão de checkout associada a um produto. O checkout retorna um `client_secret` que pode ser usado no frontend para exibir a interface de pagamento.

## Autenticação

Requer **Organization Access Token (OAT)** via header `Authorization: Bearer`.

Escopos necessários: `web:write` ou `checkouts:write`.

**Organização pai:** se `product_id` for de um produto cuja organização é uma **sub-organização direta** do token, a criação do checkout é permitida (sem OAT do filho). Detalhes e exemplos em [Marketplace: OAT da organização pai e sub-organizações](https://scaleup-c34c4386.mintlify.site/guides/parent-marketplace-suborganizations.md).

## Corpo da Requisição

É obrigatório informar ao menos um dos campos: `product_id`, `product_price_id` ou `products`.

**payment\_processor** `string` (default: zoop)

Processador de pagamento. Valor aceito: `zoop`

**product\_id** `string`

ID do produto a ser cobrado (recomendado)

**product\_price\_id** `string`

ID do preço do produto (obsoleto — prefira `product_id`)

**products** `string[]`

Lista de IDs de produtos para checkouts com múltiplos itens

**discount\_id** `string`

ID de um desconto pré-aplicado

**allow\_discount\_codes** `boolean` (default: true)

Permitir que o cliente insira cupons de desconto na página de checkout

**amount** `integer`

Valor personalizado em centavos (para produtos com preço livre)

**quantity** `integer` (default: 1)

Quantidade de unidades (assentos, licenças, etc). Total cobrado = `unit_amount × quantity`. Ver [Precificação por Quantidade](https://scaleup-c34c4386.mintlify.site/features/seat-based-pricing.md).

**customer\_id** `string`

ID de um cliente existente para associar ao checkout

**is\_business\_customer** `boolean` (default: false)

Indica se o comprador é pessoa jurídica

**external\_customer\_id** `string`

ID externo do cliente no seu sistema

**customer\_name** `string`

Nome completo do cliente

**customer\_email** `string`

E-mail do cliente

**customer\_ip\_address** `string`

Endereço IP do cliente (para antifraude)

**customer\_billing\_name** `string`

Nome de cobrança do cliente

**customer\_billing\_address** `object`

Endereço de cobrança do cliente

**customer\_tax\_id** `string`

CPF ou CNPJ do cliente

**customer\_metadata** `object`

Metadados adicionais do cliente em formato chave-valor

**subscription\_id** `string`

ID da assinatura existente (para upgrades de plano)

**recurrence\_billing** `string`

Estratégia de cobrança recorrente para produtos com assinatura. Valores: `zoop` (padrão — cobrança automática via plano no gateway) ou `manual` (Chargefy gerencia as renovações; use junto com `POST /:id/manual-renewal-checkout`).

**trial\_interval** `string`

Unidade do período de trial (ex: `day`, `month`)

**trial\_interval\_count** `integer`

Quantidade de unidades do período de trial

**require\_billing\_address** `boolean` (default: false)

Exigir que o cliente preencha o endereço de cobrança

**success\_url** `string`

URL de redirecionamento após pagamento bem-sucedido

**cancel\_url** `string`

URL de redirecionamento quando o comprador abandona ou cancela o checkout (botão "Voltar" no checkout hospedado)

**embed\_origin** `string`

Origem permitida para checkout embutido via iframe

**metadata** `object`

Metadados personalizados em formato chave-valor

**no\_fees\_installments** `boolean` (default: false)

Se `true`, as opções de parcelamento são calculadas sem acréscimo de juros

**checkout\_link\_id** `string`

ID do checkout link reutilizável associado a esta sessão (omitir para checkouts individuais)

## Resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `string` | ID único do checkout |
| `status` | `string` | Status: `open` |
| `client_secret` | `string` | Secret para uso no frontend |
| `product_price_id` | `string` | ID do preço do produto |
| `amount` | `integer` | Valor em centavos |
| `currency` | `string` | Moeda (ex: `BRL`) |
| `customer_email` | `string` | Email do cliente |
| `success_url` | `string` | URL de sucesso |
| `metadata` | `object` | Metadados personalizados |
| `expires_at` | `string` | Data/hora de expiração |
| `created_at` | `string` | Data/hora de criação |

## Exemplo

```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": "pp_abc123",
    "customer_email": "cliente@exemplo.com",
    "success_url": "https://meusite.com/sucesso",
    "metadata": {
      "order_ref": "pedido-456"
    }
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

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

const checkout = await chargefy.checkouts.create({
  productPriceId: 'pp_abc123',
  customerEmail: 'cliente@exemplo.com',
  successUrl: 'https://meusite.com/sucesso',
  metadata: {
    order_ref: 'pedido-456',
  },
});
```

## Resposta de Exemplo

```json theme={null}
{
  "id": "chk_1a2b3c4d5e6f",
  "status": "open",
  "client_secret": "chk_secret_xyz789",
  "product_price_id": "pp_abc123",
  "amount": 9900,
  "currency": "BRL",
  "customer_email": "cliente@exemplo.com",
  "success_url": "https://meusite.com/sucesso",
  "metadata": {
    "order_ref": "pedido-456"
  },
  "expires_at": "2026-03-12T10:30:00Z",
  "created_at": "2026-03-12T10:00:00Z",
  "updated_at": "2026-03-12T10:00:00Z"
}
```


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