Catálogo de eventos
Encontre o evento certo para cada situação de venda ou assinatura e veja o que fazer ao receber cada um.
A PagPolar envia 15 eventos. Cada página de evento mostra quando ele é enviado, o que fazer, os cuidados e um exemplo completo do payload.
Antes de tratar os eventos, leia Formato do evento e Processar eventos sem duplicar.
Eventos de venda
| Evento | Quando é enviado | O que fazer |
|---|---|---|
TRANSACTION_CREATED | Uma venda foi registrada, no checkout ou pela API. | Registre a venda. Não libere nada. |
TRANSACTION_PENDING | A cobrança de renovação de uma assinatura em PIX ou boleto foi gerada. | Mostre a nova cobrança ao cliente. |
TRANSACTION_PAID | O pagamento foi confirmado. | Libere o que foi vendido. |
TRANSACTION_EXPIRED | Um PIX ou boleto venceu sem pagamento. | Marque o pedido como não pago. |
TRANSACTION_CANCELED | A venda foi cancelada sem ter sido paga. | Cancele o pedido. |
TRANSACTION_ASK_REFUNDING | O cliente pediu reembolso. O dinheiro ainda não voltou. | Registre o pedido e espere o estorno. |
TRANSACTION_REFUNDED | O estorno foi concluído. | Revogue o acesso. |
TRANSACTION_CHARGEBACK_APPROVED | O banco do cliente aprovou uma contestação. | Revogue o acesso. |
Eventos de assinatura
| Evento | Quando é enviado | O que fazer |
|---|---|---|
SUBSCRIPTION_CREATED | Uma assinatura foi registrada. | Registre a assinatura. Não libere o acesso. |
SUBSCRIPTION_CONFIRMED | O gateway aceitou a assinatura no cartão. O status continua DRAFT. | Guarde o external_id. Espere o pagamento. |
SUBSCRIPTION_FAILED | O gateway recusou a assinatura no cartão. | Peça outro cartão. |
SUBSCRIPTION_RENEWED | Um ciclo do cartão, a partir do segundo, foi pago. | Mantenha o acesso. |
SUBSCRIPTION_DELAYED | A renovação em PIX ou boleto está atrasada, dentro da carência. | Lembre o cliente de pagar. |
SUBSCRIPTION_EXPIRED | A assinatura em PIX ou boleto passou da carência sem pagar. | Revogue o acesso. |
SUBSCRIPTION_CANCELED | O cancelamento foi efetivado. | Revogue o acesso. Se precisar da data, confira end_at em GET /subscriptions/{id}. |
Eventos só de assinaturas em PIX ou boleto
Pela API, a assinatura é sempre no cartão. Os eventos de PIX ou boleto das tabelas acima (TRANSACTION_PENDING, SUBSCRIPTION_DELAYED e SUBSCRIPTION_EXPIRED) só chegam para as assinaturas vendidas no checkout da PagPolar.
Situações que não geram evento
| Situação | O que chega | Como acompanhar |
|---|---|---|
| Cartão recusado | Só TRANSACTION_CREATED. Ele chega com status: FAILED se a recusa veio antes do envio. Se a recusa vier depois, a mudança para FAILED não gera evento, nem TRANSACTION_CANCELED | Leia o status do TRANSACTION_CREATED. Se a venda continuar PROCESSING, consulte GET /sales/{identifier}. |
Pedido de cancelamento de assinatura no cartão (CANCELING) | Nada, até o gateway confirmar | Espere SUBSCRIPTION_CANCELED. |
| Troca do cartão de uma assinatura | Nada | Resposta de PATCH /subscriptions/{id}/card. |
| Reembolso de parte dos itens, quando ainda restam itens na venda | Nada. A venda volta para PAID. | Consulte GET /refunds. |
| Pedido de reembolso aberto pelo vendedor ou pelo suporte | Nada de TRANSACTION_ASK_REFUNDING | Espere TRANSACTION_REFUNDED. |
| Renovação paga de assinatura em PIX ou boleto | TRANSACTION_PAID, sem SUBSCRIPTION_RENEWED | Use o TRANSACTION_PAID com subscription preenchida. |
Vendas de uma assinatura recusada que ficam FAILED | TRANSACTION_CREATED na criação e depois SUBSCRIPTION_FAILED; a mudança da venda para FAILED não gera evento | Trate a assinatura inteira como recusada ao receber SUBSCRIPTION_FAILED. |
Processar eventos sem duplicar
Processe cada evento uma única vez, mesmo quando ele chega repetido, fora de ordem ou com um status posterior.
Venda criada POST
**Evento:** `TRANSACTION_CREATED` Uma venda foi registrada. **Quando dispara:** logo depois da criação da venda, no checkout da PagPolar ou pela API, em `POST /v1/payments/pix`, `POST /v1/payments/boleto`, `POST /v1/payments/credit-card` e `POST /v1/plans/offer/{id}/subscribe`. **O que fazer:** registre a venda pelo `transaction.id` e ligue ao seu pedido. Não libere o que foi vendido: espere `TRANSACTION_PAID`. **Atenção:** confira `transaction.status`. No cartão, a venda recusada pelo gateway na criação chega como `FAILED` e não recebe outro evento. O payload é montado na hora do envio, então a venda pode chegar com um status posterior, como `PAID`. Use `source.channel` para saber se a venda veio do checkout ou da API. ### Exemplo de payload ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "event": "TRANSACTION_CREATED", "creation_date": "2026-01-29T14:00:05.000Z", "version": "1.0.0", "data": { "transaction": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "identifier": "PPO0087103960", "status": "PROCESSING", "type": "BILLING", "payment_method": "PIX", "total_amount": "450.0000", "net_amount": 450, "effective_value": "426.5500", "base_tax": "23.4500", "installment_tax": "0.0000", "base_fixed_tax": "0.9900", "base_percentage_tax": "22.4600", "installments": 1, "cycle": 1, "paid_at": null, "created_at": "2026-01-29T14:00:00.000Z" }, "items": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "quantity": 1, "amount": "450.0000", "original_amount": "500.0000", "discount_value": "50.0000", "product": { "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "name": "Curso Completo de Marketing Digital", "type": "DIGITAL" }, "price": { "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "title": "Plano Anual", "price": "500.0000", "identifier": "PPP1234567890" } } ], "product": { "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "name": "Curso Completo de Marketing Digital", "type": "DIGITAL" }, "buyer": { "name": "João Silva", "email": "joao.silva@email.com", "document": "12345678900", "phone": "11999999999" }, "address": { "street": "Rua das Flores", "number": "123", "complement": "Apto 4B", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postal_code": "01000-000" }, "payment_details": { "origin": "DIRECT", "qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d", "billet_barcode": null, "billet_link": null, "last_credit_card_digits": null, "shipping_value": "0.00" }, "coupon": null, "subscription": null, "affiliate": null, "source": { "channel": "API", "api_credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "order_bumps": [ { "transaction": { "id": "d4e5f6a7-b8c9-4123-8def-456789012345", "identifier": "PPO0087103961", "status": "PAID", "type": "BILLING", "payment_method": "CREDIT_CARD", "total_amount": "47.0000", "net_amount": 47, "effective_value": "43.5000", "base_tax": "3.5000", "installment_tax": "0.0000", "base_fixed_tax": "0.9900", "base_percentage_tax": "2.5100", "installments": 1, "cycle": 1, "paid_at": "2026-01-29T14:35:00.000Z", "created_at": "2026-01-29T14:00:00.000Z" }, "items": [ { "id": "a12bc34d-56ef-4890-abcd-ef1234567890", "quantity": 1, "amount": "47.0000", "original_amount": "47.0000", "discount_value": "0.0000", "product": { "id": "7c3aeb2d-5b8e-4bad-9cdd-3a1d8c4eab7e", "name": "E-book Estratégias Avançadas", "type": "DIGITAL" }, "price": { "id": "3d1f8ace-dd0f-4d4f-bd7f-cd0f1ddf6def", "title": "Oferta Especial", "price": "47.0000", "identifier": "PPP1234567891" } } ], "product": { "id": "7c3aeb2d-5b8e-4bad-9cdd-3a1d8c4eab7e", "name": "E-book Estratégias Avançadas", "type": "DIGITAL" } } ] } } ```