Pagamentos Recorrentes

Monte uma assinatura: a primeira cobrança sai na hora e, a partir daí, a PayZu cobra o cartão do cliente sozinha a cada ciclo, mensal ou anual.

POSTCriar Cobrança/charges GETConsultar Recorrência/charges/recurrences/{recurrentPaymentId}Webhooks Status de transação

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.
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 na sua postbackUrl.

Pagamentos recorrentes podem não estar disponíveis para todas as contas. Consulte o suporte sobre a disponibilidade na sua conta.

Criar uma recorrência

Uma recorrência nasce de uma cobrança de cartão de crédito comum (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.

Recorrência é sempre à vista. O campo installments precisa ser 1; valores maiores são rejeitados.

Request de exemplo (valores em centavos):

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

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

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

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

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

GETConsultar Recorrência/charges/recurrences/{recurrentPaymentId}PUTAlterar valor da Recorrência/charges/recurrences/{recurrentPaymentId}/amount PUTDesativar Recorrência/charges/recurrences/{recurrentPaymentId}/deactivate PUTReativar Recorrência/charges/recurrences/{recurrentPaymentId}/reactivate

Consultar uma recorrência

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

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

Use 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

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

{ "amount": 12000 }

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.