Skip to main content
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)
​
seats
integer
Número de assentos (para produtos com precificação por assento)
​
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
​
cross_sell
array
Itens adicionais (add-ons) incluídos no checkout. O amount do checkout deve cobrir o total (produto principal + itens de cross-sell)
​
checkout_link_id
string
ID do checkout link reutilizável associado a esta sessão (omitir para checkouts individuais)

​
Resposta

CampoTipoDescrição
idstringID único do checkout
statusstringStatus: open
client_secretstringSecret para uso no frontend
product_price_idstringID do preço do produto
amountintegerValor em centavos
currencystringMoeda (ex: BRL)
customer_emailstringEmail do cliente
success_urlstringURL de sucesso
metadataobjectMetadados personalizados
expires_atstringData/hora de expiração
created_atstringData/hora de criação

​
Exemplo

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": "[email protected]",
    "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": "[email protected]",
  "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"
}