> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purincash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# subscription.*

> Autorizou, renovou, falhou, cancelou. Quatro eventos, uma chave estável: o subscriptionId.

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](/webhooks/visao-geral)).

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.

```json theme={null}
{
  "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\"}"
}
```

<Note>
  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.
</Note>

## `payment.paid` de renovação

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "event": "subscription.cancelled",
  "subscriptionId": "RN12345678202609200000000001",
  "status": "cancelada",
  "reason": "merchant",
  "detail": "cliente pediu"
}
```

<Warning>
  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.
</Warning>

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](/webhooks/assinatura).