Overview - Chargefy

Uma checkout.session representa uma única tentativa de compra. Ela nasce para uma cobrança específica — com seus itens, valores e configuração visual já resolvidos — e devolve uma url (a página hospedada onde o comprador paga) e um client_secret (lido pelo browser do comprador para abrir essa página). É a sessão que coleta os dados do comprador, apresenta os métodos de pagamento disponíveis e confirma a escolha dele. Diferente de um payment link (URL pública reutilizável), a session é descartável: vale para uma compra, expira em 24h e não volta a open depois de confirmada. Ela também não é o livro-razão financeiro da cobrança — quem registra o resultado do pagamento são o payment_status, as invoices quando aplicável e os webhooks. A session surge quando você a cria pela API ou quando o comprador clica num payment link, e é atualizada conforme o comprador preenche o formulário e confirma o pagamento; para PIX e boleto, a compensação chega depois, de forma assíncrona.

Data Object

Este é o formato completo retornado em create, get, na confirmação e em data.object dos webhooks checkout.session.*. O campo payment_data vem null enquanto a sessão não foi confirmada e é preenchido conforme o método escolhido após o confirm.

{
  "id": "id_123",
  "object": "checkout.session",
  "allow_discount_codes": true,
  "amount_discount": 0,
  "amount_subtotal": 19990,
  "amount_tax": 0,
  "amount_total": 19990,
  "branding_settings": 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_789",
      "amount_discount": 0,
      "amount_subtotal": 19990,
      "amount_tax": 0,
      "amount_total": 19990,
      "currency": "brl",
      "description": "Plano Pro mensal",
      "metadata": {},
      "position": 0,
      "price": "price_123",
      "price_data": null,
      "product": "prod_123",
      "quantity": 1,
      "recurring_interval": null,
      "recurring_interval_count": null,
      "unit_amount": 19990
    }
  ],
  "livemode": true,
  "metadata": {
    "order_id": "id_456"
  },
  "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": "auto",
  "subscription": null,
  "success_url": "https://meusite.com/sucesso",
  "template": null,
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f"
}

string

Identificador da checkout session.

object

string

Sempre "checkout.session".

allow_discount_codes

boolean

Indica se o comprador pode inserir códigos de cupom na página hospedada.

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. Igual a subtotal − discount + tax.

branding_settings

object | null

Override visual cru desta sessão sobre a identidade da organização. null quando a sessão herda 100% da organização. Cada campo presente sobrescreve só aquele campo; campo ausente vem null e herda. A mescla final é resolvida pela página hospedada, nunca aqui.

Show Campos de branding_settings

accent_color

string | null

Cor de destaque (botão/foco), hex #RGB ou #RRGGBB. null quando não sobrescrita.

border_style

string | null

pill, rounded, sharp ou null.

brand_color

string | null

Cor de marca (painel/cabeçalho), hex #RGB ou #RRGGBB. null quando não sobrescrita.

font_family

string | null

system, inter, geist, bitter ou null.

theme

string | null

light, dark ou null.

cancel_url

string | null

URL para onde a Chargefy redireciona se o comprador abandonar a sessão. null quando não informado.

client_secret

string

String opaca de 64 caracteres hex, sem prefixo. Usada pela página hospedada para abrir a sessão sem precisar do token de API. Não é segredo de servidor — é runtime do browser.

created_at

string

Data de criação em ISO 8601.

currency

string

Moeda em ISO 4217 minúsculo, como brl.

customer

string | null

Customer resolvido para a sessão. Vem null no create — a Chargefy resolve o customer só no confirm — e aparece preenchido a partir de checkout.session.completed.

customer_document

string | null

CPF ou CNPJ do comprador, apenas dígitos. Mesmo padrão de customer_email.

customer_document_type

string | null

Tipo do documento: cpf, cnpj ou null.

customer_email

string | null

Email do comprador. Pré-preenchido se enviado no create; senão null. Atualizado quando o comprador preenche o formulário.

customer_name

string | null

Nome do comprador. Mesmo padrão de customer_email.

discount

string | null

ID de um desconto pré-aplicado à sessão. null quando não houver.

expires_at

string

Data de expiração em ISO 8601. 24h depois do created_at.

invoice_creation

boolean

Quando true e a sessão é mode=payment, o pagamento bem-sucedido materializa uma invoice canônica. Sessões mode=subscription sempre materializam invoice via a assinatura, independentemente desse campo.

line_items

array

Itens cobrados na sessão, com produto, preço e recorrência já resolvidos.

Show Campos de cada line_item

string

Identificador do item.

amount_discount

integer

Desconto aplicado ao item, em centavos.

amount_subtotal

integer

Subtotal do item (unit_amount × quantity), em centavos.

amount_tax

integer

Impostos aplicados ao item, em centavos.

amount_total

integer

Total do item, em centavos.

currency

string

Moeda do item em ISO 4217 minúsculo.

description

string | null

Descrição do item exibida ao comprador. null quando não informada.

metadata

object

Objeto livre do item. Quando vazio, retorna {}.

position

integer

Posição do item na sessão, começando em 0.

price

string | null

ID do preço do catálogo, quando o item veio de um preço cadastrado. null quando o valor foi informado ad-hoc.

price_data

object | null

Dados de preço ad-hoc usados quando o item não aponta para um price. null quando o item veio do catálogo.

product

string | null

ID do produto do catálogo, quando o item veio de um produto cadastrado. null em itens totalmente ad-hoc.

quantity

integer

Quantidade do item.

recurring_interval

string | null

Intervalo de recorrência (day, week, month, year) quando o item é recorrente. null em itens de cobrança única.

recurring_interval_count

integer | null

Número de intervalos entre cada cobrança. null em itens de cobrança única.

unit_amount

integer

Valor unitário, em centavos.

livemode

boolean

true em produção; false em ambiente de teste.

metadata

object

Objeto livre para correlacionar a sessão com o seu sistema. Ecoado em todos os webhooks checkout.session.*. Quando vazio, retorna {}.

mode

string

payment (compra única) ou subscription (recorrente). É derivado dos line_items.

payment_data

object | null

Dados do pagamento expostos após o confirm, conforme o método escolhido. Vem null enquanto a sessão não foi confirmada.

Show Campos de payment_data

barcode

string | null

Código de barras do boleto. Presente apenas em boleto.

decline_category

string | null

Categoria da recusa em uma tentativa de credit_card malsucedida (issuer_declined, invalid, blocked, processing_error). null quando não houve recusa. Veja Códigos de falha.

decline_code

string | null

Código estável do motivo da recusa em uma tentativa de credit_card malsucedida (insufficient_funds, expired_card, …). null quando não houve recusa. Veja Códigos de falha.

digitable_line

string | null

Linha digitável do boleto. Presente apenas em boleto.

due_date

string | null

Data de vencimento do boleto em ISO 8601. Presente apenas em boleto.

expiration_date

string | null

Data de expiração do PIX em ISO 8601. Presente apenas em pix.

installments

integer | null

Número de parcelas. Presente apenas em credit_card.

payment_method

string

Método confirmado: credit_card, pix ou boleto.

pdf_url

string | null

URL do PDF do boleto. Presente apenas em boleto.

qr_code

string | null

Código PIX (string EMV) para colar no app do banco. Presente apenas em pix.

qr_code_url

string | null

URL da imagem do QR Code PIX. Presente apenas em pix.

status

string

Status do pagamento para esse método.

payment_method_collection

string

Em sessões subscription, controla se o checkout coleta um método de pagamento quando não há cobrança no momento. always coleta sempre; if_required coleta apenas quando há valor devido agora.

payment_method_options

object

Opções por método de pagamento oferecidas na página hospedada.

Show Campos de payment_method_options

credit_card

object

Opções do cartão de crédito.

Show Campos de credit_card

installments

object

Configuração do parcelamento.

Show Campos de installments

has_interest

boolean

true quando o comprador paga o acréscimo do parcelamento; false quando o lojista absorve o acréscimo.

max_count

integer

Número máximo de parcelas oferecidas (1–12).

payment_method_types

string[]

Métodos disponíveis para o comprador na página hospedada, como ["credit_card", "pix", "boleto"]. Congelado no momento do create (snapshot imutável) e mantido idêntico em toda leitura — consulta, confirmação e webhooks da sessão refletem exatamente esse conjunto, mesmo que a política de checkout da organização mude depois. Vem vazio quando a organização ainda não concluiu o cadastro financeiro.

payment_status

string

unpaid, paid ou no_payment_required (total igual a zero). Para PIX e boleto permanece unpaid até a compensação assíncrona.

require_billing_address

boolean

Indica se o endereço de cobrança é exigido no formulário. Boleto sempre exige.

require_document

boolean

Indica se o documento (CPF/CNPJ) do comprador é exigido no formulário. Boleto sempre exige.

require_phone

boolean

Indica se o telefone do comprador é exigido no formulário.

status

string

open (criada, aguardando o comprador), complete (comprador confirmou) ou expired (24h sem confirmação — terminal).

submit_type

string

Tipo semântico do botão de finalização: auto, pay, subscribe, book ou donate. Controla a cópia do botão, que a página hospedada renderiza no idioma do comprador. auto escolhe a cópia pelo tipo da sessão.

subscription

string | null

Subscription criada por uma sessão mode=subscription. Vem null antes da confirmação ou em sessões mode=payment.

success_url

string | null

URL para onde a Chargefy redireciona o comprador após o pagamento confirmado. null quando não informado.

template

string | null

Template explícito da sessão. null significa que a página hospedada usa o padrão da organização. Valores disponíveis: minimal e booking.

url

string

URL da página hospedada da Chargefy. Redirecione o comprador para essa URL.

Operações

Test helpers

Em sandbox, você pode simular o resultado de uma checkout.session pelo ID da sessão. A Chargefy localiza o payment_intent associado, aplica a ação nele e retorna o objeto payment_intent completo atualizado. Test helpers só aceitam chaves ch_test_...; chamadas em live mode retornam erro testmode_required.

Ação	Endpoint	Resultado
Succeed	`POST /v1/test-helpers/checkout-sessions/{id}/succeed`	Liquida o pagamento de teste, marca o intent como `succeeded` e emite os webhooks de sucesso.
Fail	`POST /v1/test-helpers/checkout-sessions/{id}/fail`	Marca a tentativa como falha, registra o erro público no intent e emite os webhooks de falha.
Expire	`POST /v1/test-helpers/checkout-sessions/{id}/expire`	Expira a sessão de teste, cancela o intent associado e emite os webhooks correspondentes.

Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

O payload sempre carrega o objeto checkout.session completo em data.object; eventos que alteram a sessão também incluem data.previous_attributes com os valores anteriores dos campos alterados.

​Data Object

​Operações

​Test helpers

​Webhooks

Data Object

Operações

Test helpers

Webhooks