Obter uma sessão de checkout

Use a consulta autenticada por ID no seu servidor ou painel administrativo. Use a consulta pública por client_secret somente no browser do comprador, quando não pode existir API key no frontend.

Leitura	Endpoint	Autenticação	Uso típico
Por ID	`GET /v1/checkout-sessions/{id}`	API key com escopo `read`	servidor, painel administrativo, reconciliação
Por `client_secret`	`GET /v1/checkout-sessions/public/{client_secret}`	nenhuma; o `client_secret` autentica a sessão	hosted page ou checkout frontend custom

Consulta por ID

Retorna o objeto checkout.session completo pelo ID da sessão. A API key da própria organização atua diretamente. A API key de plataforma exige o header Organization: <id> apontando para uma organização conectada ativa.

Parâmetros de caminho

string

required

ID da checkout session (cs_*).

curl -X GET "https://api.chargefy.io/v1/checkout-sessions/cs_Wwz6A9P364XFq31K" \
  -H "Authorization: Bearer {{API_KEY}}"

Resposta

Retorna o mesmo DTO de POST /v1/checkout-sessions. O campo payment_data fica null antes da confirmação e aparece preenchido quando a sessão já foi confirmada.

200

{
  "id": "cs_Wwz6A9P364XFq31K",
  "object": "checkout.session",
  "allow_discount_codes": false,
  "amount_discount": 0,
  "amount_subtotal": 19990,
  "amount_tax": 0,
  "amount_total": 19990,
  "cancel_url": "https://meusite.com/cancelado",
  "client_reference_id": null,
  "client_secret": "aecaaf4172294e5149544a611873530704816cd4a4aeada47821af62c67dc808",
  "created_at": "2026-05-19T18:31:00Z",
  "currency": "brl",
  "customer": "cus_AqS7dhPduv5PuKqf",
  "customer_document": "12345678901",
  "customer_document_type": "cpf",
  "customer_email": "nome@email.com",
  "customer_name": "Cliente Exemplo",
  "discount": null,
  "expires_at": "2026-05-20T18:31:00Z",
  "has_surcharge": false,
  "invoice_creation": false,
  "line_items": [
    {
      "id": "li_v3zoBS78P8fgfK6x",
      "adjustable_quantity": {
        "enabled": false,
        "maximum": null,
        "minimum": null
      },
      "amount_discount": 0,
      "amount_subtotal": 19990,
      "amount_tax": 0,
      "amount_total": 19990,
      "currency": "brl",
      "description": "Plano Pro mensal",
      "metadata": {},
      "position": 0,
      "price": "price_L5yEaLBX4FvkcVrX",
      "price_data": null,
      "product": "prod_ciM8ubnYU2T9DkUP",
      "quantity": 1,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 19990
    }
  ],
  "livemode": true,
  "marketing_attribution": null,
  "metadata": {},
  "mode": "payment",
  "payment_data": null,
  "payment_method_collection": "always",
  "payment_status": "unpaid",
  "status": "open",
  "submit_type": "auto",
  "subscription": null,
  "success_url": "https://meusite.com/sucesso",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f"
}

Consulta pública por client_secret

Endpoint de leitura para o browser do comprador. Não envie Authorization; o client_secret na URL é a credencial da sessão.

Parâmetros de caminho

string

required

Secret opaco da checkout session, retornado no campo client_secret do create.

curl -X GET "https://api.chargefy.io/v1/checkout-sessions/public/{{CLIENT_SECRET}}"

Não exponha o Authorization da sua API key no browser. A rota pública por client_secret existe para carregar e acompanhar a sessão sem credencial de servidor.

Resposta pública

Retorna o mesmo objeto checkout.session da leitura por ID. Por alimentar a página hospedada, a leitura pública também inclui campos de renderização resolvidos no servidor.

object

Configuração atual e materializada da organização para a página hospedada. Inclui identidade visual, template, exibição do produto e resumo, política de descontos, dados exigidos, métodos de pagamento e parcelamento. Também inclui logo_url, business_name e statement_descriptor para identificar o lojista.

string | null

Alias público de expires_at, usado pela hosted page.

object | null

Opções de parcelamento calculadas para o valor atual da sessão. Objeto com max (número máximo de parcelas permitido) e options (mapa por bandeira, cada item com installments, interest_rate, per_installment e total). interest_rate usa basis points: 708 representa 7,08%.

object | null

Detalhes de próxima ação quando a resposta tiver dados de exibição para um método assíncrono. Na leitura antes do confirm, normalmente é null.

checkout_settings existe somente na leitura pública usada pela página hospedada. A leitura autenticada por ID e os webhooks retornam o objeto transacional, sem duplicar a configuração da organização.

Para PIX e boleto, status: "complete" significa que o comprador submeteu o formulário, não que o pagamento foi compensado. Acompanhe payment_status (unpaid -> paid) ou ouça o webhook checkout.session.async.payment.succeeded.

Erros

HTTP	Razão
400	`client_secret` ausente ou corpo inválido na rota pública
401	API key ausente, mal formada ou inválida na rota por ID
403	API key de plataforma sem `Organization`, ou `Organization` sem vínculo ativo
404	Checkout session não encontrada

404

{
  "error": {
    "code": "resource_missing",
    "message": "Checkout session not found",
    "type": "invalid_request_error"
  }
}

401

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Obter uma sessão de checkout

Consulta por ID

Parâmetros de caminho

Resposta

Consulta pública por client_secret

Parâmetros de caminho

Resposta pública

Erros

​Consulta por ID

​Parâmetros de caminho

​Resposta

​Consulta pública por client_secret

​Parâmetros de caminho

​Resposta pública

​Erros

Consulta por ID

Parâmetros de caminho

Resposta

Consulta pública por client_secret

Parâmetros de caminho

Resposta pública

Erros