Ciclo de vida da assinatura
Entenda por que a assinatura nasce DRAFT, quando fica ACTIVE, como renova e como termina.
O problema: a confirmação chega depois
Quando você chama POST /plans/offer/{id}/subscribe, a resposta 201 chega antes de o gateway criar a assinatura. Por isso a resposta sempre traz status: DRAFT, mesmo quando tudo vai dar certo.
O resultado chega depois, pelos webhooks ou por GET /subscriptions/{id}.
Existem dois tipos de assinatura, com caminhos diferentes:
| Tipo | Como nasce | Quem cobra a cada ciclo |
|---|---|---|
| Cartão de crédito | Pela API ou pelo checkout da PagPolar | O gateway |
| PIX ou boleto | Só pelo checkout da PagPolar | A PagPolar gera uma cobrança nova a cada ciclo |
Pela API, a assinatura é sempre no cartão. As assinaturas em PIX ou boleto aparecem nos webhooks e nas consultas porque o webhook da sua credencial também recebe as vendas do checkout.
Assinatura no cartão
O diagrama mostra os status de uma assinatura no cartão.
| Status | Significado | Evento | O que fazer |
|---|---|---|---|
DRAFT | Assinatura registrada. O gateway ainda não confirmou. | SUBSCRIPTION_CREATED e depois SUBSCRIPTION_CONFIRMED | Registre. Não libere o acesso. |
ACTIVE | A cobrança do ciclo foi paga. | Primeiro ciclo: nenhum evento de assinatura próprio; confira status em GET /subscriptions/{id}. A partir do segundo ciclo: SUBSCRIPTION_RENEWED. | Libere ou mantenha o acesso. |
PROCESSING | O gateway informou uma cobrança pendente. | Nenhum evento próprio | Consulte a assinatura se precisar do detalhe. |
CANCELING | Você pediu o cancelamento e o gateway ainda não confirmou. | Nenhum evento | Espere SUBSCRIPTION_CANCELED. |
CANCELED | O cancelamento foi efetivado, a pedido seu ou por aviso do gateway (cancelamento ou recusa). | SUBSCRIPTION_CANCELED | Revogue o acesso. Se precisar da data, confira end_at em GET /subscriptions/{id}. |
FAILED | O gateway recusou a criação ou informou falha. | SUBSCRIPTION_FAILED na criação | Não libere o acesso. |
EXPIRED | O gateway informou que a assinatura expirou. | Nenhum evento próprio no cartão | Revogue o acesso. |
SUBSCRIPTION_CONFIRMED não ativa a assinatura
Depois de SUBSCRIPTION_CONFIRMED, o status continua DRAFT. Ele só vira ACTIVE quando o gateway informa a cobrança paga.
O status segue sempre o último aviso do gateway. Por isso a assinatura pode sair de qualquer status para outro, conforme o gateway informa.
DELETE /subscriptions/{id} só muda o status de uma assinatura no cartão quando ela está ACTIVE. Em outro status, a resposta é 200 e nada muda.
Assinatura em PIX ou boleto
O diagrama mostra os status de uma assinatura em PIX ou boleto.
| Status | Significado | Evento | O que fazer |
|---|---|---|---|
PENDING_PAYMENT | Espera o pagamento da primeira cobrança. | SUBSCRIPTION_CREATED | Não libere o acesso. |
ACTIVE | O ciclo está pago. | TRANSACTION_PAID da cobrança do ciclo | Libere ou mantenha o acesso. |
PENDING_RENEWAL | Chegou a data da renovação e ela ainda não foi paga. | TRANSACTION_PENDING quando a nova cobrança é gerada e SUBSCRIPTION_DELAYED enquanto está atrasada | Lembre o cliente de pagar. |
EXPIRED | O prazo de carência acabou sem pagamento. | SUBSCRIPTION_EXPIRED | Revogue o acesso. |
CANCELED | Cancelada na hora do pedido. | SUBSCRIPTION_CANCELED | Revogue o acesso. |
Diferenças em relação ao cartão:
- A renovação paga chega como
TRANSACTION_PAID. Não existeSUBSCRIPTION_RENEWEDpara PIX ou boleto. - O cancelamento vale na hora, sem passar por
CANCELING. - A PagPolar confere atrasos e expirações uma vez por dia.
Reembolso, estorno e chargeback cancelam a assinatura
Pedidos de reembolso, estornos e chargebacks de vendas da assinatura também pedem o cancelamento dela. Veja em quais casos em Reembolso e chargeback também cancelam.