# Pagamentos Recorrentes (/docs/cartao/recurrence)



<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/charges/post_charges" title="Criar Cobrança" method="POST" path="/charges" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="Consultar Recorrência" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/webhooks" title="Webhooks" />

  <QuickLink href="/docs/cartao/transaction-status" title="Status de transação" />
</QuickLinks>

Uma recorrência é uma assinatura: você cria a primeira cobrança informando o intervalo e, a partir daí, cada ciclo é cobrado automaticamente no cartão do cliente, sem nova chamada à API.

* **Primeira cobrança**: criada na hora, na resposta do [`POST /charges`](/docs/cartao/endpoints/charges/post_charges).
* **Ciclos seguintes**: gerados automaticamente no intervalo configurado (mensal ou anual).
* Cada ciclo vira uma cobrança vinculada à recorrência, numerada por `recurrenceCycle` (`0` = inicial, `1..n` = ciclos).
* A cada ciclo você recebe um postback [`recurrence.cycle`](/docs/cartao/webhooks) na sua `postbackUrl`.

<Callout type="info">
  Pagamentos recorrentes podem não estar disponíveis para todas as contas. Consulte o suporte sobre a disponibilidade na sua conta.
</Callout>

## Criar uma recorrência [#criar-uma-recorrência]

Uma recorrência nasce de uma cobrança de cartão de crédito comum ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)) com o nó `recurrence` adicionado.

Campos de `recurrence` no request:

| Campo      | Tipo                | Descrição                                                                         |
| ---------- | ------------------- | --------------------------------------------------------------------------------- |
| `interval` | string, obrigatório | `Monthly` (mensal) ou `Annual` (anual)                                            |
| `endDate`  | string, opcional    | Data final no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente. |

<Callout type="warn">
  Recorrência é sempre à vista. O campo `installments` precisa ser `1`; valores maiores são rejeitados.
</Callout>

Request de exemplo (valores em centavos):

```json
{
  "amount": 10000,
  "paymentType": "creditcard",
  "externalId": "assinatura-123",
  "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF" },
  "cart": [{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }],
  "creditCardPayment": {
    "installments": 1,
    "authenticate": false,
    "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" }
  },
  "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" }
}
```

Resposta:

```json
{
  "id": "uuid-da-cobranca",
  "amount": 10000,
  "creditCardPayment": { "status": 2, "reference": "PaymentId" },
  "recurrence": {
    "recurrentPaymentId": "uuid-da-recorrencia",
    "interval": "MONTHLY",
    "status": "ACTIVE",
    "amount": 10000,
    "endDate": "2027-06-12T00:00:00.000Z",
    "nextRecurrency": "2026-07-12T00:00:00.000Z"
  },
  "recurrenceCycle": 0
}
```

Campos de `recurrence` na resposta:

| Campo                | Descrição                                                             |
| -------------------- | --------------------------------------------------------------------- |
| `recurrentPaymentId` | Identificador da recorrência. Use nos endpoints de consulta e gestão. |
| `status`             | `ACTIVE`, `INACTIVE` ou `ENDED`.                                      |
| `amount`             | Valor de cada ciclo, em centavos.                                     |
| `nextRecurrency`     | Data da próxima cobrança automática.                                  |
| `endDate`            | Data final, se informada na criação.                                  |

## Como funcionam os ciclos [#como-funcionam-os-ciclos]

Você não precisa fazer nada para os ciclos acontecerem. A cada intervalo, a PayZu cobra o cartão e cria uma nova cobrança vinculada à recorrência, com o `recurrenceCycle` incrementado. A cada ciclo cobrado, um postback com o evento `recurrence.cycle` é enviado para a sua `postbackUrl`. Use-o para conciliar as cobranças.

## Ciclo de vida [#ciclo-de-vida]

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> ACTIVE: POST /charges com recurrence
  ACTIVE --> ACTIVE: Novo ciclo cobrado (recurrence.cycle)
  ACTIVE --> INACTIVE: PUT .../deactivate
  INACTIVE --> ACTIVE: PUT .../reactivate
  ACTIVE --> ENDED: endDate atingida
  ENDED --> [*]
`"
/>

| Status     | Significado                                                      |
| ---------- | ---------------------------------------------------------------- |
| `ACTIVE`   | Ativa, gerando os ciclos no intervalo configurado.               |
| `INACTIVE` | Desativada (manualmente ou pelo emissor). Não gera novos ciclos. |
| `ENDED`    | Encerrada por ter atingido a `endDate`.                          |

## Gerenciar a recorrência [#gerenciar-a-recorrência]

Use o `recurrentPaymentId` retornado na criação para consultar e gerenciar a assinatura:

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="Consultar Recorrência" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount" title="Alterar valor da Recorrência" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/amount" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate" title="Desativar Recorrência" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/deactivate" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate" title="Reativar Recorrência" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/reactivate" />
</QuickLinks>

### Consultar uma recorrência [#consultar-uma-recorrência]

`GET /charges/recurrences/{recurrentPaymentId}` retorna o estado atual da recorrência:

```json
{
  "recurrentPaymentId": "uuid-da-recorrencia",
  "interval": "MONTHLY",
  "status": "ACTIVE",
  "amount": 10000,
  "nextRecurrency": "2026-07-12T00:00:00.000Z",
  "endDate": "2027-06-12T00:00:00.000Z"
}
```

### Listar as cobranças da recorrência [#listar-as-cobranças-da-recorrência]

Use [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) com o filtro `recurrentPaymentId`:

```
GET /charges?recurrentPaymentId={recurrentPaymentId}
```

Lista a cobrança inicial e todos os ciclos já gerados (paginado). Aceita também os filtros `limit`, `page`, `startDate` e `endDate`.

### Alterar o valor [#alterar-o-valor]

`PUT /charges/recurrences/{recurrentPaymentId}/amount` altera o valor das próximas cobranças. Não afeta ciclos já gerados.

```json
{ "amount": 12000 }
```

### Desativar e reativar [#desativar-e-reativar]

* `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` interrompe a recorrência: nenhum ciclo novo é gerado e o status vira `INACTIVE`.
* `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` retoma uma recorrência desativada: o status volta para `ACTIVE`.