subscription.* - PurinCash

Uma assinatura é um Pix Automático: o cliente paga o primeiro ciclo e, no mesmo QR, autoriza os próximos no app do banco. Depois disso cada renovação é cobrada sozinha. Tudo que muda nela chega na callbackUrl que você mandou ao criar (ou na URL da conta). O paymentId muda a cada ciclo (psa_sub_…, psa_sub_…_c1, psa_sub_…_c2). O subscriptionId é o mesmo em todos os eventos: é por ele que você acha o assinante.

`subscription.authorized`

O banco do cliente aprovou a recorrência. A partir daqui as renovações saem sozinhas.

{
  "event": "subscription.authorized",
  "subscriptionId": "RN12345678202609200000000001",
  "paymentId": "psa_sub_a1b2c3d4",
  "status": "ativa",
  "amountCents": 4990,
  "frequency": "MONTHLY",
  "nextChargeDate": "2026-10-20",
  "customer": { "name": "João Silva", "externalId": "user_42" },
  "metadata": "{\"plano\":\"premium\"}"
}

O primeiro pagamento chega separado, como um payment.paid normal do paymentId da criação. Autorização e pagamento são atos diferentes no banco e podem chegar em qualquer ordem.

`payment.paid` de renovação

Cada ciclo pago é um payment.paid como outro qualquer, com dois campos a mais:

{
  "event": "payment.paid",
  "paymentId": "psa_sub_a1b2c3d4_c2",
  "subscriptionId": "RN12345678202609200000000001",
  "subscriptionCycle": 2,
  "amountCents": 4990,
  "status": "paid",
  "paidAt": "2026-11-20T09:12:00.000Z",
  "customer": { "name": "João Silva", "externalId": "user_42" },
  "metadata": "{\"plano\":\"premium\"}"
}

subscriptionCycle é 0 no primeiro pagamento e cresce a cada renovação. Renove o acesso pelo subscriptionId, nunca pelo paymentId.

`subscription.charge_failed`

Uma cobrança recorrente não liquidou. A assinatura continua ativa: quando a política permite, a retentativa é pedida sozinha (até 3 em 7 dias), e o ciclo seguinte é enviado normalmente.

{
  "event": "subscription.charge_failed",
  "subscriptionId": "RN12345678202609200000000001",
  "cycle": 2,
  "dueDate": "2026-11-20",
  "reason": "rejeitada",
  "detail": "AM04 Saldo insuficiente"
}

reason é rejeitada, expirada ou cancelada. detail traz o código e a descrição que o banco devolveu, quando há.

`subscription.cancelled`

Acabou: pela loja (reason: "merchant"), pelo cliente ou pelo banco (cancelada), recusada na autorização (rejeitada) ou vencida (expirada). Não haverá novas cobranças.

{
  "event": "subscription.cancelled",
  "subscriptionId": "RN12345678202609200000000001",
  "status": "cancelada",
  "reason": "merchant",
  "detail": "cliente pediu"
}

Derrube o acesso pela data, não pelo evento: quando um ciclo não é pago, a validade que você guardou vence sozinha. O subscription.cancelled é o aviso de que não vale esperar pela próxima.

Mesmas garantias dos outros eventos: assinatura HMAC no X-Webhook-Signature, idempotência por X-Webhook-Id e reentrega com backoff. Veja Validando a assinatura.

​subscription.authorized

​payment.paid de renovação

​subscription.charge_failed

​subscription.cancelled

`subscription.authorized`

`payment.paid` de renovação

`subscription.charge_failed`

`subscription.cancelled`