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.

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.

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

cURL

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": "[e-mail]",
    "success_url": "https://meusite.com/sucesso",
    "metadata": {
      "order_ref": "pedido-456"
    }
  }'

Resposta de Exemplo

{
  "id": "chk_1a2b3c4d5e6f",
  "status": "open",
  "client_secret": "chk_secret_xyz789",
  "product_price_id": "pp_abc123",
  "amount": 9900,
  "currency": "BRL",
  "customer_email": "[e-mail]",
  "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"
}