> ## 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.

# Ciclo de vida da assinatura

> Status, retentativa de cobrança, atualização, cancelamento com arrependimento de 7 dias e histórico de cobranças.

Depois de criada, a assinatura passa por renovações, eventuais falhas de cobrança e, em algum momento, termina por cancelamento ou expiração. Esta página explica cada etapa, o que a Finvia faz sozinha e o que a sua plataforma precisa controlar.

> [!NOTE]
>
> **Para o negócio:** três regras resumem a operação. Primeiro, quando o cartão é recusado na renovação, a Finvia tenta de novo por alguns dias antes de encerrar a assinatura. Segundo, não há troca de cartão nem de plano: o cliente cancela e assina de novo, com cobrança imediata. Terceiro, pela regra da plataforma, cancelamentos em até 7 dias da criação da assinatura estornam automaticamente tudo o que foi pago; depois disso, não há estorno e o acesso vale até o fim do período pago.

> [!WARNING]
>
> Assinaturas não têm modo de teste: 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).

## Status da assinatura

| Status | Significado | Cobra e renova? |
| - | - | - |
| `pending_activation` | A primeira cobrança foi recusada ou está em análise. Não tem retentativa automática e não expira sozinha. Se a análise aprovar o pagamento, passa a `active` automaticamente | Não |
| `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança | Sim |
| `cancelled` | Cancelada pelo usuário ou pelo sistema | Não |
| `expired` | Encerrada: limite de retentativas de cobrança esgotado ou plano chegou ao `endDate` | Não |

`cancelled` e `expired` são estados finais. Para o cliente voltar a assinar, crie uma nova assinatura.

O desenho abaixo mostra como a assinatura passa de um status para outro e o aviso 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
    S(["POST /v1/subscriptions"]):::neutro
    PA["pending_activation<br/>aguardando ativação<br/>não cobra nem renova"]:::alerta
    ACT["active<br/>ativa e em dia, inclusive<br/>durante as retentativas"]:::ok
    CAN["cancelled<br/>cancelada"]:::erro
    EXP["expired<br/>encerrada"]:::erro
    FIM(["Estados finais<br/>para voltar, crie uma<br/>nova assinatura"]):::neutro
    S -->|"1ª cobrança aprovada<br/>ou início do trial<br/>subscription.activated"| ACT
    S -->|"1ª cobrança recusada<br/>ou em análise"| PA
    PA -->|"análise aprovou<br/>subscription.activated"| ACT
    ACT -->|"cancelamento<br/>subscription.cancelled"| CAN
    PA -->|"cancelamento<br/>subscription.cancelled"| CAN
    ACT -->|"retentativas esgotadas<br/>ou endDate do plano<br/>subscription.expired"| EXP
    CAN -.-> FIM
    EXP -.-> FIM
    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
```

### Assinatura parada em `pending_activation`

A rotina de cobrança só processa assinaturas `active`. Uma assinatura `pending_activation` não é cobrada de novo, não renova e não expira sozinha. Ela só sai desse status em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (`firstCharge.pending: true` ou `trialCharge.pending: true`) e a análise aprovou. Aí ela passa a `active` e chega `subscription.activated`. Se a análise recusar, chega `subscription.payment_failed` e ela continua parada. `PATCH /v1/subscriptions/{id}` também não destrava, porque só aceita assinaturas `active`.

Para tentar de novo pela API (por exemplo, com outro cartão), crie uma **nova** assinatura com `POST /v1/subscriptions`. A API não reaproveita a pendente: a nova tem outro `id`. Cancele a pendente com `POST /v1/subscriptions/{id}/cancel` para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada.

## Como funciona

**1. Criação e ativação**

A assinatura nasce `active` quando a primeira cobrança é aprovada (ou o trial começa). Se a primeira cobrança é recusada ou fica em análise, ela fica em `pending_activation`.

**2. Renovação a cada ciclo**

Uma rotina roda às 6h, 12h e 18h (horário de Brasília) e cobra as assinaturas cujo período terminou. Com sucesso, chega `subscription.renewed`.

**3. Retentativas em caso de falha**

Se a renovação for recusada, as rodadas seguintes tentam de novo. Cada recusa gera `subscription.payment_failed`.

**4. Encerramento**

A assinatura termina por cancelamento (`cancelled`) ou por expiração (`expired`), quando as tentativas se esgotam ou o plano chega ao `endDate`.

## Ciclo de cobrança e renovação

Não há como escolher o dia da cobrança. O ciclo segue estas regras:

| Situação | Como funciona |
| - | - |
| Sem trial | A primeira cobrança acontece na criação, e o ciclo fica ancorado na data e hora da contratação. `currentPeriodEnd` é o início mais 1 semana (`weekly`), 2 semanas (`biweekly`), 1 mês (`monthly`) ou N dias (`custom`) |
| Com trial | O primeiro ciclo pago começa quando o trial termina e a cobrança é feita. Essa data passa a ser a referência |
| Mensal | O dia de referência é mantido. Uma contratação em 31/01 renova em 28/02 (ou 29/02) e volta para 31/03 |
| Renovação | Uma rotina roda às 6h, 12h e 18h (horário de Brasília). A cobrança sai na primeira rodada do **dia seguinte** à data de `currentPeriodEnd` |
| Deslocamento | O novo período começa exatamente no fim do anterior. O atraso de algumas horas até a rodada não desloca o ciclo |

Exemplo: uma assinatura mensal contratada em 15/01 às 10h30 cobre o período até 15/02 às 10h30. A renovação sai na rodada das 6h de 16/02, e o novo período vai de 15/02 às 10h30 até 15/03 às 10h30.

**Em validação (V-34):** o time Finvia ainda confirma a cobrança no "dia seguinte" ao fim do período e o limite de 12 tentativas antes da publicação.

## Retentativa de cobrança

Quando a cobrança de renovação é recusada, a Finvia tenta de novo automaticamente:

| Regra | Valor |
| - | - |
| Retentativas no mesmo dia | Nas rodadas seguintes do dia (12h e 18h, horário de Brasília) |
| Dias seguintes | Novas tentativas nas três rodadas (6h, 12h e 18h) |
| Limite por ciclo | **12 tentativas recusadas** no mesmo ciclo (cerca de 4 dias) |
| Aviso a cada falha | Webhook `subscription.payment_failed`, com `failure_reason` |
| Ao atingir o limite | A assinatura passa a `expired` e chega `subscription.expired` |
| Status durante as tentativas | Continua `active` |
| Tentativa sem envio à cobrança (cartão vencido ou indisponível) | Conta para o limite; `charge.charge_id` vem `null` no webhook |

Um plano com `endDate` também encerra a assinatura em `expired` quando o período seguinte começaria depois dessa data.

O desenho abaixo mostra a renovação de um ciclo, com as novas tentativas quando o cartão é recusado.

```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
    FIM(["currentPeriodEnd<br/>fim do período"]):::neutro
    COB["Rotina cobra o cartão<br/>rodadas de 6h, 12h e 18h"]:::finvia
    Q1{"Cobrança<br/>aprovada?"}:::decisao
    REN[["subscription.renewed"]]:::evento
    NOV(["Novo período começa<br/>no fim do anterior"]):::ok
    FAL[["subscription.payment_failed<br/>com failure_reason"]]:::evento
    Q2{"Chegou a 12 recusas<br/>no ciclo? (V-34)"}:::decisao
    PRO["Próxima rodada<br/>12h e 18h no mesmo dia,<br/>depois 6h, 12h e 18h"]:::alerta
    EXP(["expired"]):::erro
    EVX[["subscription.expired"]]:::evento
    FIM -->|"1ª rodada do dia seguinte<br/>(em validação, V-34)"| COB
    COB --> Q1
    Q1 -->|"sim"| REN
    REN --> NOV
    NOV -.->|"próximo ciclo"| FIM
    Q1 -->|"não"| FAL
    FAL --> Q2
    Q2 -->|"não: segue active"| PRO
    PRO --> COB
    Q2 -->|"sim"| EXP
    EXP --> EVX
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    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
```

O dia seguinte e o limite de 12 tentativas estão em validação (V-34), como indicado acima.

> [!NOTE]
>
> Enquanto houver retentativas pendentes, a assinatura continua `active`. Use o `subscription.payment_failed` para avisar o comprador a atualizar o cartão. Como não existe troca de cartão na assinatura, o caminho é cancelar e criar outra (veja [Trocar cartão ou plano](#trocar-cartão-ou-plano)).

> [!NOTE]
>
> **Para o negócio:** a janela de retentativas é a oportunidade de recuperar o assinante. Uma régua de comunicação comum é avisar na primeira falha ("tivemos um problema com o seu cartão") e reforçar perto do fim das tentativas, com um link para o cliente assinar de novo com outro cartão.

## Atualizar a assinatura

Apenas `metadata` pode ser atualizado, e só em assinaturas `active`.

```bash cURL theme={null}
curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "notes": "Cliente VIP"
    }
  }'
```

Resposta `200`:

```json theme={null}
{
  "success": true,
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "metadata": { "notes": "Cliente VIP" }
}
```

| Campo atualizável | Tipo | Descrição |
| - | - | - |
| `metadata` | object | Metadados adicionais da assinatura |

### Trocar cartão ou plano

> [!WARNING]
>
> Não existe troca de cartão, troca de plano, alteração de valor nem pausa. **Para trocar o cartão ou o plano, cancele a assinatura e crie outra.** A nova assinatura começa um ciclo novo, **com cobrança imediata**.

**1. Registre o novo cartão (se for troca de cartão)**

`POST /v1/cards` com os dados do novo cartão.

**2. Cancele a assinatura atual**

`POST /v1/subscriptions/{id}/cancel`. Atenção à regra de 7 dias explicada abaixo.

**3. Crie a nova assinatura**

`POST /v1/subscriptions` com o novo `cardTokenId` ou o novo `subscriptionPlanId`. A primeira cobrança acontece imediatamente.

> [!NOTE]
>
> **Para o negócio:** na troca, o cliente paga a nova assinatura imediatamente, mesmo que ainda tenha dias do período anterior. Se a troca acontece depois de 7 dias da contratação, não há estorno automático da assinatura antiga. Defina a sua política (por exemplo, conceder dias extras ou fazer a troca perto da data de renovação) e comunique ao cliente antes.

## Cancelamento

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cliente solicitou cancelamento"
  }'
```

O corpo é opcional. O campo `reason` aceita até 500 caracteres.

A API trata o cancelamento de duas formas, conforme a data de criação da assinatura. O cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas e vem com `cancellationType` igual a `regret` (arrependimento):

| | Arrependimento (`regret`) | Regular (`regular`) |
| - | - | - |
| Quando | Até 7 dias após a criação (em dias completos) | Depois de 7 dias |
| Estorno | **Todas as cobranças pagas** da assinatura são estornadas automaticamente: trial pago, primeira cobrança e renovações dentro do período | Sem estorno |
| `refunded` | `true` quando havia cobrança paga e todas foram estornadas; `false` quando não havia o que estornar (ex.: trial grátis) ou quando um estorno não foi concluído | `false` |
| Status | `cancelled` | `cancelled` |
| Cobranças futuras | Param | Param imediatamente |
| Acesso | Encerrado **na hora** | Continua até `accessRevokedAt` (fim do período pago, `current_period_end`). Sua plataforma controla |
| Webhook | `subscription.cancelled` com `cancellation_type: "regret"` | `subscription.cancelled` com `cancellation_type: "regular"` e `refunded: false` |

O desenho abaixo mostra o que acontece em cada tipo de cancelamento.

```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
    IN(["POST /v1/subscriptions/{id}/cancel"]):::neutro
    Q{"Até 7 dias completos<br/>da criação?"}:::decisao
    RG["regret<br/>arrependimento"]:::alerta
    RG1["Estorna todas as<br/>cobranças pagas<br/>refunded: true se havia"]:::finvia
    RG2(["Acesso encerrado na hora<br/>bloqueie já"]):::erro
    RE["regular<br/>depois de 7 dias"]:::neutro
    RE1["Sem estorno<br/>refunded: false<br/>cobranças param"]:::finvia
    RE2(["Acesso até accessRevokedAt<br/>sua plataforma bloqueia"]):::alerta
    EV[["status cancelled<br/>subscription.cancelled<br/>com cancellation_type"]]:::evento
    IN --> Q
    Q -->|"sim"| RG
    Q -->|"não"| RE
    RG --> RG1 --> RG2
    RE --> RE1 --> RE2
    RG2 --> EV
    RE2 --> EV
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    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
```

### Regra dos 7 dias

Regra da plataforma: se a assinatura for cancelada em até 7 dias da criação, todas as cobranças pagas dela são estornadas automaticamente e o acesso é encerrado na hora. Depois desse prazo, o cancelamento não gera estorno e o acesso continua até o fim do período pago.

* A regra é automática para todo cancelamento dentro da janela, venha ele do lojista ou da Finvia, por qualquer motivo. Ela não depende de pedido do comprador e vale também para venda entre empresas.
* A janela conta a partir da **criação da assinatura**, e não da entrega do produto ou serviço nem da primeira cobrança.
* A contagem é em dias completos: um cancelamento feito até 7 dias e 23 horas depois da criação ainda é `regret`.
* Não existe opção para cancelar dentro da janela sem estornar.

**Em validação (V-51):** o jurídico da Finvia decide se esta página cita a base legal (art. 49 do CDC) e com que ressalva.

### Arrependimento (até 7 dias)

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "cancelled",
  "cancellationType": "regret",
  "refunded": true,
  "refundId": "2RhQg9M7ZCg3X3nMb9W4kA1T",
  "accessRevokedAt": "2024-01-16T10:30:00.000Z"
}
```

`refundId` identifica o estorno (pode ser `null`). `accessRevokedAt` indica quando o acesso foi revogado.

> [!WARNING]
>
> No cancelamento por arrependimento, confira `refunded`. Se vier `false` numa assinatura que tinha cobrança paga, um estorno não foi concluído e o valor ainda não voltou ao cliente. Acompanhe pelo histórico da assinatura ou acione o suporte da Finvia.

### Cancelamento regular (depois de 7 dias)

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "cancelled",
  "cancellationType": "regular",
  "refunded": false,
  "accessRevokedAt": "2024-02-15T10:30:00.000Z"
}
```

No cancelamento regular, `accessRevokedAt` é só a **data até a qual o acesso do comprador vale** (fim do período já pago). O status já é `cancelled` e as cobranças pararam. É a **sua plataforma** que mantém o acesso até essa data e o encerra depois.

> [!TIP]
>
> **Para o desenvolvedor:** ao receber a resposta do cancelamento (ou o webhook `subscription.cancelled`), grave `accessRevokedAt` no seu sistema e agende o bloqueio do acesso para essa data. No caso `regret`, bloqueie imediatamente.

## Histórico de cobranças

A consulta da assinatura por ID traz o histórico de tentativas de cobrança em `charges`. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo `billingCycle`. A lista vem ordenada por `billingCycle` decrescente, e `billingCycle: 0` é a cobrança do trial pago.

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "active",
  "currentPeriodStart": "2024-01-15T10:30:00.000Z",
  "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
  "cancelledAt": null,
  "cancellationType": null,
  "refunded": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "plan": {
    "id": "2RhQg9M7ZCg3X3nMb9W2kY9R",
    "name": "Plano Premium Mensal",
    "price": 99.9,
    "currency": "BRL",
    "recurrenceType": "monthly"
  },
  "customer": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "name": "Joao Silva",
    "email": "joao@email.com"
  },
  "merchant": {
    "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "tradeName": "Loja Exemplo"
  },
  "charges": [
    {
      "id": "2RhQg9M7ZCg3X3nMb9W3kZ0S",
      "billingCycle": 1,
      "billingPeriodStart": "2024-01-15T10:30:00.000Z",
      "billingPeriodEnd": "2024-02-15T10:30:00.000Z",
      "amount": 99.90,
      "currency": "BRL",
      "status": "paid",
      "pspTransactionId": "12345",
      "failureReason": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "metadata": { "referralCode": "PROMO2024" }
}
```

### Status das cobranças da assinatura

| Status | Significado |
| - | - |
| `pending` | Em análise |
| `paid` | Paga com sucesso |
| `failed` | Falhou (o motivo vem em `failureReason`) |
| `refunded` | Estornada |

> [!NOTE]
>
> `charges[].id` é o id do **registro de cobrança da assinatura** (igual a `data.charge.id` nos webhooks de assinatura) e não funciona em `GET /v1/charges/{id}`. O id da cobrança vem em `firstCharge.chargeId` e `trialCharge.chargeId` na criação, em `data.charge.charge_id` nos webhooks e em `data[].chargeId` na listagem de cobranças do plano (`GET /v1/subscription-plans/{id}/charges`), que traz também `id`, `subscriptionId` e `billingCycle`. Veja [Consultar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md).

### Listar assinaturas

`GET /v1/subscriptions` é paginada e aceita os filtros `merchantId`, `customerId`, `status` (`pending_activation`, `active`, `cancelled`, `expired`), `search` (nome ou e-mail do cliente, ou nome do plano), `page` (padrão `1`) e `size` (padrão `10`).

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions?customerId=2vorkDcXyvzifL63YX09S9VqcnI&status=active" \
  -u "$FINVIA_API_KEY:"
```

> [!TIP]
>
> **Para o desenvolvedor:** antes de criar uma assinatura, consulte se o cliente já tem uma `active` no mesmo plano com `GET /v1/subscriptions?customerId=...&status=active`. Isso evita assinaturas duplicadas quando o cliente clica duas vezes ou volta ao checkout.

## Webhooks do ciclo de vida

| Evento | Quando |
| - | - |
| `subscription.created` | Nova assinatura criada |
| `subscription.activated` | Primeira cobrança bem-sucedida (em planos com trial, inclui a ativação em trial) |
| `subscription.renewed` | Cobrança recorrente processada (inclui a primeira cobrança cheia após o trial) |
| `subscription.payment_failed` | Falha na cobrança recorrente (um por tentativa) |
| `subscription.cancelled` | Assinatura cancelada |
| `subscription.expired` | Assinatura encerrada (limite de retentativas ou fim do plano) |

Cada cobrança de assinatura paga também dispara `charge.created` e `charge.paid`. A recusa de uma cobrança de assinatura **não** dispara webhook `charge.*` de recusa: quem avisa é o `subscription.payment_failed`. Payloads completos em [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md).

## Boas práticas

1. **Valide o plano antes do checkout.** Consulte `GET /v1/subscription-plans/{id}` e confirme que o plano está `active`.
2. **Trate falha na primeira cobrança.** Se a resposta da criação vier com `status: "pending_activation"` e `firstCharge.success: false`, ofereça ao cliente tentar de novo com outro cartão, criando uma nova assinatura, e cancele a pendente.
3. **Não duplique em caso de análise.** Se `firstCharge.pending` vier `true`, o pagamento está em análise. Não crie outra assinatura: aguarde `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado).
4. **Avise o cliente sobre a renovação.** Envie um lembrete alguns dias antes da cobrança automática.
5. **Trate cartão vencido ou recusado.** A cada tentativa que falha chega `subscription.payment_failed`. Oriente o cliente a cancelar e criar outra assinatura com o novo cartão.
6. **Use `metadata`.** Guarde dados que ligam a assinatura ao seu sistema:

```json theme={null}
{
  "metadata": {
    "referralCode": "PROMO2024",
    "campaignId": "black-friday",
    "internalUserId": "12345"
  }
}
```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `Only active subscriptions can be updated` | Tentativa de atualizar assinatura que não está `active` | Só atualize `metadata` de assinaturas ativas |
| `400` `Subscription already cancelled or expired` | Cancelamento de assinatura já encerrada | Consulte o status antes de cancelar |
| `404` `Subscription not found` | `id` incorreto | Confira o `id` com a listagem |
| Cliente perdeu o acesso antes do fim do período | Acesso bloqueado no momento do cancelamento `regular` | Mantenha o acesso até `accessRevokedAt` |
| Cliente com acesso depois de cancelar em até 7 dias | Acesso não revogado no cancelamento `regret` | No `regret`, revogue imediatamente |
| Tentativa de trocar cartão via `PATCH` | Só `metadata` é atualizável | Cancele e crie nova assinatura |
| Assinatura `pending_activation` não é cobrada de novo | Não há retentativa da primeira cobrança | Crie uma nova assinatura com outro cartão e cancele a pendente |
| `GET /v1/charges/{id}` não encontra a cobrança de um ciclo | Foi usado `charges[].id`, que é o registro da assinatura | Use o `chargeId` (veja [Histórico de cobranças](#histórico-de-cobranças)) |

## Perguntas frequentes

> [accordion] Quantas vezes a Finvia tenta cobrar um cartão recusado?
>
> Hoje, até 12 tentativas recusadas no mesmo ciclo, nas rodadas das 6h, 12h e 18h (horário de Brasília), ao longo de cerca de 4 dias. No limite, a assinatura passa a `expired` e chega `subscription.expired`.

> [accordion] Posso pausar uma assinatura?
>
> Não. Não há pausa. A alternativa é cancelar e, quando o cliente quiser voltar, criar uma nova assinatura.

> [accordion] O cliente cancelou no 5º dia. O que acontece com o dinheiro?
>
> Pela regra da plataforma, é um cancelamento por arrependimento (`regret`): todas as cobranças pagas são estornadas automaticamente e o acesso é encerrado na hora. Confira `refunded: true` na resposta.

> [accordion] O cliente cancelou no 20º dia de um plano mensal. Ele perde o acesso imediatamente?
>
> Não deveria. O status vira `cancelled` e as cobranças param, mas o acesso vale até `accessRevokedAt`, o fim do período já pago. Quem controla isso é a sua plataforma.

> [accordion] Assinatura expirada pode ser reativada?
>
> Não. `expired` é um estado final. Crie uma nova assinatura para o cliente.

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada |
| SUB-05 | Webhooks de criação e ativação | Eventos recebidos e respondidos com HTTP 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 criar assinaturas.

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Preço, recorrência e trial.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Payloads de cada evento.

> [card] [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md)
>
> Contrato completo da rota.


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