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

# Webhooks de assinatura

> Eventos de criação, ativação, renovação, falha de pagamento, cancelamento e expiração das assinaturas recorrentes.

As assinaturas cobram o cliente sozinhas, a cada ciclo, sem ninguém na tela. Os webhooks de assinatura são a forma de o seu sistema acompanhar isso: quando a assinatura começa, quando renova, quando uma cobrança falha e quando ela termina.

> [!NOTE]
>
> **Para o negócio:** estes eventos mantêm o acesso do assinante coerente com o pagamento. `subscription.renewed` estende o acesso, `subscription.payment_failed` é a hora de avisar o cliente para trocar o cartão e `subscription.expired` encerra o acesso quando as tentativas de cobrança se esgotam. Também é por eles que a sua régua de comunicação (boas-vindas, aviso de falha, oferta de reativação) pode ser disparada automaticamente.

## Quando usar

| Situação | Evento |
| - | - |
| Liberar o serviço e enviar boas-vindas | `subscription.activated` |
| Estender o acesso por mais um período | `subscription.renewed` |
| Avisar o cliente sobre cartão recusado | `subscription.payment_failed` |
| Encerrar o acesso após cancelamento | `subscription.cancelled` |
| Encerrar o acesso após esgotar as retentativas ou fim do plano | `subscription.expired` |
| Registrar a assinatura no seu CRM | `subscription.created` |
| Saber que a primeira cobrança em análise foi aprovada | `subscription.activated` (a assinatura sai de `pending_activation`) |

## Como funciona

O desenho abaixo mostra o que o seu sistema faz ao receber cada evento de assinatura.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart LR
    E1[["subscription.created"]]:::evento
    E2[["subscription.activated"]]:::evento
    E3[["subscription.renewed"]]:::evento
    E4[["subscription.payment_failed"]]:::evento
    E5[["subscription.cancelled"]]:::evento
    E6[["subscription.expired"]]:::evento
    A1["Registre a assinatura<br/>no seu CRM"]:::lojista
    A2["Libere o acesso e<br/>envie as boas-vindas"]:::ok
    A3["Estenda o acesso até<br/>current_period_end"]:::ok
    A4["Avise o cliente, com<br/>controle de frequência<br/>status continua active"]:::alerta
    Q5{"cancellation_type?"}:::decisao
    A5a["regret: revogue já<br/>refunded indica o estorno"]:::erro
    A5b["regular: mantenha até<br/>current_period_end"]:::neutro
    A6["Revogue o acesso e<br/>ofereça reativação"]:::erro
    E1 --> A1
    E2 --> A2
    E3 --> A3
    E4 --> A4
    E5 --> Q5
    Q5 -->|"até 7 dias"| A5a
    Q5 -->|"depois de 7 dias"| A5b
    E6 --> A6
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Cada cobrança de assinatura paga também gera `charge.created` e `charge.paid`. A recusa gera só o `subscription.payment_failed`.

**1. Assinatura criada**

Sua aplicação chama `POST /v1/subscriptions`. A Finvia envia `subscription.created`.

**2. Ativação**

Com a primeira cobrança aprovada (ou o início do trial), chega `subscription.activated`.

**3. Renovações**

A cada ciclo cobrado com sucesso, chega `subscription.renewed`, com o número do ciclo em `charge.billing_cycle`.

**4. Falhas e retentativas**

Se a cobrança de renovação falhar, cada tentativa malsucedida gera um `subscription.payment_failed`. A assinatura continua `active` enquanto houver tentativas.

**5. Encerramento**

Com o cancelamento chega `subscription.cancelled`. Com as tentativas esgotadas ou o fim do plano chega `subscription.expired`.

## Eventos disponíveis

| Evento | Quando é enviado |
| - | - |
| `subscription.created` | Uma nova assinatura é criada |
| `subscription.activated` | A assinatura é ativada (primeira cobrança bem-sucedida; em planos com trial, inclui a ativação em trial) |
| `subscription.renewed` | Uma cobrança recorrente é processada com sucesso (inclui a primeira cobrança cheia depois do trial) |
| `subscription.payment_failed` | **Cada tentativa** de cobrança recorrente que falha |
| `subscription.cancelled` | A assinatura é cancelada |
| `subscription.expired` | A assinatura é encerrada (limite de retentativas esgotado ou plano chegou ao `endDate`) |

> [!NOTE]
>
> Os eventos `subscription.trial_started` e `subscription.trial_ended` estão definidos no contrato de tipos, mas **não são entregues atualmente**. Não os implemente como ativos. Em planos com trial, acompanhe a ativação e a conversão pelos eventos `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial` no payload.

## Status da assinatura

| Valor | Significado |
| - | - |
| `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra e não renova. Se a análise aprovar o pagamento, ela passa a `active` automaticamente |
| `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança |
| `cancelled` | Cancelada |
| `expired` | Encerrada: limite de retentativas esgotado ou plano chegou ao `endDate` |

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Retentativa de renovação | Nas rodadas de cobrança das 06h, 12h e 18h (horário de Brasília), até o limite de tentativas recusadas no ciclo descrito em [Ciclo de vida da assinatura](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md) |
| Aviso de falha | Cada tentativa que falha gera um `subscription.payment_failed` |
| Fim das tentativas | Atingido o limite, a assinatura vira `expired` e chega `subscription.expired` |
| Primeira cobrança recusada | Gera `subscription.payment_failed` e a assinatura fica em `pending_activation`, sem nova tentativa automática |
| Fim do plano | Um plano com `endDate` também encerra a assinatura em `expired` |
| Trial grátis | A cobrança de validação de R\$ 1,00 e o estorno dela **não geram webhooks** |
| Formato | Envelope padrão com campos em **snake\_case**. Exceções: o objeto `trial` usa camelCase e `metadata` volta como foi enviada |
| Valores | Em reais: `99.9` é R\$ 99,90 |
| Destinos | Endpoints da conta dona da assinatura e endpoints da conta master com a opção de incluir subcontas. Assinaturas não têm `postbackUrl`. Veja [Quem recebe cada evento](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#quem-recebe-cada-evento) |
| Entrega | Veja [Entrega e retentativas](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#entrega-e-retentativas) |

> [!WARNING]
>
> Um cliente com cartão recusado pode gerar vários eventos `subscription.payment_failed` no mesmo ciclo, até três por dia. Se a sua aplicação envia um e-mail por evento, o cliente recebe vários e-mails em poucos dias. Controle a frequência dos avisos do seu lado, por exemplo um aviso por dia ou só na primeira e na última tentativa.

### Relação com os webhooks de cobrança

Cada cobrança de assinatura **paga** também dispara os webhooks `charge.created` e `charge.paid` da cobrança correspondente. A **recusa** de uma cobrança de assinatura **não** dispara webhook `charge.*` de recusa: quem avisa é o `subscription.payment_failed`.

Para ligar os dois fluxos:

* Nos eventos de assinatura, `data.charge.charge_id` é o **ID da cobrança**, o mesmo usado nos webhooks `charge.*` e em `GET /v1/charges/{id}`. Já `data.charge.id` é o ID do registro de cobrança da assinatura, outro identificador.
* No webhook `charge.paid` de uma cobrança de assinatura, o `metadata` traz `subscription_id` e `billing_cycle`, o que permite a ligação no sentido inverso.

> [!TIP]
>
> **Para o desenvolvedor:** se você trata `charge.paid` e `subscription.renewed`, o mesmo pagamento chega duas vezes por caminhos diferentes. Escolha um deles como referência para estender o acesso (o `subscription.renewed` é o mais direto) e use o outro só para conciliação financeira, evitando estender o acesso duas vezes.

## Envelope

Todos os webhooks de assinatura usam o envelope padrão, com campos em snake\_case. O `id` da raiz identifica o evento e é a chave da [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos). Não use `livemode` para separar teste de produção: as assinaturas não têm modo de teste.

```json theme={null}
{
  "id": "evt_7RtY2uI5oP8aS1dF4gH6jK9l",
  "event": "subscription.activated",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "active"
  }
}
```

### Campos base do objeto `data`

Presentes em todos os eventos:

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID da assinatura |
| `object` | string | Sempre `"subscription"` |
| `status` | string | Status atual |
| `merchant_id` | string | ID do merchant |
| `customer` | object | Dados do cliente |
| `plan` | object | Dados do plano |
| `current_period_start` | string \| null | Início do período atual (ISO 8601) |
| `current_period_end` | string \| null | Fim do período atual (ISO 8601) |
| `metadata` | object \| null | Metadados enviados por você |
| `created_at` | string | Data e hora de criação (ISO 8601) |
| `updated_at` | string | Data e hora da última atualização (ISO 8601) |

Em planos com trial, `subscription.activated` e `subscription.renewed` trazem também o objeto `trial`, com `startDate`, `endDate` e, depois da conversão, `convertedAt`. Esse objeto usa camelCase, diferente do resto do payload. `metadata` volta exatamente como você enviou.

### Objeto `customer`

```json theme={null}
{
  "id": "cu_abc123",
  "name": "Joao Silva",
  "email": "joao@email.com",
  "document_id": "52998224725"
}
```

### Objeto `plan`

Valores em **reais** (ex.: `99.9` para R\$ 99,90):

```json theme={null}
{
  "id": "plan_abc123",
  "name": "Plano Mensal",
  "price": 99.9,
  "currency": "BRL",
  "recurrence_type": "monthly"
}
```

### Objeto `charge`

Presente em `subscription.renewed` e `subscription.payment_failed`, e em `subscription.activated` **exceto no trial grátis** (não há cobrança na ativação). Valores em reais.

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID do registro de cobrança da assinatura (diferente do ID usado nos webhooks `charge.*`) |
| `charge_id` | string \| null | **ID da cobrança**, o mesmo dos webhooks `charge.*` e de `GET /v1/charges/{id}` |
| `billing_cycle` | integer | Número do ciclo de cobrança |
| `amount` | number | Valor em reais |
| `currency` | string | Moeda |
| `status` | string | Status da cobrança |
| `spread` | number \| null | Spread aplicado (em `activated` e `renewed`) |
| `net` | number \| null | Valor líquido em reais (em `activated` e `renewed`) |
| `is_trial_charge` | boolean | `true` se é a cobrança do trial (em `activated` e `renewed`) |
| `failure_reason` | string \| null | Motivo da falha (em `payment_failed`) |
| `created_at` | string | Data e hora da cobrança (ISO 8601) |

## Payloads por evento

### subscription.created

Enviado logo após a criação da assinatura. Traz só os campos base.

```json theme={null}
{
  "id": "evt_3NcV8bX1zL5kJ7hG2fD9sA4q",
  "event": "subscription.created",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "active",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document_id": "52998224725"
    },
    "plan": {
      "id": "plan_abc123",
      "name": "Plano Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrence_type": "monthly"
    },
    "current_period_start": "2024-01-15T10:30:00.000Z",
    "current_period_end": "2024-02-15T10:30:00.000Z",
    "metadata": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}
```

### subscription.activated

Enviado quando a assinatura é ativada. O conteúdo muda conforme o plano:

| Tipo de plano | Quando chega | Objeto `charge` | Objeto `trial` |
| - | - | - | - |
| Sem trial | Após a primeira cobrança aprovada | Sim, com `billing_cycle: 1` | Não |
| Trial pago | Após a cobrança do trial | Sim, com `is_trial_charge: true` e `billing_cycle: 0` | Sim |
| Trial grátis | Na criação | **Não** (não há cobrança) | Sim |

```json theme={null}
{
  "id": "evt_7RtY2uI5oP8aS1dF4gH6jK9l",
  "event": "subscription.activated",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "active",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document_id": "52998224725"
    },
    "plan": {
      "id": "plan_abc123",
      "name": "Plano Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrence_type": "monthly"
    },
    "current_period_start": "2024-01-15T10:30:00.000Z",
    "current_period_end": "2024-02-15T10:30:00.000Z",
    "metadata": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:05.000Z",
    "charge": {
      "id": "subchg_abc123",
      "charge_id": "2RhQg9M7ZCg3X3nMb9W2kY9R",
      "billing_cycle": 1,
      "amount": 99.9,
      "currency": "BRL",
      "spread": 3,
      "net": 96.9,
      "status": "paid",
      "is_trial_charge": false,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}
```

### subscription.renewed

Enviado quando uma cobrança recorrente é processada com sucesso. A estrutura é igual à do `subscription.activated`, com `billing_cycle` incrementado.

```json theme={null}
{
  "id": "evt_4WqE6rT9yU2iO5pA8sD1fG3h",
  "event": "subscription.renewed",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "active",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document_id": "52998224725"
    },
    "plan": {
      "id": "plan_abc123",
      "name": "Plano Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrence_type": "monthly"
    },
    "current_period_start": "2024-02-15T10:30:00.000Z",
    "current_period_end": "2024-03-15T10:30:00.000Z",
    "metadata": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-02-15T10:30:05.000Z",
    "charge": {
      "id": "subchg_def456",
      "charge_id": "2vXa7Bq4Nm1Kc8Lp3Zr6Td9Wf5",
      "billing_cycle": 2,
      "amount": 99.9,
      "currency": "BRL",
      "spread": 3,
      "net": 96.9,
      "status": "paid",
      "is_trial_charge": false,
      "created_at": "2024-02-15T10:30:00.000Z"
    }
  }
}
```

### subscription.payment\_failed

Enviado a **cada tentativa** de cobrança recorrente que falha. Traz `failure_reason` no topo de `data` e o objeto `charge` com os detalhes da falha.

```json theme={null}
{
  "id": "evt_8ZxC1vB4nM7qW2eR5tY9uI6o",
  "event": "subscription.payment_failed",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "active",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document_id": "52998224725"
    },
    "plan": {
      "id": "plan_abc123",
      "name": "Plano Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrence_type": "monthly"
    },
    "current_period_start": "2024-02-15T10:30:00.000Z",
    "current_period_end": "2024-03-15T10:30:00.000Z",
    "metadata": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-02-15T10:30:05.000Z",
    "failure_reason": "Recusa do banco emissor",
    "charge": {
      "id": "subchg_ghi789",
      "charge_id": "2kEs4Hu7Jy0Ob3Ni6Mt9Pq2Rw8",
      "billing_cycle": 2,
      "amount": 99.9,
      "currency": "BRL",
      "status": "failed",
      "failure_reason": "Recusa do banco emissor",
      "created_at": "2024-02-15T10:30:00.000Z"
    }
  }
}
```

> [!NOTE]
>
> `failure_reason` é um texto descritivo (ex.: `"Recusa do banco emissor"`, `"Cartão vencido"`). Use-o para exibir ou registrar, nunca para decidir o fluxo. `charge.charge_id` vem `null` só quando a tentativa nem chegou a ser enviada para cobrança (cartão vencido ou indisponível). Essa tentativa também conta para o limite de tentativas do ciclo.

### subscription.cancelled

Enviado quando a assinatura é cancelada. Traz `cancelled_at`, `cancellation_type` e `refunded`.

> [tab] Arrependimento (até 7 dias)
>
> ```json theme={null}
> {
>   "id": "evt_9MnB3vC6xZ1aS4dF7gH2jK5l",
>   "event": "subscription.cancelled",
>   "livemode": true,
>   "data": {
>     "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
>     "object": "subscription",
>     "status": "cancelled",
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document_id": "52998224725"
>     },
>     "plan": {
>       "id": "plan_abc123",
>       "name": "Plano Mensal",
>       "price": 99.9,
>       "currency": "BRL",
>       "recurrence_type": "monthly"
>     },
>     "current_period_start": "2024-01-15T10:30:00.000Z",
>     "current_period_end": "2024-02-15T10:30:00.000Z",
>     "metadata": null,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-16T10:30:00.000Z",
>     "cancelled_at": "2024-01-16T10:30:00.000Z",
>     "cancellation_type": "regret",
>     "refunded": true
>   }
> }
> ```

> [tab] Regular (após 7 dias)
>
> ```json theme={null}
> {
>   "id": "evt_6QaZ9wS2xE5dC8rF1vT4gB7y",
>   "event": "subscription.cancelled",
>   "livemode": true,
>   "data": {
>     "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
>     "object": "subscription",
>     "status": "cancelled",
>     "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
>     "customer": {
>       "id": "cu_abc123",
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document_id": "52998224725"
>     },
>     "plan": {
>       "id": "plan_abc123",
>       "name": "Plano Mensal",
>       "price": 99.9,
>       "currency": "BRL",
>       "recurrence_type": "monthly"
>     },
>     "current_period_start": "2024-01-15T10:30:00.000Z",
>     "current_period_end": "2024-02-15T10:30:00.000Z",
>     "metadata": null,
>     "created_at": "2024-01-15T10:30:00.000Z",
>     "updated_at": "2024-01-20T10:30:00.000Z",
>     "cancelled_at": "2024-01-20T10:30:00.000Z",
>     "cancellation_type": "regular",
>     "refunded": false
>   }
> }
> ```

| Tipo | Condição | Estorno | Acesso |
| - | - | - | - |
| `regret` | Até 7 dias após a criação | Todas as cobranças pagas. `refunded: true` se todas foram estornadas; `false` se não havia cobrança paga (ex.: trial grátis) ou se um estorno falhou | Revogado imediatamente |
| `regular` | Depois de 7 dias | Não há estorno (`refunded: false`) | Vale até o fim do período pago (controle da sua plataforma) |

> [!NOTE]
>
> No cancelamento regular, o status já é `cancelled` e as próximas cobranças não acontecem. `current_period_end` indica até quando o acesso do comprador vale, e é a sua plataforma que controla o acesso até essa data.

### subscription.expired

Enviado quando a assinatura é encerrada por esgotar as retentativas de cobrança ou porque o plano chegou ao `endDate`. Traz só os campos base.

```json theme={null}
{
  "id": "evt_5PlK8jH2gF6dS9aQ3wE7rT1y",
  "event": "subscription.expired",
  "livemode": true,
  "data": {
    "id": "2tYp6Wn3Kd9Rf1Lx8Qm4Vb7Hc2",
    "object": "subscription",
    "status": "expired",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document_id": "52998224725"
    },
    "plan": {
      "id": "plan_abc123",
      "name": "Plano Mensal",
      "price": 99.9,
      "currency": "BRL",
      "recurrence_type": "monthly"
    },
    "current_period_start": "2024-01-15T10:30:00.000Z",
    "current_period_end": "2024-02-15T10:30:00.000Z",
    "metadata": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-02-20T10:30:00.000Z"
  }
}
```

## Ciclo de vida em eventos

O desenho abaixo mostra os status da assinatura e o evento que acompanha cada mudança.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    NEW(["Nova assinatura<br/>POST /v1/subscriptions"]):::lojista
    PA["pending_activation<br/>1ª cobrança recusada<br/>ou em análise"]:::alerta
    ACT["active<br/>ativa e em dia"]:::ok
    REN[["subscription.renewed<br/>a cada ciclo cobrado<br/>continua active"]]:::evento
    FAL[["subscription.payment_failed<br/>a cada tentativa que falha<br/>continua active"]]:::evento
    CAN["cancelled<br/>cancelada, estado final"]:::neutro
    EXP["expired<br/>encerrada, estado final"]:::erro
    NEW -->|"created + activated"| ACT
    NEW -->|"created, e payment_failed<br/>se a 1ª foi recusada"| PA
    PA -->|"análise aprova<br/>activated"| ACT
    ACT -.-> REN
    ACT -.-> FAL
    ACT -->|"cancelamento<br/>cancelled"| CAN
    ACT -->|"tentativas esgotadas<br/>ou endDate · expired"| EXP
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Nos rótulos das setas, os eventos aparecem sem o prefixo `subscription.`.

| De | Para | Evento |
| - | - | - |
| (nova) | `active` | `subscription.created` e `subscription.activated` |
| (nova) | `pending_activation` | `subscription.created` e, se a primeira cobrança foi recusada, `subscription.payment_failed` |
| `pending_activation` | `active` | `subscription.activated`, quando a análise aprova a primeira cobrança |
| `active` | `active` | `subscription.renewed` |
| `active` | `active` | `subscription.payment_failed` (o status continua `active`) |
| `active` | `cancelled` | `subscription.cancelled` |
| `active` | `expired` | `subscription.expired` |

`cancelled` e `expired` são estados finais. Para o cliente voltar, crie uma nova assinatura. Uma assinatura em `pending_activation` também não é cobrada de novo: para tentar outra vez, crie uma nova assinatura e, se quiser, cancele a pendente.

## Passo a passo

```javascript Node.js theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { event, data } = req.body;
  res.status(200).send('OK');

  switch (event) {
    case 'subscription.created':
      await crm.registerSubscription(data.id, data.customer.email);
      break;

    case 'subscription.activated':
      // Liberar acesso e enviar boas-vindas
      await access.grant(data.id, data.current_period_end);
      if (data.trial) {
        // Assinatura em trial: data.trial.endDate indica quando a primeira cobrança cheia acontece
      }
      break;

    case 'subscription.renewed':
      // Estender o acesso até o fim do novo período
      await access.extend(data.id, data.current_period_end, data.charge.billing_cycle);
      break;

    case 'subscription.payment_failed':
      // Avisar o cliente (controle a frequência do seu lado)
      // Não há troca de cartão: oriente a cancelar e criar outra assinatura
      await notify.paymentFailed(data.customer.email, data.failure_reason);
      break;

    case 'subscription.cancelled':
      if (data.cancellation_type === 'regret') {
        // data.refunded indica se as cobranças pagas foram estornadas
        // (false quando não havia cobrança paga, como no trial grátis)
        await access.revokeNow(data.id);
      } else {
        // Manter o acesso até data.current_period_end
        await access.revokeAt(data.id, data.current_period_end);
      }
      break;

    case 'subscription.expired':
      await access.revokeNow(data.id);
      // Enviar oferta de reativação
      break;

    default:
      console.log(`Evento não tratado: ${event}`);
  }
});
```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Código esperando `subscription.trial_started` nunca dispara | Esse evento não é entregue atualmente | Use `subscription.activated` e `subscription.renewed` com o objeto `trial` |
| Cobrança da assinatura não encontrada em `GET /v1/charges/{id}` | Consulta feita com `data.charge.id`, que é o ID do registro de cobrança da assinatura | Use `charge_id` para consultar a cobrança |
| Acesso estendido duas vezes no mesmo ciclo | Tratamento de `charge.paid` e `subscription.renewed` para o mesmo pagamento | Escolha um único evento como referência para o acesso |
| Esperando `charge.*` de recusa na renovação | A recusa de assinatura só gera `subscription.payment_failed` | Trate `subscription.payment_failed` |
| Erro ao ler `charge` no trial grátis | O `subscription.activated` do trial grátis não tem `charge` | Verifique se `data.charge` existe antes de ler |
| Lógica baseada em `failure_reason` falha | O campo é texto livre, não código | Use-o só para exibir ou registrar |

## Perguntas frequentes

> [accordion] O cliente teve o cartão recusado. A assinatura é cancelada imediatamente?
>
> Não. Ela continua `active` enquanto houver retentativas, nas rodadas das 06h, 12h e 18h (horário de Brasília), até o limite descrito em [Ciclo de vida da assinatura](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md). Se todas falharem, ela vira `expired` e chega `subscription.expired`.

> [accordion] Como o cliente troca o cartão de uma assinatura?
>
> Não existe troca de cartão na assinatura. O caminho é cancelar a assinatura atual e criar outra com o novo cartão. A nova começa um ciclo novo, com cobrança imediata. Veja [Ciclo de vida da assinatura](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md).

> [accordion] A validação de R\$ 1,00 do trial grátis gera webhook?
>
> Não. A cobrança de validação e o estorno dela não geram webhooks. No trial grátis, o `subscription.activated` chega na criação, sem o objeto `charge`.

> [accordion] Até quando mantenho o acesso depois de um cancelamento regular?
>
> Até `current_period_end`. O status já é `cancelled` e as cobranças pararam, mas o período pago continua valendo. Quem controla o acesso até essa data é a sua plataforma.

> [accordion] Como sei de qual assinatura veio um charge.paid?
>
> O `metadata` do `charge.paid` de uma cobrança de assinatura traz `subscription_id` e `billing_cycle`.

## Como testar

> [!WARNING]
>
> Assinaturas não têm sandbox: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

| Código | Cenário | O que comprovar |
| - | - | - |
| SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada |
| SUB-05 | Receber `subscription.created` e `subscription.activated` | Eventos recebidos e respondidos com `2xx` |
| SUB-06 | Cancelar em até 7 dias | `cancellationType: "regret"`, `refunded: true` e webhook `subscription.cancelled` |

## Veja também

> [card] [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Como a cobrança recorrente funciona.

> [card] [Ciclo de vida da assinatura](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, retentativa e cancelamento.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Os eventos charge.\* de cada cobrança.

> [card] [Webhooks: visão geral](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Destinos, formatos, entrega e deduplicação.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.