Evento checkout.session.completed

Evento `checkout.session.completed`

Disparado quando o comprador conclui o confirm da checkout session na página hospedada ou em um frontend custom. data.object contém a sessão completa já com o customer resolvido e, quando houver pagamento, com payment_data preenchido para o método escolhido. Use este evento para marcar que a sessão foi finalizada pelo comprador. Para cartão aprovado de forma síncrona, ele já pode indicar pagamento confirmado. Para Pix e boleto, completed significa que o comprador recebeu as instruções de pagamento; a confirmação financeira chega depois por checkout.session.async.payment.succeeded.

Webhooks devem ser a fonte confiável para liberar produto, serviço ou acesso. Leia sempre payment_status junto com payment_data.payment_method antes de concluir a entrega.

No checkout hospedado, a Chargefy persiste e enfileira este evento antes de responder, mas não aguarda a rede do seu endpoint. A tela de sucesso permite redirecionar imediatamente e segue automaticamente para a success_url após 10 segundos. Persista e deduplique o evento antes de responder 2xx; processe a liberação fora da resposta e faça sua página de destino consultar o estado do seu backend quando o acesso ainda não estiver pronto.

Para transformar esse comportamento em uma experiência clara para o comprador, veja Após receber com um Checkout. O guia cobre a tela de ativação, polling no seu backend, trials e reconciliação pela API.

Quando acontece

Situação	Como aparece no payload
Comprador confirmou com cartão aprovado	`status: "complete"` e `payment_status: "paid"`.
Comprador confirmou com Pix	`status: "complete"`, `payment_status: "unpaid"` e `payment_data.payment_method: "pix"`.
Comprador confirmou com boleto	`status: "complete"`, `payment_status: "unpaid"` e `payment_data.payment_method: "boleto"`.
Trial ou sessão sem valor devido	`payment_status: "no_payment_required"` quando não há cobrança no momento.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id como chave da checkout session no seu sistema.
Salve data.object.customer, que é resolvido no confirm e aparece preenchido deste evento em diante.
Para payment_status: "paid", marque o pedido como pago e libere o produto ou serviço.
Para payment_status: "unpaid" com pix ou boleto, marque o pedido como aguardando pagamento e espere o evento assíncrono de sucesso.
Para payment_status: "no_payment_required", conclua o fluxo sem cobrança imediata conforme a regra da sessão.

Campos importantes

Campo	O que observar
`data.object.status`	Sempre `complete` neste evento: o comprador concluiu o formulário.
`payment_status`	Decide a liberação: `paid`, `unpaid` ou `no_payment_required`.
`payment_data.payment_method`	Método escolhido no confirm quando `payment_data` está preenchido (`credit_card`, `pix` ou `boleto`).
`payment_data.status`	Status do método naquele momento; para métodos assíncronos pode indicar que ainda está pendente.
`customer`	Customer resolvido para a sessão. Use para conciliação e histórico.
`marketing_attribution`	Mesmo snapshot `first_touch` capturado para a sessão; não muda no `completed`.
`subscription`	Vem preenchido quando a sessão `mode: "subscription"` cria uma assinatura.
`metadata`	Ecoa os metadados enviados na criação para correlacionar com seu pedido.

Variações de pagamento

Método	`payment_status` no `completed`	Próxima ação
`credit_card`	`paid` quando aprovado	Pode liberar o produto ou serviço.
`pix`	`unpaid`	Aguarde `checkout.session.async.payment.succeeded` antes de liberar.
`boleto`	`unpaid`	Aguarde `checkout.session.async.payment.succeeded` antes de liberar.
`no_payment_required`	`no_payment_required`	Conclua sem cobrança imediata, normalmente em trial ou total zero.

Exemplo de payload

{
  "id": "evt_8h3K2pQ9mN4tR7vL",
  "object": "event",
  "created_at": "2026-05-03T18:35:00Z",
  "data": {
    "object": {
      "id": "cs_Vjjo5tzBzWiX1Q8p",
      "object": "checkout.session",
      "allow_discount_codes": false,
      "amount_discount": 0,
      "amount_subtotal": 19990,
      "amount_tax": 0,
      "amount_total": 19990,
      "cancel_url": null,
      "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_compare_at_amount": false,
        "summary_style": "product",
        "tracking": {
          "destinations": [],
          "mode": "inherit"
        }
      },
      "client_reference_id": null,
      "client_secret": null,
      "composition_revision": 0,
      "created_at": "2026-05-03T18:31:00Z",
      "currency": "brl",
      "customer": "cus_F37ypJL5uHM4MBsu",
      "customer_document": "123.456.789-00",
      "customer_document_type": "cpf",
      "customer_email": "[email protected]",
      "customer_name": "Cliente",
      "discount": null,
      "expires_at": "2026-05-04T18:31:00Z",
      "has_surcharge": false,
      "invoice_creation": false,
      "line_items": [],
      "livemode": true,
      "marketing_attribution": null,
      "metadata": {},
      "mode": "payment",
      "optional_items": [],
      "payment_data": {
        "payment_method": "credit_card",
        "status": "succeeded"
      },
      "payment_intent": "pi_4JAceVEdXxjxxUhD",
      "payment_method_collection": "always",
      "payment_method_options": {
        "credit_card": {
          "installments": {
            "interest_payer": "buyer",
            "max_count": 12
          }
        }
      },
      "payment_method_types": [
        "credit_card",
        "pix"
      ],
      "payment_status": "paid",
      "status": "complete",
      "submit_type": "auto",
      "subscription": null,
      "success_url": "https://meusite.com/sucesso",
      "template": "split",
      "ui_mode": "hosted",
      "url": "https://pay.chargefy.io/session/..."
    }
  },
  "livemode": true,
  "organization": "org_tyQCzoK42beQBXwC",
  "request": {
    "id": null
  },
  "type": "checkout.session.completed"
}

data.object.payment_data traz os campos do método (Pix QR, boleto barcode ou parcelas do cartão). Veja as variantes em o objeto Checkout Session.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Evento checkout.session.completed