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

# Cobrança recorrente e assinaturas

> Crie planos, assine clientes e automatize cobranças recorrentes (mensalidades, SaaS, clubes) com renovação, trial e webhooks na UvviPay.

A cobrança recorrente da UvviPay cobra de novo no intervalo que você escolher: mensalidade, SaaS, clube ou outro serviço com pagamento repetido.

Você cria o plano uma vez (valor, moeda e frequência) e depois assina o cliente. A cada ciclo a UvviPay gera uma fatura, cobra o método padrão e avisa por webhook.

* Cobrança em intervalos fixos.
* Renovação e novas tentativas sem você ter que intervir.
* Cartão tokenizado (PCI) ou PIX, sem guardar dados de cartão.
* Webhook a cada mudança de status.

## Quando usar

> [card] Mensalidades e SaaS
>
> Acesso a plataformas, aplicativos ou APIs com cobrança mensal ou anual.

> [card] Clubes e assinaturas
>
> Clubes de benefícios, comunidades, caixas mensais e programas de fidelidade.

> [card] Cursos e conteúdo
>
> Cursos, mídia e conteúdo premium com renovação automática.

> [card] Contratos de serviço
>
> Manutenção, suporte e prestação de serviço com cobrança periódica.

## Conceitos

| Termo | O que é |
| - | - |
| **Plano** | Valor, moeda e frequência (mensal, anual, etc.). Você cria uma vez e reusa em vários clientes. |
| **Cliente** | Quem você cobra. Depois da primeira assinatura, o cadastro fica na sua conta com um `customer_id`. Use esse `customer_id` nas assinaturas seguintes. |
| **Assinatura** | O vínculo entre um cliente e um plano. A UvviPay cobra a cada ciclo a partir daqui. |
| **Fatura** | Cobrança de um ciclo da assinatura. Cada renovação gera uma nova fatura. |
| **Ciclo** | Período coberto por uma fatura (ex.: 1 mês). |
| **Trial** | Período de teste gratuito antes da primeira cobrança. |
| **Carência** | Dias de tolerância depois de uma falha de cobrança, antes do cancelamento. |

## Como funciona

**1. Crie um plano**

Defina valor, moeda e frequência (`POST /v1/subscriptions/plan`). A frequência é definida uma vez e não muda depois.

**2. Assine o cliente**

Envie o cliente e o meio de pagamento (`POST /v1/subscriptions`). Se o
cliente já estiver cadastrado, prefira `customer_id`. O bloco `customer`
também reaproveita o cadastro pelo e-mail. Sem trial, a primeira cobrança acontece neste
request (`201` se cartão pago ou PIX pendente; `422` / `UVV154147` se o cartão
for recusado). Se o trial for aceito, a API responde `201` sem cobrança
inicial. A primeira cobrança acontece no fim do trial. Em `pix_type: automatic`,
o trial deve terminar no mínimo em 3 dias. Duração menor responde `422` /
`UVV154490`.

**3. Primeira cobrança**

Sem trial, o resultado da cobrança já vem na resposta HTTP. Em PIX pendente,
aguarde a confirmação pelo webhook. Os eventos `subscription.activated`,
`subscription.past_due` e os demais cobrem as mudanças seguintes.

**4. Renovação automática**

A cada ciclo, a UvviPay gera a próxima fatura e cobra o método de pagamento padrão.

```mermaid theme={null}
flowchart LR
    P["Plano<br/>(valor + cadência)"] --> S["Assinatura<br/>(cliente + meio)"]
    S --> F["Fatura do ciclo"]
    F --> C{"Cobrança"}
    C -->|Paga| A["ACTIVE +<br/>próxima fatura"]
    C -->|PIX pendente| W["PENDING + QR"]
    W -->|Pago| A
    C -->|Falha| R["Retentativas /<br/>PAST_DUE"]
    A --> F
```

## Pré-requisitos

**1. Produto habilitado**

O produto Recorrência precisa estar ativo na sua conta. A equipe UvviPay
faz a ativação. Peça ao seu contato comercial.

**2. Credenciais de API**

Use `client-id` e `client-secret` no backend. Nunca exponha o
`client-secret` no front-end. Veja [Autenticação](https://developers.uvvipay.com.br/authentication.md).

**3. Webhooks (recomendado)**

Cadastre um endpoint para receber `subscription.*` e acompanhar a ativação
sem consultar a API o tempo todo. Veja [Webhooks](https://developers.uvvipay.com.br/webhooks.md).

> [!WARNING]
>
> Não envie dados de cartão a partir do navegador. Chame os endpoints de assinatura
> e de troca de método de pagamento só do seu backend (PCI).

## Catálogo (planos)

| Ação | Método | Endpoint |
| - | - | - |
| [Criar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/create.md) | `POST` | `/v1/subscriptions/plan` |
| [Consultar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/get.md) | `GET` | `/v1/subscriptions/plan/{planId}` |
| [Listar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/list.md) | `GET` | `/v1/subscriptions/plans` |
| [Atualizar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/update.md) | `PATCH` | `/v1/subscriptions/plan/{planId}` |
| [Desativar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/deactivate.md) | `POST` | `/v1/subscriptions/plan/{planId}/deactivate` |
| [Ativar](https://developers.uvvipay.com.br/api-reference/recurrency/plans/activate.md) | `POST` | `/v1/subscriptions/plan/{planId}/activate` |

> [!NOTE]
>
> A frequência do plano (`interval` / `custom_interval`) não muda depois da
> criação. Se você tentar alterar, a API responde `422`.

## Assinaturas

| Ação | Método | Endpoint |
| - | - | - |
| [Criar](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/create.md) | `POST` | `/v1/subscriptions` (`201` / `422`) |
| [Consultar](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/get.md) | `GET` | `/v1/subscriptions/{subscriptionId}` |
| [Listar](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/list.md) | `GET` | `/v1/subscriptions` |
| [Cancelar](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/cancel.md) | `POST` | `/v1/subscriptions/{subscriptionId}/cancel` |
| [Trocar meio de pagamento](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/update-payment-method.md) | `POST` | `/v1/subscriptions/{subscriptionId}/payment-method` |
| [Reativar](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/reactivate.md) | `POST` | `/v1/subscriptions/{subscriptionId}/reactivate` |

## Faturas

| Ação | Método | Endpoint |
| - | - | - |
| [Listar](https://developers.uvvipay.com.br/api-reference/recurrency/invoices/list.md) | `GET` | `/v1/subscriptions/invoices` |
| [Consultar](https://developers.uvvipay.com.br/api-reference/recurrency/invoices/get.md) | `GET` | `/v1/subscriptions/invoices/{invoiceId}` |

## Clientes

| Ação | Método | Endpoint |
| - | - | - |
| [Criar](https://developers.uvvipay.com.br/api-reference/recurrency/customers/create.md) | `POST` | `/v1/customers` |
| [Listar](https://developers.uvvipay.com.br/api-reference/recurrency/customers/list.md) | `GET` | `/v1/customers` |
| [Consultar](https://developers.uvvipay.com.br/api-reference/recurrency/customers/get.md) | `GET` | `/v1/customers/{customerId}` |

### Status da assinatura

| Status | Significado |
| - | - |
| `PENDING` | Criada. Aguardando a primeira cobrança. |
| `TRIAL` | Em período de teste gratuito. |
| `ACTIVE` | Cobrança ativa e renovando. |
| `PAST_DUE` | A cobrança falhou. Ainda há tentativas restantes. |
| `CANCELLED` | Encerrada pelo cliente ou por falha de pagamento. |

## Exemplo prático

### 1) Criar um plano mensal

Defina valor, moeda e frequência do plano:

```bash Criar plano theme={null}
curl -X POST https://api.uvvipay.com.br/v1/subscriptions/plan \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "name": "Plano Mensal Pro",
    "description": "Acesso completo",
    "amount": 9900,
    "pricing_type": "FIXED_PRICE",
    "currency": "BRL",
    "interval": "MONTHLY",
    "custom_interval": null,
    "allowed_payment_types": ["credit_card"],
    "default_trial_unit": null,
    "default_trial_duration": null,
    "prevent_trial_abuse": true
  }'
```

### 2) Assinar um cliente

Envie o cliente e o meio de pagamento (`credit_card` ou `pix`) com o
`subscription_plan_id`. Sem trial, a primeira cobrança acontece neste request.
Não envie dados de cartão quando `type` for `pix`.

```bash Assinar cliente theme={null}
curl -X POST https://api.uvvipay.com.br/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "subscription_plan_id": "PLAN_UUID",
    "grace_period_days": 3,
    "trial_duration": null,
    "trial_unit": null,
    "transaction_idempotency_id": "sub-create-0001",
    "customer": {
      "external_customer_id": "customer-ext-0001",
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "11987654321",
      "address": {
        "street": "Rua Exemplo",
        "street_number": "100",
        "zip_code": "01310100",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "neighborhood": "Bela Vista"
      },
      "document": {
        "number": "12345678901",
        "type": "cpf"
      }
    },
    "payment_methods": {
      "number": "4111111111111111",
      "holder_name": "JOAO DA SILVA",
      "security_code": "123",
      "expiration_month": 12,
      "expiration_year": 2030,
      "main_payment_method": true,
      "type": "credit_card"
    }
  }'
```

PIX sem trial: `payment_methods` pode ser só `{ "type": "pix" }`. A resposta inclui `pix.qrcode`.

### 3) Assinar um cliente que já existe

Cadastre o cliente com [`POST /v1/customers`](https://developers.uvvipay.com.br/api-reference/recurrency/customers/create). Guarde o `id`. Na criação da assinatura, envie esse valor em `customer_id` e não reenvie os dados do cliente.

A criação aceita duas formas de identificar o cliente. Envie uma. Nunca as duas.

| Campo | Quando usar | O que a API faz |
| - | - | - |
| `customer_id` | O cliente já está na sua conta | Usa esse cliente na assinatura |
| `customer` | Primeira assinatura do cliente | Cria o cadastro, ou reaproveita o que já existe pelo e-mail |

Para obter o `customer_id`:

1. Crie o cliente com [`POST /v1/customers`](https://developers.uvvipay.com.br/api-reference/recurrency/customers/create) e use o `id` da resposta.
2. Ou liste com [`GET /v1/customers`](https://developers.uvvipay.com.br/api-reference/recurrency/customers/list) e use o `id` de cada item.

```bash Assinar cliente existente theme={null}
curl -X POST https://api.uvvipay.com.br/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "subscription_plan_id": "PLAN_UUID",
    "grace_period_days": 3,
    "transaction_idempotency_id": "sub-create-0002",
    "customer_id": "660e8400-e29b-41d4-a716-446655440000",
    "payment_methods": {
      "type": "pix",
      "main_payment_method": true
    }
  }'
```

O resto da criação não muda. Plano, `payment_methods`, trial, carência e idempotência funcionam igual nas duas formas.

#### O que muda com `customer_id`

* A API não olha nome, e-mail, telefone nem documento. Por isso `UVV154640` e `UVV154718` não aparecem.
* A busca é na sua conta. Um `customer_id` de outra conta responde `404`.
* O cadastro do cliente não muda. Nem `customer_id` nem `customer` atualizam quem já está salvo.

#### Erros do cliente na criação

| HTTP | `code` | Forma | Causa |
| - | - | - | - |
| `400` | - | ambas | Enviou `customer_id` e `customer` juntos, ou não enviou nenhum |
| `404` | `UVV154225` | `customer_id` | O `customer_id` não existe na sua conta |
| `422` | `UVV154640` | `customer` | Dados diferentes do cadastro para o mesmo `external_customer_id`, ou para o mesmo e-mail em cadastro criado antes da identidade por e-mail |
| `422` | `UVV154718` | `customer` | E-mail já ligado a outro `external_customer_id` |
| `409` | `UVV154158` | ambas | O cliente já tem assinatura neste plano |
| `422` | `UVV154361` | ambas | Pix Automático sem endereço completo |

> [!WARNING]
>
> Pix Automático (`pix_type: automatic`) pede endereço completo: `zip_code`,
> `street`, `street_number`, `neighborhood`, `city`, `state` e `country`.
>
> Se o cliente já está salvo sem endereço, `customer_id` não resolve. A API
> responde `422` / `UVV154361` e não cria a assinatura.
>
> Cadastre o endereço na primeira assinatura. Não há endpoint público para
> atualizar o cadastro depois. Enviar `customer` com `address` vale só para
> aquela criação: o cliente que já existe continua sem endereço.
>
> PIX imediato e cartão não pedem endereço.

> [!NOTE]
>
> O endereço dentro de `customer` é opcional. Se você enviar `address`, preencha
> todos os campos. Se faltar algum, a API responde `400`. Envie o endereço na
> primeira assinatura se pretende usar Pix Automático depois.

> [!NOTE]
>
> A idempotência considera a forma de identificar o cliente. Para repetir a
> chamada com o mesmo `transaction_idempotency_id`, envie o mesmo payload. Se a
> primeira chamada enviou o bloco `customer` e a nova enviar `customer_id`, a
> API responde `409` / `UVV154862`.

### Respostas da criação

#### `201`: cobrança aprovada (sem trial)

```json Resposta 201 (cartão pago) theme={null}
{
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "660e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440000",
  "subscription_status": "ACTIVE",
  "invoice_status": "paid",
  "charge_status": "succeeded",
  "transaction_id": "880e8400-e29b-41d4-a716-446655440000",
  "failure_code": null,
  "failure_message": null,
  "pix": null
}
```

#### `201`: trial (sem cobrança na criação)

Com trial, não há cobrança na criação (`subscription_status: "TRIAL"`).

#### `422` / `UVV154147`: cartão recusado na primeira cobrança

A assinatura é criada mesmo assim (`PAST_DUE`, fatura `open`). A API responde `422`, não `201`:

```json Resposta 422 UVV154147 theme={null}
{
  "code": "UVV154147",
  "message": "Nao foi possivel processar o pagamento. Verifique os dados e tente novamente.",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440000",
  "failure_code": "issuer_declined",
  "failure_message": "Recusa do banco emissor"
}
```

Para tentar de novo, reenvie o mesmo `POST` com o mesmo `transaction_idempotency_id` e o mesmo payload. A API não cria outra assinatura. Se a fatura ainda estiver `open`, a cobrança roda de novo. Payload diferente responde `409` / `UVV154862`.

Detalhes em [Criar assinatura](https://developers.uvvipay.com.br/api-reference/recurrency/subscriptions/create.md).

## Webhooks de ciclo de vida

Com um endpoint de webhook cadastrado, você recebe:

| Evento | Quando |
| - | - |
| `subscription.created` | Assinatura criada |
| `subscription.trial_started` | Criação com status `TRIAL` |
| `subscription.activated` | Primeira cobrança paga (`ACTIVE`) |
| `subscription.past_due` | Cobrança falhou, com tentativas restantes |
| `subscription.cancelled` | Cancelamento pelo cliente ou por falha de pagamento |
| `subscription.reactivated` | Reativação após cancelamento por `USER_ACTION` |
| `subscription.completed` | Assinatura concluída ao esgotar os ciclos |
| `subscription.renewed` | Cobrança paga com a assinatura já `ACTIVE` e o período avançado |

Exemplo de payload:

```json theme={null}
{
  "event": "subscription.activated",
  "event_id": "<subscription_events.id>",
  "id": "<subscriptionId>",
  "status": "ACTIVE",
  "plan_id": "...",
  "amount": 9900,
  "currency": "BRL",
  "next_billing_date": "...",
  "period_start_date": "...",
  "period_end_date": "...",
  "occurred_at": "...",
  "customer_id": "<customerId>",
  "external_customer_id": "<externalCustomerId>",
  "invoice_id": "...",
  "charge_attempt_id": "...",
  "transaction_id": "...",
  "attempt": null,
  "decline_kind": null,
  "failure_category": null,
  "cancellation_reason": null,
  "payment_method_id": null,
  "trial_unit": null,
  "trial_duration": null,
  "metadata": {
    "invoiceId": "...",
    "chargeAttemptId": "...",
    "transactionId": "..."
  }
}
```

O mesmo webhook pode chegar mais de uma vez. Use `event_id` para ignorar duplicata. O campo `id` é o id da assinatura. Alguns campos no topo podem vir `null`, conforme o evento.

Gerencie endpoints em [Webhooks](https://developers.uvvipay.com.br/webhooks.md).

## Campos importantes

| Campo | Observação |
| - | - |
| `amount` | Sempre em centavos (ex.: `9900` = R$ 99,00). Mín. `1` (R$ 0,01); máx. `1000000` (R\$ 10.000,00) |
| `default_trial_duration` | Duração do trial padrão do plano; máx. `31` dias |
| `allowed_payment_types` | `credit_card` e/ou `pix` |
| `grace_period_days` | Dias de tolerância depois da falha, antes do cancelamento |
| `prevent_trial_abuse` | Impede novo trial para o mesmo cliente neste plano |
| `trial_unit` | Só `DAY` na criação da assinatura |
| Request bodies | snake\_case (`subscription_plan_id`, `payment_methods`, …) |
| Responses | snake\_case em todos os endpoints (`subscription_id`, `subscription_status`, `next_billing_date`, …) |
| Webhooks | payload em snake\_case (`plan_id`, `next_billing_date`, `occurred_at`, …) |

## Perguntas frequentes

> [accordion] Preciso armazenar os dados do cartão?
>
> Não. Na criação da assinatura o cartão é tokenizado. As cobranças seguintes
> usam o token. Você nunca guarda o número do cartão.

> [accordion] O que acontece se uma cobrança falhar?
>
> Na primeira cobrança (criação sem trial), a API responde `422` / `UVV154147`
> com `subscription_id` e `invoice_id` (fatura `open`). A assinatura fica
> `PAST_DUE`. Para tentar de novo, reenvie o mesmo `POST` com o mesmo
> `transaction_idempotency_id` e o mesmo payload. A API não cria outra
> assinatura. Payload diferente responde `409` / `UVV154862`. Nas renovações,
> a UvviPay pode tentar de novo enquanto a assinatura estiver em atraso.

> [accordion] Tem período de teste (trial)?
>
> Sim. Defina o trial no plano (`default_trial_unit` / `default_trial_duration`,
> máx. 31 dias) ou na assinatura (`trial_unit` / `trial_duration`). A primeira
> cobrança acontece no fim do trial.

> [accordion] Como cancelo uma assinatura?
>
> Use `POST /v1/subscriptions/{id}/cancel`. As faturas `open` passam a `void`
> e a assinatura fica `CANCELLED` por ação do cliente. Dá para reativar depois
> com `.../reactivate`.

> [accordion] Posso trocar o meio de pagamento de um cliente?
>
> Sim. Use `POST /v1/subscriptions/{id}/payment-method` (só do backend) para
> definir cartão ou PIX como padrão antes do próximo ciclo. Em
> `payment_methods` com `type: "pix"`, não envie dados de cartão.

> [accordion] Consigo mudar o valor ou a frequência do plano?
>
> O valor pode ser atualizado no plano. A frequência não muda depois da
> criação (`422`). Para outra frequência, crie um novo plano.

> [accordion] Preciso reenviar os dados do cliente em cada assinatura?
>
> Não. Se o cliente já estiver cadastrado, inclusive por
> [`POST /v1/customers`](https://developers.uvvipay.com.br/api-reference/recurrency/customers/create), prefira
> `customer_id` desde a primeira assinatura. O bloco `customer` também vale:
> a API reaproveita o cadastro pelo e-mail. As duas formas
> são exclusivas: envie uma ou outra. Os dois juntos respondem `400`.

> [accordion] O mesmo cliente pode ter mais de uma assinatura?
>
> Sim, em planos diferentes. Use o mesmo `customer_id` em cada criação. No
> mesmo plano, uma segunda assinatura ativa responde `409` / `UVV154158`.

> [accordion] Como atualizo os dados de um cliente já salvo?
>
> A criação da assinatura não atualiza o cliente. Enviar o bloco `customer`
> com o mesmo `external_customer_id` e dados diferentes responde `422` /
> `UVV154640`. Para corrigir o cadastro, fale com o suporte UvviPay.

## Boas práticas

* Trate a criação pelo status HTTP: `201` (cartão pago, trial ou PIX pendente) ou `422` / `UVV154147` (recusa com ids). Em `201`, confira `subscription_status`, `charge_status` e `pix`. Em PIX pendente, não libere o serviço até a confirmação do pagamento.
* Use webhooks para as mudanças seguintes (renovação, `past_due`, cancelamento). Em PIX pendente, confirme com `subscription.activated` e/ou `transaction.paid`, pelo `subscription_id` ou `transaction_id`.
* Guarde `subscription_id`, `customer_id` e `transaction_idempotency_id`. Com o `customer_id` salvo, as assinaturas seguintes do mesmo cliente não precisam do bloco `customer`.
* Cadastre o cliente com endereço completo na primeira assinatura se você pretende usar Pix Automático depois. Sem endereço, a API responde `422` / `UVV154361`.
* Se a primeira cobrança for recusada, reenvie o mesmo `POST` com o mesmo `transaction_idempotency_id` e o mesmo payload. Payload diferente responde `409` / `UVV154862`.
* Trate o webhook como idempotente. A mesma notificação pode chegar de novo.
* Reenviar o mesmo `transaction_idempotency_id` com o mesmo payload devolve a assinatura já criada. Se a fatura ainda estiver `open`, a cobrança pode rodar de novo.
* Troque o meio de pagamento com `.../payment-method` antes do próximo ciclo, quando o cliente atualizar cartão ou PIX.


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