Sessões de checkout
Expirar uma sessão de checkout
Encerra uma sessão aberta antes do prazo e cancela o payment intent dela com expired.
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/cs_ESZSB92S1L4ZwFqH/expire" \
-H "Authorization: Bearer {{API_KEY}}"
{
"id": "cs_ESZSB92S1L4ZwFqH",
"object": "checkout.session",
"affiliate_selection": "inherit",
"affiliates": [],
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description": null,
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_billing_address": false,
"show_compare_at_amount": false,
"show_document": false,
"show_phone": false,
"success_redirect": {
"delay_seconds": 10,
"type": "automatic"
},
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-19T18:31:00Z",
"currency": "brl",
"customer": "cus_A2aHh2bPdmihXEgm",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "[email protected]",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-20T18:31:00Z",
"has_surcharge": false,
"invoice": null,
"invoice_creation": false,
"line_items": [
{
"id": "li_mEkXYS6Qx46gUgP8",
"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": {},
"optional_item": null,
"position": 0,
"price": "price_khN9pm1LeXMtE9ip",
"price_data": null,
"product": "prod_aHjZFX1ZqeyGeGxA",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_ESZSB92S1L4ZwFqH"
}
{
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
{
"error": {
"code": "resource_missing",
"message": "Checkout session not found",
"type": "invalid_request_error"
}
}
{
"error": {
"code": "resource_state_conflict",
"message": "Checkout session cannot be expired in status complete.",
"type": "invalid_request_error"
}
}
Encerra imediatamente uma sessão de checkout aberta, sem esperar o
Se havia um Pix ou boleto emitido e ainda pendente sob esse intent, a cobrança
também é encerrada como
Os dois eventos descrevem a mesma decisão. Trate-os de forma idempotente para
não encerrar o pedido duas vezes no seu sistema.


expires_at.
O comprador que abrir o link depois disso vê um checkout expirado.
Este também é o caminho para encerrar a tentativa de pagamento por trás da
sessão. A sessão é a dona do ciclo de vida do payment_intent dela: expirar a
sessão cancela o intent com cancellation_reason: "expired", do mesmo jeito que
acontece quando o prazo termina sozinho.
Enquanto a sessão está aberta o intent fica aberto de propósito — é isso que
permite ao comprador voltar ao link, trocar de meio de pagamento ou pedir um
novo código Pix dentro do prazo da sessão. Só quando a sessão termina é que a
tentativa termina.
Parâmetros de caminho
Não há corpo. A API key da própria organização atua diretamente; a API key de plataforma exige o headerOrganization: <id> apontando para uma organização
conectada ativa.
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/cs_ESZSB92S1L4ZwFqH/expire" \
-H "Authorization: Bearer {{API_KEY}}"
Quais sessões podem ser expiradas
Os valores abaixo são decheckout_session.status, que tem três valores
possíveis. Só o primeiro aceita a chamada.
checkout_session.status | Resultado da chamada |
|---|---|
open | 200 OK; a sessão passa para expired. |
complete | 409; a sessão já foi submetida pelo comprador. |
expired | 409; a sessão já está expirada. |
Efeito no payment intent
A partir daqui,status é o do payment intent — outro objeto, outra lista
de valores. Não confunda com a tabela acima.
O intent da sessão é cancelado em quatro dos sete valores possíveis. Nos outros
três nada acontece, e cada exclusão é intencional:
payment_intent.status | O que acontece ao expirar a sessão | Por quê |
|---|---|---|
requires_payment_method | Vira canceled, cancellation_reason: "expired", canceled_at preenchido | O comprador nunca escolheu como pagar |
requires_confirmation | idem | Escolheu, mas não confirmou |
requires_action | idem | Pix ou boleto emitido e não pago |
processing | idem | Em processamento sem desfecho |
succeeded | Nada | O comprador pagou. Um pagamento concluído nunca é reescrito |
canceled | Nada | Já encerrado; chamar de novo não muda nada |
requires_capture | Nada | Há valor autorizado e reservado no cartão do comprador. Libere com POST /v1/payment-intents/:id/cancel |
failed — o comprovante já não podia ser pago.
Resposta
200 OK com o objeto checkout.session completo — mesmo shape de
GET /v1/checkout-sessions/:id — agora com
status: "expired".
{
"id": "cs_ESZSB92S1L4ZwFqH",
"object": "checkout.session",
"affiliate_selection": "inherit",
"affiliates": [],
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description": null,
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_billing_address": false,
"show_compare_at_amount": false,
"show_document": false,
"show_phone": false,
"success_redirect": {
"delay_seconds": 10,
"type": "automatic"
},
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-19T18:31:00Z",
"currency": "brl",
"customer": "cus_A2aHh2bPdmihXEgm",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "[email protected]",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-20T18:31:00Z",
"has_surcharge": false,
"invoice": null,
"invoice_creation": false,
"line_items": [
{
"id": "li_mEkXYS6Qx46gUgP8",
"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": {},
"optional_item": null,
"position": 0,
"price": "price_khN9pm1LeXMtE9ip",
"price_data": null,
"product": "prod_aHjZFX1ZqeyGeGxA",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_ESZSB92S1L4ZwFqH"
}
{
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
{
"error": {
"code": "resource_missing",
"message": "Checkout session not found",
"type": "invalid_request_error"
}
}
{
"error": {
"code": "resource_state_conflict",
"message": "Checkout session cannot be expired in status complete.",
"type": "invalid_request_error"
}
}
Erros
| HTTP | code | Quando ocorre |
|---|---|---|
401 | authentication_failed | API key ausente, mal formada ou inválida. |
403 | permission_denied | API key de plataforma sem Organization, ou Organization sem vínculo ativo. |
404 | resource_missing | A sessão não existe nesta organização. |
409 | resource_state_conflict | A sessão não está em open. |
Webhooks gerados
| Evento | Quando |
|---|---|
checkout.session.expired | Sempre. Carrega a sessão completa em data.object. |
payment.intent.canceled | Quando havia um intent em andamento, com cancellation_reason: "expired". |
Objeto da sessão
Campos, estados e relação com o pagamento.
Cancelar um pagamento
Quando o cancelamento vai pelo lado do intent.
⌘I
curl -X POST "https://api.chargefy.io/v1/checkout-sessions/cs_ESZSB92S1L4ZwFqH/expire" \
-H "Authorization: Bearer {{API_KEY}}"
{
"id": "cs_ESZSB92S1L4ZwFqH",
"object": "checkout.session",
"affiliate_selection": "inherit",
"affiliates": [],
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description": null,
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_billing_address": false,
"show_compare_at_amount": false,
"show_document": false,
"show_phone": false,
"success_redirect": {
"delay_seconds": 10,
"type": "automatic"
},
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-19T18:31:00Z",
"currency": "brl",
"customer": "cus_A2aHh2bPdmihXEgm",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "[email protected]",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-20T18:31:00Z",
"has_surcharge": false,
"invoice": null,
"invoice_creation": false,
"line_items": [
{
"id": "li_mEkXYS6Qx46gUgP8",
"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": {},
"optional_item": null,
"position": 0,
"price": "price_khN9pm1LeXMtE9ip",
"price_data": null,
"product": "prod_aHjZFX1ZqeyGeGxA",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_ESZSB92S1L4ZwFqH"
}
{
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
{
"error": {
"code": "resource_missing",
"message": "Checkout session not found",
"type": "invalid_request_error"
}
}
{
"error": {
"code": "resource_state_conflict",
"message": "Checkout session cannot be expired in status complete.",
"type": "invalid_request_error"
}
}

