# Recurring payments (/en/docs/cartao/recurrence)

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/charges/post_charges" title="Create charge" method="POST" path="/charges" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="Get recurrence" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

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

  <QuickLink href="/docs/cartao/transaction-status" title="Transaction status" />
</QuickLinks>

A recurrence is a subscription: you create the first charge specifying the interval and, from then on, each cycle is charged automatically to the customer's card, with no new API call.

* **First charge**: created immediately, in the response of [`POST /charges`](/docs/cartao/endpoints/charges/post_charges).
* **Following cycles**: generated automatically at the configured interval (monthly or annual).
* Each cycle becomes a charge linked to the recurrence, numbered by `recurrenceCycle` (`0` = initial, `1..n` = cycles).
* On every cycle you receive a [`recurrence.cycle`](/docs/cartao/webhooks) postback at your `postbackUrl`.

<Callout type="info">
  Recurring payments may not be available for all accounts. Check with support about availability on your account.
</Callout>

## Create a recurrence [#create-a-recurrence]

A recurrence starts from a regular credit card charge ([`POST /charges`](/docs/cartao/endpoints/charges/post_charges)) with the `recurrence` node added.

`recurrence` fields in the request:

| Field      | Type             | Description                                                                    |
| ---------- | ---------------- | ------------------------------------------------------------------------------ |
| `interval` | string, required | `Monthly` or `Annual`                                                          |
| `endDate`  | string, optional | End date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely. |

<Callout type="warn">
  A recurrence is always a single payment. The `installments` field must be `1`; higher values are rejected.
</Callout>

Example request (amounts in cents):

```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" }
}
```

Response:

```json
{
  "id": "uuid-da-cobranca",
  "amount": 10000,
  "creditCardPayment": { "status": 2, "acquirerTransactionId": "0725103012345" },
  "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
}
```

`recurrence` fields in the response:

| Field                | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `recurrentPaymentId` | Identifier of the recurrence. Use it in the query and management endpoints. |
| `status`             | `ACTIVE`, `INACTIVE` or `ENDED`.                                            |
| `amount`             | Amount of each cycle, in cents.                                             |
| `nextRecurrency`     | Date of the next automatic charge.                                          |
| `endDate`            | End date, if provided at creation.                                          |

## How cycles work [#how-cycles-work]

You don't need to do anything for the cycles to happen. At each interval, PayZu charges the card and creates a new charge linked to the recurrence, with `recurrenceCycle` incremented. For every charged cycle, a postback with the `recurrence.cycle` event is sent to your `postbackUrl`. Use it to reconcile the charges.

## Lifecycle [#lifecycle]

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> ACTIVE: POST /charges with recurrence
  ACTIVE --> ACTIVE: New cycle charged (recurrence.cycle)
  ACTIVE --> INACTIVE: PUT .../deactivate
  INACTIVE --> ACTIVE: PUT .../reactivate
  ACTIVE --> ENDED: endDate reached
  ENDED --> [*]
`"
/>

| Status     | Meaning                                                               |
| ---------- | --------------------------------------------------------------------- |
| `ACTIVE`   | Active, generating cycles at the configured interval.                 |
| `INACTIVE` | Deactivated (manually or by the issuer). No new cycles are generated. |
| `ENDED`    | Ended after reaching the `endDate`.                                   |

## Manage the recurrence [#manage-the-recurrence]

Use the `recurrentPaymentId` returned at creation to query and manage the subscription:

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="Get recurrence" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount" title="Update Recurrence amount" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/amount" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate" title="Deactivate recurrence" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/deactivate" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate" title="Reactivate recurrence" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/reactivate" />
</QuickLinks>

### Get a recurrence [#get-a-recurrence]

`GET /charges/recurrences/{recurrentPaymentId}` returns the current state of the recurrence:

```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"
}
```

### List the recurrence charges [#list-the-recurrence-charges]

Use [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) with the `recurrentPaymentId` filter:

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

Lists the initial charge and every cycle generated so far (paginated). It also accepts the `limit`, `page`, `startDate` and `endDate` filters.

### Update the amount [#update-the-amount]

`PUT /charges/recurrences/{recurrentPaymentId}/amount` changes the amount of upcoming charges. It does not affect cycles already generated.

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

### Deactivate and reactivate [#deactivate-and-reactivate]

* `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` stops the recurrence: no new cycle is generated and the status becomes `INACTIVE`.
* `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` resumes a deactivated recurrence: the status goes back to `ACTIVE`.