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

# Assinaturas: visão geral

> Cobre seus clientes automaticamente a cada semana, quinzena, mês ou intervalo definido, com cartão de crédito.

As assinaturas cobram o cartão do cliente automaticamente, em intervalos regulares, sem que ele precise voltar ao seu site a cada ciclo. Servem para planos mensais de software, clubes de assinatura, mensalidades de cursos, academias e qualquer serviço com cobrança recorrente.

> [!NOTE]
>
> **Para o negócio:** com assinatura, a Finvia cuida da cobrança de cada ciclo e das novas tentativas quando o cartão é recusado, e avisa o seu sistema de cada renovação, falha e cancelamento. O cancelamento em até 7 dias da contratação estorna automaticamente as cobranças pagas (veja [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)). A sua equipe define o plano (preço e periodicidade) e a sua plataforma controla o acesso do assinante a partir dos avisos.

> [!WARNING]
>
> **Assinaturas e cadastro de cartão não têm modo de teste.** Mesmo com a chave de teste (`sk_test_`), as cobranças da assinatura são **reais**, inclusive a validação de R\$ 1,00 do trial grátis. O cadastro do cartão (`POST /v1/cards`) também é real, mas não cobra nada. O cofre é o mesmo para teste e produção: um cartão salvo na homologação funciona com a chave de produção. Para homologar, use um cartão real com valor baixo e cancele a assinatura no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas. Veja o [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Quando usar

| Situação | Use assinatura? |
| - | - |
| Plano mensal de SaaS, clube, academia, curso | Sim |
| Cobrança semanal, quinzenal ou a cada N dias | Sim (`weekly`, `biweekly` ou `custom`) |
| Período de teste grátis ou pago antes da primeira mensalidade | Sim, com trial no plano |
| Recompra rápida em que o cliente está presente | Não. Use [cartão salvo](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) com CVV |
| Cobrança recorrente por Pix | Não documentado. As assinaturas são descritas apenas com cartão de crédito |
| Valor diferente a cada ciclo | Não. O preço fica fixo na assinatura no momento da contratação |

### Assinatura ou cartão salvo?

| | Assinatura | Cartão salvo |
| - | - | - |
| Quem inicia a cobrança | A Finvia, automaticamente, a cada ciclo | A sua aplicação, com o cliente presente |
| CVV a cada cobrança | Não | Sim, obrigatório |
| Valor | Fixo, definido no plano | Livre, definido em cada cobrança |
| Retentativa automática em recusa | Sim, nas renovações ([Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)). A primeira cobrança não tem retentativa | Não |
| Indicado para | Mensalidades e planos | Compra com um clique, recompra |

## As três peças

| Peça | O que é | Rota |
| - | - | - |
| Cliente (customer) | Quem assina. Precisa de e-mail e CPF ou CNPJ | `/v1/customers` |
| Plano (subscription plan) | Preço, moeda, periodicidade e trial | `/v1/subscription-plans` |
| Assinatura (subscription) | O vínculo entre um cliente, um plano e um cartão | `/v1/subscriptions` |

O cartão, guardado no [cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md), é o meio de pagamento da assinatura.

O desenho abaixo mostra como cliente, plano e cartão se juntam na assinatura e o que acontece a cada ciclo.

```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
    subgraph CAD["Criados pela sua aplicação"]
        CLI["Cliente<br/>/v1/customers<br/>e-mail e CPF ou CNPJ"]:::neutro
        PLA["Plano<br/>/v1/subscription-plans<br/>preço, BRL, periodicidade"]:::neutro
        CAR["Cartão no cofre<br/>/v1/cards<br/>já nasce active"]:::neutro
    end
    ASS["Assinatura<br/>/v1/subscriptions<br/>preço congelado"]:::finvia
    CLI -->|"customerId"| ASS
    PLA -->|"subscriptionPlanId"| ASS
    CAR -->|"cardTokenId"| ASS
    ASS ==>|"1ª cobrança aprovada<br/>ou início do trial"| ATV(["active"]):::ok
    ATV -->|"a cada ciclo"| REN["Finvia cobra o cartão<br/>às 6h, 12h ou 18h<br/>sem CVV"]:::finvia
    REN -->|"aprovada"| EOK[["subscription.renewed"]]:::evento
    REN -->|"recusada"| EKO[["subscription.payment_failed<br/>e novas tentativas"]]:::evento
    EOK -.->|"novo ciclo"| ATV
    EKO -->|"tentativas esgotadas"| EXP(["expired"]):::erro
    EOK --> SIS["Sua plataforma controla<br/>o acesso pelos avisos"]:::lojista
    EKO --> SIS
    style CAD fill:#F7F9FC,stroke:#D5DCE6
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    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 neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

## Como funciona

O fluxo recomendado é o **cards-first**: o cartão é registrado antes e a assinatura é criada a partir dele.

A sequência abaixo mostra o fluxo cards-first de ponta a ponta, com a diferença entre plano com trial grátis e os demais.

```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}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant C as Assinante
    end
    box rgb(243,245,248) Sua aplicação
        participant S as Seu servidor
        participant W as Receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant P as Processador do cartão
    end
    Note over S,F: Antes, uma vez só: POST /v1/subscription-plans cria o plano
    C->>S: Escolhe o plano e informa o cartão
    S->>F: POST /v1/customers
    F-->>S: id do cliente
    S->>F: POST /v1/cards
    F-->>S: id do cartão · active
    S->>F: POST /v1/subscriptions (subscriptionPlanId, customerId, cardTokenId)
    alt Trial grátis sem skipTrial
        F->>P: Cobra R$ 1,00 e estorna (validação do cartão)
    else Trial pago, sem trial ou skipTrial
        F->>P: Cobra o valor do trial ou o valor cheio
    end
    P-->>F: Resultado
    F-->>S: 201 · status · firstCharge (ou cardValidation)
    F-)W: subscription.created e, se ativada, subscription.activated
    S-->>C: Libera o acesso
    Note over F,P: Nos ciclos seguintes, a Finvia cobra sozinha e avisa com subscription.renewed ou subscription.payment_failed
```

**1. Crie o cliente**

`POST /v1/customers` com nome, e-mail, CPF ou CNPJ. Veja [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md).

**2. Crie o plano**

`POST /v1/subscription-plans` com preço, moeda `BRL` e recorrência. Normalmente feito uma vez, na configuração do produto. Veja [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md).

**3. Registre o cartão**

`POST /v1/cards` com os dados do cartão. O cartão já nasce ativo.

**4. Crie a assinatura com cardTokenId**

`POST /v1/subscriptions` com `subscriptionPlanId`, `customerId` e `cardTokenId`.

**5. Primeira cobrança**

A primeira cobrança é processada imediatamente (ou o trial começa). Se aprovada, a assinatura fica `active`.

**6. Cobranças automáticas**

A cada ciclo, a Finvia cobra o cartão e envia os webhooks de renovação ou de falha.

> [!NOTE]
>
> O cartão já nasce **ativo** ao ser registrado. Não existe transação de teste nem etapa de ativação, e o campo `validateCard` é obsoleto e não tem efeito.

## Formas de criar a assinatura

A criação combina duas escolhas: como informar o **cartão** e como informar o **cliente**.

| Cartão | Cliente | Quando usar |
| - | - | - |
| `cardTokenId` (cartão já registrado) | `customerId` | Fluxo recomendado (cards-first). Cliente e cartão já existem |
| `paymentMethod` (cartão digitado, registrado na mesma chamada) | `customerId` | Cliente já cadastrado, cartão novo |
| `paymentMethod` | Objeto `customer` (cria ou localiza pelo e-mail) | Checkout de assinatura em uma única chamada |

> [!WARNING]
>
> Envie `customerId` **ou** `customer`, nunca os dois. Da mesma forma, envie `cardTokenId` **ou** `paymentMethod`. Quando o cartão vai em `paymentMethod`, o cliente precisa ter e-mail e CPF ou CNPJ; com o objeto `customer`, envie `document`. Se já existir um cliente com o mesmo e-mail, vale o documento desse cadastro.

> [tab] 1. cardTokenId (recomendado)
>
> ```bash cURL theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>     "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
>     "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
>   }'
> ```
>
> O cartão precisa estar `active` e pertencer ao mesmo merchant da chave de API.

> [tab] 2. Cartão inline
>
> ```bash cURL theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>     "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
>     "paymentMethod": {
>       "number": "1111222233334444",
>       "holderName": "JOAO SILVA",
>       "expirationMonth": "12",
>       "expirationYear": "2028",
>       "cvv": "123"
>     }
>   }'
> ```
>
> O cartão informado é registrado no cofre e passa a ser o cartão da assinatura. O cliente precisa ter e-mail e CPF ou CNPJ.

> [tab] 3. Cliente e cartão inline
>
> ```bash cURL theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>     "customer": {
>       "name": "Joao Silva",
>       "email": "joao@email.com",
>       "document": { "type": "cpf", "id": "52998224725" },
>       "phoneNumber": "+5511987654321"
>     },
>     "paymentMethod": {
>       "number": "1111222233334444",
>       "holderName": "JOAO SILVA",
>       "expirationMonth": "12",
>       "expirationYear": "2028",
>       "cvv": "123"
>     },
>     "metadata": { "referralCode": "PROMO2024" }
>   }'
> ```
>
> A API procura um cliente com o mesmo e-mail e, se não encontrar, cria um novo.

### Campos da criação

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `subscriptionPlanId` | string | Sim | ID do plano. O plano precisa estar ativo |
| `customerId` | string | Um dos dois | ID de cliente existente |
| `customer` | object | Um dos dois | `name` e `email` obrigatórios; `document` com `type` (`cpf` ou `cnpj`) e `id` (11 ou 14 dígitos), obrigatório quando o cartão vai em `paymentMethod`; `phoneNumber` opcional |
| `cardTokenId` | string | Um dos dois | ID de cartão já registrado pela mesma conta |
| `paymentMethod` | object | Um dos dois | `number`, `holderName`, `expirationMonth` (2 caracteres), `expirationYear` (4 caracteres), `cvv` (mínimo 3) |
| `skipTrial` | boolean | Não | `true` pula o trial do plano e cobra o valor cheio imediatamente. Padrão `false` |
| `metadata` | object | Não | Dados seus, livres (ex.: código de indicação, ID do usuário no seu sistema) |
| `validateCard` | boolean | Não | Obsoleto, sem efeito |

> [!NOTE]
>
> Não há como escolher o dia da cobrança: o ciclo é ancorado na data e hora da contratação (ou no fim do trial). Um `billingDay` enviado é ignorado, sem erro.

### Resposta

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "active",
  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "currentPeriodStart": "2024-01-15T10:30:00.000Z",
  "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
  "firstCharge": {
    "success": true,
    "chargeId": "2xKp7QmR4tVw9YzA1bC3dE5fG6h",
    "nsuOperacao": "123456789",
    "codigoAutorizacao": "ABC123",
    "message": "Transaction approved"
  }
}
```

| Campo | Descrição |
| - | - |
| `id` | ID da assinatura. Guarde para consultar e cancelar |
| `status` | `active` ou `pending_activation` |
| `cardTokenId` | ID do cartão usado. No cartão inline, é o cartão recém-registrado |
| `currentPeriodStart` e `currentPeriodEnd` | Período coberto pela primeira cobrança |
| `firstCharge` | Resultado da primeira cobrança: `success`, `pending` (em análise), `chargeId` (id da cobrança, usado em `GET /v1/charges/{id}`), `nsuOperacao` (identificador da operação no processador), `codigoAutorizacao` e `message` |
| `trialCharge` | Em plano com trial pago: resultado da cobrança do trial, com os mesmos campos |
| `cardValidation` | Em plano com trial grátis: `{ "validated": true, "amount": 1 }` |

> [!TIP]
>
> **Para o desenvolvedor:** guarde o `firstCharge.chargeId`. A [consulta da assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md) não devolve o id da cobrança: o `charges[].id` de lá é o registro da assinatura.

## O que acontece no checkout

O desenho abaixo mostra cada verificação feita na criação da assinatura e o resultado de cada caminho.

```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"]):::neutro
    Q1{"Plano existe<br/>e está ativo?"}:::decisao
    E404["404 Subscription plan<br/>not found or inactive"]:::erro
    CLI["Cria ou localiza o cliente<br/>pelo e-mail"]:::finvia
    Q2{"Cartão veio em<br/>paymentMethod?"}:::decisao
    REG["Registra o cartão<br/>no cofre"]:::finvia
    E400["400 Failed to register card<br/>cliente sem e-mail<br/>ou CPF/CNPJ"]:::erro
    Q3{"Trial grátis<br/>sem skipTrial?"}:::decisao
    VAL["Cobra R$ 1,00<br/>e estorna em seguida"]:::finvia
    E422["422 CARD_VALIDATION_FAILED<br/>nada é criado"]:::erro
    COB["Primeira cobrança imediata<br/>trial pago ou valor cheio"]:::finvia
    Q5{"Resultado da<br/>cobrança?"}:::decisao
    ACT(["active<br/>libere o acesso"]):::ok
    PEN(["pending_activation<br/>peça outro cartão e<br/>crie nova assinatura"]):::erro
    ANA(["pending_activation<br/>firstCharge.pending: true<br/>aguarde o webhook"]):::alerta
    IN --> Q1
    Q1 -->|"não"| E404
    Q1 -->|"sim"| CLI
    CLI --> Q2
    Q2 -->|"sim"| REG
    Q2 -->|"não, cardTokenId"| Q3
    REG -->|"cadastro incompleto"| E400
    REG -->|"ok"| Q3
    Q3 -->|"sim"| VAL
    Q3 -->|"não"| COB
    VAL -->|"recusada, em análise<br/>ou sem resposta"| E422
    VAL -->|"aprovada: trial começa"| ACT
    COB --> Q5
    Q5 -->|"aprovada"| ACT
    Q5 -->|"recusada"| PEN
    Q5 -->|"em análise"| ANA
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    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
```

**1. Validação do plano**

O plano é validado. Plano inexistente ou inativo gera `404` com `Subscription plan not found or inactive`.

**2. Cliente**

O cliente é criado ou localizado pelo e-mail. Se ele já existe, vale o documento do cadastro.

**3. Cartão**

Com `paymentMethod`, o cartão é registrado no cofre da Finvia e já nasce ativo. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`.

**4. Validação do trial grátis**

Em plano com **trial grátis** (sem `skipTrial`), a Finvia cobra R\$ 1,00 e estorna em seguida, para validar o cartão. Se a cobrança for recusada, ficar em análise ou o processador não responder, a resposta é `422 CARD_VALIDATION_FAILED` e nada é criado. Reenviar a mesma requisição em até 15 minutos reaproveita uma validação aprovada.

**5. Primeira cobrança**

A primeira cobrança é feita imediatamente: o valor do trial pago, ou o valor cheio quando não há trial.

**6. Gravação**

A assinatura é gravada com status `active` se a cobrança for aprovada.

### Primeira cobrança recusada ou em análise

| Resposta | Significado | O que fazer |
| - | - | - |
| `status: "active"` e `firstCharge.success: true` | Cobrança aprovada | Liberar o acesso |
| `status: "pending_activation"` e `firstCharge.success: false` | Primeira cobrança recusada | A assinatura não está ativa, não cobra, não renova e não tem retentativa. Peça outro cartão, crie uma nova assinatura (ela terá outro `id`) e cancele a pendente |
| `firstCharge.pending: true` | Pagamento em análise | **Não** crie outra assinatura. Aguarde `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado) |

> [!WARNING]
>
> Com a primeira cobrança em análise, criar uma segunda assinatura para "tentar de novo" pode resultar em duas assinaturas cobrando o mesmo cliente se a análise aprovar a primeira. Aguarde o webhook.

## Ciclo de cobrança

* O ciclo fica ancorado na **data e hora da contratação**. Em plano com trial, a referência passa a ser o fim do trial, quando a primeira cobrança cheia é feita.
* No mensal, o dia de referência é mantido mesmo em meses mais curtos.
* As renovações são feitas por uma rotina que roda às **6h, 12h e 18h (horário de Brasília)**. Se a renovação for recusada, há novas tentativas e, no limite delas, a assinatura passa a `expired`.

Os detalhes de status, retentativa, atualização e cancelamento estão em [Ciclo de vida da assinatura](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md).

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Moeda | Planos cobrados no cartão aceitam só `BRL` |
| Cliente | Precisa de e-mail e CPF ou CNPJ quando o cartão é cadastrado. O tipo é deduzido pelos dígitos (11 é CPF, 14 é CNPJ); outro tamanho conta como sem documento |
| Cartão | Precisa pertencer ao mesmo merchant da chave. As cobranças da assinatura não pedem CVV |
| Preço congelado | Preço e periodicidade ficam congelados na contratação. Editar o plano não muda assinaturas existentes |
| Split | As cobranças recorrentes de assinatura não recebem split |
| Sem troca | Não há troca de cartão, troca de plano, alteração de valor nem pausa. Para trocar, cancele e crie outra |
| Arrependimento | Regra da plataforma: cancelamento em até 7 dias da criação estorna todas as cobranças pagas |
| Permissão da chave | Depende do perfil de quem gerou a chave. Veja a tabela abaixo |

### Permissões por perfil

A chave de API herda o perfil do usuário que a gerou, e cada rota de planos e assinaturas exige uma permissão. Sem ela, a resposta é `403`:

```json theme={null}
{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }
```

| Rota | Permissão exigida |
| - | - |
| `POST /v1/subscriptions` | criar assinaturas |
| `GET /v1/subscriptions`, `GET /v1/subscriptions/summary`, `GET /v1/subscriptions/{id}` | visualizar assinaturas |
| `PATCH /v1/subscriptions/{id}` | atualizar assinaturas |
| `POST /v1/subscriptions/{id}/cancel` | cancelar assinaturas |
| `GET /v1/subscription-plans`, `GET /v1/subscription-plans/{id}`, `GET /v1/subscription-plans/{id}/charges` | visualizar assinaturas |
| `POST /v1/subscription-plans` | criar assinaturas |
| `PUT /v1/subscription-plans/{id}`, `POST /v1/subscription-plans/{id}/image`, `PATCH /v1/subscription-plans/{id}/status`, `PATCH /v1/subscription-plans/{id}/status/confirm` | atualizar assinaturas |

| Perfil padrão | Acesso às rotas de planos e assinaturas |
| - | - |
| Owner, Manager e Operador | Todas |
| Visualizador | Só as de leitura (`GET`); nas demais, `403` |
| Desenvolvedor e Financeiro | Nenhuma: `403` em todas |
| Perfis personalizados | Dependem das permissões marcadas |

Para integrar assinaturas, gere a chave com um usuário Owner ou Manager.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` `Subscription plan not found or inactive` | Plano inexistente ou inativo | Confira o plano com `GET /v1/subscription-plans/{id}` antes do checkout |
| `400` `Failed to create subscription` | Dados inválidos ou falha na criação | Confira se enviou só um entre `customerId` e `customer`, e só um entre `cardTokenId` e `paymentMethod` |
| `400` `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos (inclusive um cadastro antigo com o mesmo e-mail) | Use um cliente com e-mail e CPF ou CNPJ, informado por `customerId` |
| `422 CARD_VALIDATION_FAILED` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta | Peça outro cartão. Veja [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) |
| `409 CARD_VALIDATION_IN_PROGRESS` ou `429 CARD_VALIDATION_RATE_LIMITED` | Requisição repetida em paralelo, ou recusas demais do mesmo cartão ou da conta | Veja os limites em [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) |
| `403` `Acesso negado` | O perfil do usuário que gerou a chave não tem a permissão da rota | Veja [Permissões por perfil](#permissões-por-perfil) |
| Cobrança real feita com a chave de teste | Assinaturas não têm modo de teste | Use um cartão real com valor baixo e cancele no mesmo dia |
| Assinatura em `pending_activation` | Primeira cobrança recusada | Peça outro cartão, crie nova assinatura e cancele a pendente |

## Perguntas frequentes

> [accordion] Preciso criar o cliente e o cartão antes?
>
> Não é obrigatório. É possível criar tudo em uma chamada, com o objeto `customer` e o `paymentMethod`. O fluxo cards-first (cliente e cartão antes) é o recomendado porque separa os erros de cadastro dos erros de cobrança.

> [accordion] Posso testar assinaturas no sandbox?
>
> Não. Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Use um cartão real com valor baixo e cancele no mesmo dia: o cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas.

> [accordion] Se eu aumentar o preço do plano, os assinantes atuais pagam mais?
>
> Não. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só as novas assinaturas usam o novo preço.

> [accordion] Posso oferecer assinatura com Pix?
>
> A documentação descreve assinaturas apenas com cartão de crédito.

> [accordion] Como o cliente troca de plano?
>
> Não existe troca de plano. Cancele a assinatura atual e crie outra no novo plano. A nova começa um ciclo novo, com cobrança imediata.

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| SUB-01 | Registrar cartão | `status: "active"` e `pendingActivation: false` |
| SUB-03 | Criar plano em `BRL` | Retorna o `id` do plano |
| SUB-04 | Criar assinatura | Status `active` e primeira cobrança processada (cobrança real, mesmo com a chave de teste) |
| SUB-05 | Webhooks de criação e ativação | `subscription.created` e `subscription.activated` recebidos |
| SUB-06 | Cancelar em até 7 dias | `cancellationType: "regret"` e `refunded: true` |

## Veja também

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

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

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

> [card] [SaaS e assinaturas](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)
>
> Caso de uso completo.


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