Recurring payments

Card subscriptions: the first charge goes through right away and the following cycles are generated automatically.

POSTCreate charge/charges GETGet recurrence/charges/recurrences/{recurrentPaymentId}Webhooks Transaction status

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.
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 postback at your postbackUrl.

Recurring payments may not be available for all accounts. Check with support about availability on your account.

Create a recurrence

A recurrence starts from a regular credit card charge (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.

A recurrence is always a single payment. The installments field must be 1; higher values are rejected.

Example request (amounts in cents):

{
  "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:

{
  "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.

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

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

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

GETGet recurrence/charges/recurrences/{recurrentPaymentId}PUTUpdate Recurrence amount/charges/recurrences/{recurrentPaymentId}/amount PUTDeactivate recurrence/charges/recurrences/{recurrentPaymentId}/deactivate PUTReactivate recurrence/charges/recurrences/{recurrentPaymentId}/reactivate

Get a recurrence

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

{
  "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

Use 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

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

{ "amount": 12000 }

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.