Skip to main content
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123"
      }
    ]
  }'

{
  "id": "id_111",
  "object": "checkout.session",
  "allow_discount_codes": true,
  "amount_discount": 0,
  "amount_subtotal": 147000,
  "amount_tax": 0,
  "amount_total": 147000,
  "branding_settings": {
    "accent_color": "#A0D2DB",
    "border_style": "pill",
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "cancel_url": null,
  "client_secret": "9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f",
  "created_at": "2026-05-03T18:31:00Z",
  "currency": "brl",
  "customer": null,
  "customer_document": null,
  "customer_document_type": null,
  "customer_email": null,
  "customer_name": null,
  "discount": null,
  "expires_at": "2026-05-04T18:31:00Z",
  "invoice_creation": false,
  "line_items": [
    {
      "id": "id_333",
      "amount_discount": 0,
      "amount_subtotal": 135000,
      "amount_tax": 0,
      "amount_total": 135000,
      "currency": "brl",
      "description": "Suíte Vista Mar",
      "metadata": {},
      "position": 0,
      "price": null,
      "price_data": {
        "currency": "brl",
        "product_id": "prod_suite_123",
        "unit_amount": 45000
      },
      "product": "prod_suite_123",
      "quantity": 3,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 45000
    },
    {
      "id": "id_444",
      "amount_discount": 0,
      "amount_subtotal": 12000,
      "amount_tax": 0,
      "amount_total": 12000,
      "currency": "brl",
      "description": "Taxa de limpeza",
      "metadata": {},
      "position": 1,
      "price": null,
      "price_data": {
        "currency": "brl",
        "product_data": {
          "name": "Taxa de limpeza"
        },
        "unit_amount": 12000
      },
      "product": null,
      "quantity": 1,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 12000
    }
  ],
  "livemode": true,
  "metadata": {
    "order_id": "ord_123"
  },
  "mode": "payment",
  "payment_data": null,
  "payment_method_collection": "always",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "payment_method_types": [
    "credit_card",
    "pix",
    "boleto"
  ],
  "payment_status": "unpaid",
  "require_billing_address": false,
  "require_document": true,
  "require_phone": false,
  "status": "open",
  "submit_type": "book",
  "subscription": null,
  "success_url": "https://meusite.com/sucesso",
  "template": "booking",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f"
}
Uma checkout session é uma sessão temporária de compra. A Chargefy devolve url (página hospedada onde o cliente paga) e client_secret (lido pelo browser do comprador na hosted page). Ela coleta dados do comprador, apresenta os métodos disponíveis e confirma a escolha do comprador. Diferente de um payment link (URL pública reutilizável), a session nasce para uma compra específica e expira em 24h. Ela não é o livro-razão financeiro da cobrança; o resultado do pagamento é acompanhado por payment_status, payment_intent quando fizer parte do fluxo, invoices quando aplicável e webhooks.
Veja Ciclo de pagamento para entender a relação entre checkout sessions, payment intents, invoices e payment methods.

​
Autenticação

Header Authorization: Bearer {{API_KEY}}. Escopo necessário: write.
Tipo de chaveO header OrganizationEm nome de quem cria
API key da organizaçãoproibidoa própria org dona da chave
API key da plataforma (platform_admin)obrigatórioa organização conectada indicada no header (deve estar ativa sob a plataforma)

​
Attributes

​
allow_discount_codes
boolean
default:"true"
Permitir o comprador inserir códigos de cupom na hosted page.
​
branding_settings
object
Override visual desta sessão sobre a identidade da organização. null (ou omitido) herda 100% da organização. Cada campo presente sobrescreve só aquele campo; campo ausente herda. Veja Branding.
​
cancel_url
string
URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão “Voltar” na hosted page).
​
customer_document
string
CPF ou CNPJ do comprador (pré-preenche).
​
customer_document_type
string
cpf ou cnpj. Envie junto de customer_document.
​
customer_email
string
Email do comprador (pré-preenche o formulário da hosted page).
​
customer_id
string
ID de um customer já existente da organização conectada. Se omitido, a Chargefy cria um novo customer no confirm com os dados da sessão/comprador; não há dedupe automático por email ou CPF/CNPJ no nível de customer.
​
customer_name
string
Nome do comprador (pré-preenche).
​
discount_id
string
ID de um desconto pré-aplicado da organização conectada alvo.
​
invoice_creation
boolean
default:"false"
Quando true e a session é mode=payment, o pagamento bem-sucedido materializa uma invoice canônica. Padrão false — pagamentos one-shot não geram invoice. Sessions mode=subscription sempre materializam invoice via a assinatura, independente desse campo (passar false aqui em sub-mode é erro 400).
​
line_items
array
required
Array não-vazio de itens. Cada item descreve um produto/preço cobrado nessa sessão. Aceita três formas — veja Três variantes.
​
metadata
object
Objeto livre string → string, opcional e definido pelo parceiro. É ecoado em todos os webhooks checkout.session.* correspondentes. Limite: 50 chaves, chave com 40 caracteres e valor com 500 caracteres.
​
payment_method_collection
string
default:"always"
Apenas para sessões subscription. Um de always ou if_required. always coleta cartão mesmo quando a assinatura não tem cobrança no momento da confirmação, como trial gratuito ou preço recorrente gratuito. if_required permite concluir sem coletar cartão quando não há cobrança no momento da confirmação.
​
payment_method_options
object
Opções por método de pagamento. Quando omitido, aplicam-se os padrões da organização.
​
payment_method_types
array
Subconjunto dos meios de pagamento habilitados na organização conectada. Use credit_card, pix e/ou boleto. Quando omitido, a sessão usa os meios configurados na organização.
​
require_billing_address
boolean
Exigir endereço de cobrança no formulário. Quando omitido, herda a política de checkout da organização. Boleto sempre exige endereço, independente deste valor.
​
require_document
boolean
Exigir o documento (CPF/CNPJ) do comprador no formulário. Quando omitido, herda a política de checkout da organização (padrão true). Boleto sempre exige documento, independente deste valor.
​
require_phone
boolean
Exigir o telefone do comprador no formulário. Quando omitido, herda a política de checkout da organização (padrão false).
​
submit_type
string
default:"auto"
Tipo semântico do botão de finalização. Um de auto, pay, subscribe, book, donate. Controla a cópia do botão, que a hosted page renderiza no idioma do comprador. auto (padrão) escolhe a cópia pelo tipo da sessão (one-shot → “Pagar”, recorrente → “Assinar”). Use um valor explícito quando a transação for reserva (book) ou doação (donate).
​
subscription_data
object
Input transitório usado apenas quando a sessão é mode=subscription. A session guarda esse snapshot para audit/debug, mas o estado durável de trial fica na subscription criada no confirm.
​
success_url
string
URL pra onde a Chargefy redireciona o cliente após pagamento confirmado.
​
template
string
Template visual da página hospedada. Um de minimal, booking ou subscription. Quando omitido, a sessão usa o template padrão da organização.
Quando criar campo na raiz vs. usar metadata? Tudo que é estrutural (com tipagem, validação, semântica concreta na Chargefy) é na raiz. metadata é livre, opcional, parceiro decide. Campos obrigatórios nunca moram em metadata.

​
line_items — três variantes

Cada item de line_items aceita exatamente uma destas três formas. Use a mais idiomática pro seu caso. Caminho mais curto. Resolve produto, valor e (se for o caso) recorrência automaticamente a partir do price_id. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_id": "price_123"
      }
    ]
  }'

​
(b) Produto do catálogo + preço ad-hoc

Reusa nome/descrição do produto cadastrado, mas com valor único pra essa sessão. Não cria preço novo no catálogo. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_id": "prod_123",
          "unit_amount": 12990
        }
      }
    ]
  }'

​
(c) Produto e preço ad-hoc

Nada vem do catálogo. Útil pra integrações headless que não cadastram produto. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_data": {
            "name": "Consultoria avulsa"
          },
          "unit_amount": 4990
        }
      }
    ]
  }'

​
Pagamento one-shot com invoice (invoice_creation)

Passe invoice_creation: true quando precisar de uma invoice canônica materializada no sucesso da cobrança — útil pra reconciliação contábil ou emissão fiscal a partir de um documento próprio. Sem o flag, mode=payment não gera invoice; mode=subscription sempre gera independentemente. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: {{ORGANIZATION_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_creation": true,
    "line_items": [
      {
        "price_id": "price_111",
        "quantity": 1
      }
    ],
    "success_url": "https://meusite.com/sucesso"
  }'

​
Recorrência

Em (a), basta o price_id apontar pra um preço com recurring preenchido — a sessão nasce em mode: subscription sem campos extras. Em (b) e (c), adicione price_data.recurring: 
{
  "price_data": {
    "currency": "brl",
    "product_id": "prod_222",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "unit_amount": 12990
  }
}
Para trial em checkout de assinatura, use subscription_data. A session guarda esse input como snapshot, mas a assinatura criada no confirm passa a ser a fonte de verdade (trial_start, trial_end, trial_settings). Por padrão, a hosted page coleta cartão quando a assinatura não tem cobrança no momento da confirmação (payment_method_collection: "always"), preparando a cobrança automática de ciclos pagos futuros. Para permitir concluir sem cartão quando nada é devido agora, envie payment_method_collection: "if_required". 
{
  "line_items": [
    {
      "price_id": "price_111",
      "quantity": 1
    }
  ],
  "payment_method_collection": "always",
  "subscription_data": {
    "trial_period_days": 14,
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "pause"
      }
    }
  },
  "success_url": "https://meusite.com/sucesso"
}

​
Restrições do array

  • Todos os itens compartilham a mesma currency.
  • Ou todos os itens são recorrentes, ou nenhum é. Misturar one-shot com recorrente retorna 400.
  • Cada item tem exatamente um entre price_id ou price_data.
  • Quando price_data é usado, exatamente um entre product_id e product_data deve acompanhá-lo.

​
Branding

A identidade visual da página hospedada vem da organização (cor, fonte, tema, formato de borda — configurada uma vez em organizations). A checkout session pode sobrescrever campos visuais pontualmente via branding_settings. O contrato é por campo: cada campo presente em branding_settings vence o default da organização; cada campo ausente herda. branding_settings: null (ou omitido) herda tudo.
A resposta da API devolve o branding_settings cru — só o que você sobrescreveu nesta sessão, sem mesclar com a organização. A mescla final (override da sessão + defaults da organização) é resolvida pela página hospedada no momento de renderizar. Assim o que você envia é o que você lê de volta.
submit_type não é branding — é a cópia semântica do botão e mora na raiz da sessão.

​
Templates

template controla a estrutura do painel esquerdo da página hospedada. O painel de pagamento permanece o mesmo em todos os templates.

minimal

Miniatura do template minimal com produto, resumo e formulário de pagamento

booking

Miniatura do template booking com estadia, noites e adicionais

subscription

Miniatura do template subscription com trial, ciclo de cobrança e valor por mês
ValorUso
minimalProduto/preço e resumo padrão.
bookingReservas de hospedagem com estadia, noites e adicionais/taxas.
subscriptionAssinaturas com trial, ciclo de cobrança e valor por mês.
No booking, envie a acomodação como primeiro line_items[]: price_data.product_id aponta para o produto da acomodação, unit_amount é a diária dinâmica e quantity é o número de noites. Itens seguintes representam adicionais ou taxas cobradas. No subscription, use line_items[] com preços recorrentes (recurring) e, quando houver período de teste, envie subscription_data.trial_period_days (ou subscription_data.trial_end). A página destaca o trial, o ciclo de cobrança e o valor por mês equivalente, e mostra R$ 0,00 como total devido hoje durante o trial. 
curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: {{ORGANIZATION_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "branding_settings": {
      "accent_color": "#A0D2DB",
      "border_style": "pill"
    },
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_id": "prod_suite_123",
          "unit_amount": 45000
        },
        "quantity": 3
      },
      {
        "price_data": {
          "currency": "brl",
          "product_data": {
            "name": "Taxa de limpeza"
          },
          "unit_amount": 12000
        },
        "quantity": 1
      }
    ],
    "submit_type": "book",
    "success_url": "https://meusite.com/sucesso",
    "template": "booking"
  }'

​
Resposta

​
id
string
ID da checkout session.
​
object
string
Sempre checkout.session.
​
allow_discount_codes
boolean
Eco do body (default true).
​
amount_discount
integer
Desconto aplicado, em centavos.
​
amount_subtotal
integer
Soma dos line_items, em centavos, antes de descontos e impostos.
​
amount_tax
integer
Impostos aplicados, em centavos.
​
amount_total
integer
Total cobrado, em centavos. = subtotal − discount + tax.
​
branding_settings
object | null
Override visual cru desta sessão — só os campos que você sobrescreveu, sem mescla com a organização. null quando não houve override. Não é o branding resolvido (esse é aplicado pela página hospedada).
​
cancel_url
string | null
Eco do que veio no body.
​
client_secret
string
String opaca de 64 caracteres hex, sem prefixo. Usada pela hosted page pra abrir a sessão sem precisar do token de API. Não é segredo de servidor — é runtime do browser.
​
created_at
string
ISO-8601.
​
currency
string
Moeda em ISO 4217 minúsculo (ex: brl).
​
customer
string | null
Vem null no create — a Chargefy resolve customer só no confirm (lazy). Aparece preenchido nos webhooks de checkout.session.completed em diante.
​
customer_document
string | null
Mesmo padrão de customer_email.
​
customer_document_type
string | null
cpf, cnpj ou null.
​
customer_email
string | null
Pré-preenchido se enviado no body; senão null. Atualizado quando o comprador preenche o formulário.
​
customer_name
string | null
Mesmo padrão de customer_email.
​
discount
string | null
Eco do body.
​
expires_at
string
ISO-8601. 24h depois do created_at.
​
invoice_creation
boolean
Eco do body (default false em mode=payment).
​
line_items
array
Snapshot dos itens da sessão (resolvido com produto/preço/recorrência conforme a variante usada).
​
livemode
boolean
Indica se a sessão foi criada em modo live.
​
metadata
object
Eco do body (default {}).
​
mode
string
payment (one-shot) ou subscription (recorrente).
​
payment_data
object | null
null no create. Aparece preenchido depois do confirm.
​
payment_method_collection
string
Em sessões subscription, indica se a hosted page coleta cartão sempre (always) ou somente quando houver cobrança no momento da confirmação (if_required). Em sessões payment, o valor é always.
​
payment_method_options
object
Opções por método de pagamento oferecidas na hosted page.
​
payment_method_types
string[]
Métodos disponíveis pro comprador na hosted page (ex: ["credit_card", "pix", "boleto"]). É o subconjunto salvo na sessão: ou o valor enviado em payment_method_types, ou os meios configurados na organização quando o campo foi omitido. Esse conjunto é um snapshot imutável — a hosted page, a consulta, a confirmação e os webhooks da sessão sempre devolvem exatamente esses métodos, independente de mudanças posteriores na política da organização.
​
payment_status
string
unpaid, paid, no_payment_required (total = 0).
​
require_billing_address
boolean
Política resolvida (body ou default da organização). Boleto sempre exige.
​
require_document
boolean
Política resolvida (body ou default da organização, padrão true). Boleto sempre exige documento.
​
require_phone
boolean
Política resolvida (body ou default da organização, padrão false).
​
status
string
open (criada, aguardando pagamento), complete (cliente confirmou), expired (24h sem confirm — terminal).
​
submit_type
string
Eco do body (default auto). Um de auto, pay, subscribe, book, donate.
​
subscription
string | null
Subscription criada por uma sessão mode=subscription. Vem null no create.
​
success_url
string | null
Eco do que veio no body.
​
template
string | null
Template explícito da sessão. null significa que a página hospedada usa o padrão da organização.
​
url
string
URL hospedada da Chargefy. Redirecione o comprador pra essa URL.
{
  "id": "id_111",
  "object": "checkout.session",
  "allow_discount_codes": true,
  "amount_discount": 0,
  "amount_subtotal": 147000,
  "amount_tax": 0,
  "amount_total": 147000,
  "branding_settings": {
    "accent_color": "#A0D2DB",
    "border_style": "pill",
    "brand_color": null,
    "font_family": null,
    "theme": null
  },
  "cancel_url": null,
  "client_secret": "9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f",
  "created_at": "2026-05-03T18:31:00Z",
  "currency": "brl",
  "customer": null,
  "customer_document": null,
  "customer_document_type": null,
  "customer_email": null,
  "customer_name": null,
  "discount": null,
  "expires_at": "2026-05-04T18:31:00Z",
  "invoice_creation": false,
  "line_items": [
    {
      "id": "id_333",
      "amount_discount": 0,
      "amount_subtotal": 135000,
      "amount_tax": 0,
      "amount_total": 135000,
      "currency": "brl",
      "description": "Suíte Vista Mar",
      "metadata": {},
      "position": 0,
      "price": null,
      "price_data": {
        "currency": "brl",
        "product_id": "prod_suite_123",
        "unit_amount": 45000
      },
      "product": "prod_suite_123",
      "quantity": 3,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 45000
    },
    {
      "id": "id_444",
      "amount_discount": 0,
      "amount_subtotal": 12000,
      "amount_tax": 0,
      "amount_total": 12000,
      "currency": "brl",
      "description": "Taxa de limpeza",
      "metadata": {},
      "position": 1,
      "price": null,
      "price_data": {
        "currency": "brl",
        "product_data": {
          "name": "Taxa de limpeza"
        },
        "unit_amount": 12000
      },
      "product": null,
      "quantity": 1,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 12000
    }
  ],
  "livemode": true,
  "metadata": {
    "order_id": "ord_123"
  },
  "mode": "payment",
  "payment_data": null,
  "payment_method_collection": "always",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "has_interest": true,
        "max_count": 12
      }
    }
  },
  "payment_method_types": [
    "credit_card",
    "pix",
    "boleto"
  ],
  "payment_status": "unpaid",
  "require_billing_address": false,
  "require_document": true,
  "require_phone": false,
  "status": "open",
  "submit_type": "book",
  "subscription": null,
  "success_url": "https://meusite.com/sucesso",
  "template": "booking",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f"
}

​
Próximo passo

Redirecione o comprador pra resposta.url. A Chargefy renderiza a página de pagamento, confirma o método escolhido e devolve o cliente em success_url ao final. 
window.location.assign(response.url);
O frontend da hosted page chama POST /v1/checkout-sessions/public/:client_secret/confirm sozinho. Seu servidor não precisa criar nem confirmar uma movimentação interna de processamento para uma checkout session.

​
Erros

HTTPRazão
400line_items ausente, vazio, ou item sem price_id nem price_data
400Item com price_id e price_data juntos (envie exatamente um)
400price_data sem product_id nem product_data — ou com ambos
400Mistura de itens recorrentes e únicos no mesmo line_items
400Currency divergente entre os itens
400price_id ou product_id não existe na organização conectada alvo
400customer_id (quando passado) não pertence à organização conectada alvo
401Authorization ausente, mal formado ou inválido
403Token de plataforma sem header Organization, ou Organization apontando para uma organização conectada não ativa da sua plataforma
Organização conectada sem cadastro financeiro concluído não bloqueia a criação — a sessão nasce com payment_method_types: []. Trate o array vazio antes de redirecionar o comprador (ou aborte criação no seu lado se preferir).