POST /v1/checkout-sessions

Uma checkout session é uma tentativa única de pagamento. A Chargefy devolve url (página hospedada onde o cliente paga) e client_secret (lido pelo browser do comprador na hosted page). Uma session = 1 cliente, 1 tentativa, expira em 24h. Diferente de um payment link (URL pública reutilizável) — a session nasce ligada a um buying attempt específico.

Autenticação

Header Authorization: Bearer {{API_KEY}}. Escopo necessário: write.

Tipo de chave	Header `Organization`	Em nome de quem cria
Organization API key	proibido	a própria org dona da chave
Platform API key (`platform_admin`)	obrigatório	a sub-org indicada no header (deve ser ativa sob a platform)

curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: {{SUB_ORG_ID}}" \
  -H "Content-Type: application/json" \
  -d '{ "line_items": [...] }'

Corpo

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.

success_url

string

URL pra onde a Chargefy redireciona o cliente após pagamento confirmado.

cancel_url

string

URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão “Voltar” na hosted page).

customer_id

string

ID de um customer já existente da sub-org. Se omitido, a Chargefy resolve customer no momento do confirm — usando email + CPF/CNPJ informados pelo comprador. Customer existente é reaproveitado; novo é criado on-demand.

customer_email

string

Email do comprador (pré-preenche o form da hosted page).

customer_name

string

Nome do comprador (pré-preenche).

customer_tax_id

string

CPF ou CNPJ do comprador (pré-preenche).

discount_id

string

ID de um desconto pré-aplicado da sub-org alvo.

allow_discount_codes

boolean

default:"true"

Permitir o comprador inserir códigos de cupom na hosted page.

require_billing_address

boolean

default:"false"

Exigir endereço de cobrança no form.

no_fees_installments

boolean

default:"false"

Calcular parcelamento sem juros.

metadata

object

Bag de string→string, livre, opcional. Decidida pelo parceiro. Ecoada em todos os webhooks checkout.session.* correspondentes. Limite: 50 chaves, chave 40 chars, valor 500 chars.

Quando criar campo top-level vs. usar metadata? Tudo que é estrutural (com tipagem, validação, semântica concreta na Chargefy) é top-level. 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.

(a) Preço do catálogo

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 "Organization: {{SUB_ORG_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "price_id": "id_111", "quantity": 1 }
    ],
    "success_url": "https://meusite.com/sucesso"
  }'

(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 "Organization: {{SUB_ORG_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "brl",
          "unit_amount": 12990,
          "product_id": "id_222"
        }
      }
    ],
    "success_url": "https://meusite.com/sucesso"
  }'

(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 "Organization: {{SUB_ORG_ID}}" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "quantity": 1,
        "price_data": {
          "currency": "brl",
          "unit_amount": 4990,
          "product_data": {
            "name": "Consultoria avulsa",
            "description": "Sessão de 1h por videoconferência"
          }
        }
      }
    ],
    "success_url": "https://meusite.com/sucesso"
  }'

Recorrência

Em (a), basta o price_id apontar pra um preço com interval preenchido — a sessão nasce em mode: subscription sem campos extras. Em (b) e (c), adicione price_data.recurring:

"price_data": {
  "currency": "brl",
  "unit_amount": 12990,
  "product_id": "id_222",
  "recurring": { "interval": "month", "interval_count": 1 }
}

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.

Resposta

string

ID da checkout session.

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.

url

string

URL hospedada da Chargefy. Redirecione o comprador pra essa URL.

status

string

open (criada, aguardando pagamento), complete (cliente confirmou), expired (24h sem confirm — terminal).

mode

string

payment (one-shot) ou subscription (recorrente).

payment_status

string

unpaid, paid, no_payment_required (total = 0).

currency

string

Moeda em ISO 4217 minúsculo (ex: brl).

amount_subtotal

integer

Soma dos line_items, em centavos, antes de descontos e impostos.

amount_discount

integer

Desconto aplicado, em centavos.

amount_tax

integer

Impostos aplicados, em centavos.

amount_total

integer

Total cobrado, em centavos. = subtotal − discount + tax.

organization_id

string

ID da sub-org dona desta sessão.

customer_id

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_email

string | null

Pré-preenchido se enviado no body; senão null. Atualizado quando o comprador preenche o form.

customer_name

string | null

Mesmo padrão de customer_email.

customer_tax_id

string | null

Mesmo padrão de customer_email.

success_url

string | null

Echo do que veio no body.

cancel_url

string | null

Echo do que veio no body.

allow_discount_codes

boolean

Echo do body (default true).

require_billing_address

boolean

Echo do body (default false).

no_fees_installments

boolean

Echo do body (default false).

discount_id

string | null

Echo do body.

livemode

boolean

true em produção, false em sandbox.

payment_method_types

string[]

Métodos disponíveis pro comprador na hosted page (ex: ["credit_card", "pix", "boleto"]). Resolvido por sub-org no momento do create. Vem vazio se a sub-org não concluiu o cadastro financeiro.

metadata

object

Echo do body (default {}).

expires_at

string

ISO-8601. 24h depois do created_at.

created_at

string

ISO-8601.

line_items

array

Snapshot dos itens da sessão (resolvido com produto/preço/recorrência conforme a variante usada).

Resposta de exemplo

{
  "id": "id_111",
  "client_secret": "9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f",
  "status": "open",
  "mode": "payment",
  "payment_status": "unpaid",
  "currency": "brl",
  "amount_subtotal": 19990,
  "amount_discount": 0,
  "amount_tax": 0,
  "amount_total": 19990,
  "organization_id": "id_222",
  "customer_id": null,
  "customer_email": null,
  "customer_name": null,
  "customer_tax_id": null,
  "success_url": "https://meusite.com/sucesso",
  "cancel_url": null,
  "allow_discount_codes": true,
  "require_billing_address": false,
  "no_fees_installments": false,
  "discount_id": null,
  "livemode": true,
  "payment_method_types": ["credit_card", "pix", "boleto"],
  "metadata": { "order_id": "ord_123" },
  "expires_at": "2026-05-04T18:31:00Z",
  "created_at": "2026-05-03T18:31:00Z",
  "line_items": [
    {
      "id": "id_333",
      "price_id": "id_111",
      "price_data": null,
      "product_id": "id_444",
      "quantity": 1,
      "currency": "brl",
      "unit_amount": 19990,
      "amount_subtotal": 19990,
      "amount_discount": 0,
      "amount_tax": 0,
      "amount_total": 19990,
      "description": "Plano Pro mensal",
      "metadata": {},
      "recurring_interval": null,
      "recurring_interval_count": null,
      "position": 0
    }
  ]
}

Próximo passo

Redirecione o comprador pra response.url. A Chargefy renderiza a página de pagamento, processa o método escolhido (PIX/cartão/boleto) 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 — você não precisa fazer essa chamada do seu servidor.

Erros

HTTP	Razão
400	`line_items` ausente, vazio, ou item sem `price_id` nem `price_data`
400	Item com `price_id` e `price_data` juntos (envie exatamente um)
400	`price_data` sem `product_id` nem `product_data` — ou com ambos
400	Mistura de itens recorrentes e únicos no mesmo `line_items`
400	Currency divergente entre os itens
400	`price_id` ou `product_id` não existe na sub-org alvo
400	`customer_id` (quando passado) não pertence à sub-org alvo
401	`Authorization` ausente, mal formado ou inválido
403	Token de plataforma sem header `Organization`, ou `Organization` apontando pra sub-org não-ativa da sua platform

Sub-org 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).

General

Core API

Customer Portal API

Webhook Events

POST /v1/checkout-sessions

Autenticação

Corpo

line_items — três variantes

(a) Preço do catálogo

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

(c) Produto e preço ad-hoc

Recorrência

Restrições do array

Resposta

Resposta de exemplo

Próximo passo

Erros

General

Core API

Customer Portal API

Webhook Events

Documentation Index

​Autenticação

​Corpo

​line_items — três variantes

​(a) Preço do catálogo

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

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

​Recorrência

​Restrições do array

​Resposta

​Resposta de exemplo

​Próximo passo

​Erros

Autenticação

Corpo

line_items — três variantes

(a) Preço do catálogo

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

(c) Produto e preço ad-hoc

Recorrência

Restrições do array

Resposta

Resposta de exemplo

Próximo passo

Erros