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 primeira tentativa deste evento é imediata. A Chargefy aguarda um 2xx por até 10 segundos antes de redirecionar para a success_url; sem confirmação, libera o redirect e mantém o evento na fila para novas tentativas. Persista e deduplique o evento antes de responder 2xx.

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,
      "client_reference_id": null,
      "client_secret": "fc04e3beeb81f07bc1f45dd1b1a0c2f101322a073176324e955ca1c5963aa8a3",
      "created_at": "2026-05-03T18:31:00Z",
      "currency": "brl",
      "customer": "cus_F37ypJL5uHM4MBsu",
      "customer_document": "123.456.789-00",
      "customer_document_type": "cpf",
      "customer_email": "nome@email.com",
      "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",
      "payment_data": {
        "installments": 3,
        "payment_method": "credit_card",
        "status": "succeeded"
      },
      "payment_method_collection": "always",
      "payment_status": "paid",
      "status": "complete",
      "submit_type": "auto",
      "subscription": null,
      "success_url": "https://meusite.com/sucesso",
      "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 POST .../confirm para cada variante.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento checkout.session.completed