Criar uma recorrência
Abra no cartão do cliente um contrato que repete a cobrança todo mês ou todo ano, com a primeira cobrança na hora, quando a assinatura vive no seu sistema.
Crie a recorrência
É a cobrança do PayZu Payments com o nó recurrence.
| Campo | Regra |
|---|---|
interval | Monthly ou Annual. Daily serve só para testes no sandbox. |
dailyIntervalDays | Com Daily, de 1 a 99 dias entre os ciclos. O padrão é 1. |
endDate | Fim do contrato, em AAAA-MM-DD. Sem ele, o contrato não tem data para acabar. |
creditCardPayment.installments | Sempre 1. |
amount e cart[].unitPrice | Em centavos. |
curl -X POST https://api.sandbox.payzu.dev/v1/charges \
--cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"paymentType": "creditcard",
"externalId": "recorrencia-123",
"postbackUrl": "https://seusite.com.br/webhooks/payzu",
"customer": {
"name": "Maria Souza",
"identity": "11144477735",
"identityType": "CPF",
"email": "maria.souza@example.com",
"phone": "5511999998888"
},
"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"
}
}'{
"id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90",
"externalId": "recorrencia-123",
"postbackUrl": "https://seusite.com.br/webhooks/payzu",
"amount": 10000,
"paymentType": "creditcard",
"createdAt": "2026-06-12T14:35:22.000Z",
"updatedAt": "2026-06-12T14:35:24.000Z",
"customer": {
"name": "Maria Souza",
"identity": "11144477735",
"identityType": "CPF",
"email": "maria.souza@example.com",
"birthdate": "1990-04-15",
"phone": "5511999998888",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zipCode": "01310100",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"district": "Bela Vista",
"complement": "Conjunto 101"
}
},
"cart": [
{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }
],
"creditCardPayment": {
"installments": 1,
"authenticate": false,
"currency": "BRL",
"acquirerTransactionId": "1049329871283a5d2b8e",
"authorizationCode": "128734",
"reasonCode": 0,
"reasonMessage": "Successful",
"status": 2,
"returnCode": "6",
"returnMessage": "Operação realizada com sucesso",
"externalAuthentication": {},
"reversedAmount": null,
"reversedDate": null,
"card": {
"number": "411111******1111",
"holder": "MARIA SOUZA",
"expiration": "12/2030",
"brand": "Visa"
},
"chargebacks": []
},
"pixPayment": null,
"recurrence": {
"recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"interval": "MONTHLY",
"status": "ACTIVE",
"amount": 10000,
"nextRecurrency": "2026-07-12T00:00:00.000Z",
"endDate": "2027-06-12T00:00:00.000Z"
},
"recurrenceCycle": 0
}Referência: Criar uma recorrência no cartão
Na resposta 201, creditCardPayment.status igual a 2 é cobrança aprovada. Guarde recurrence.recurrentPaymentId, o identificador do contrato, junto da assinatura no seu sistema.
As chamadas levam o token do PayZu Payments e, quando a credencial exige, o certificado mTLS, como em Token. Com a exigência do certificado desligada, tire o --cert e o --key dos exemplos.
O externalId é seu, mas não impede duplicidade.
Cada chamada cria uma cobrança. Num timeout, procure o seu externalId em GET /charges antes de repetir a criação.
Receba os ciclos
| Evento | Quando chega |
|---|---|
recurrence.cycle | A cada ciclo novo, aprovado ou negado. |
charge.update | Quando o pagamento de um ciclo muda, como num estorno ou no ciclo negado que é aprovado numa nova tentativa. |
chargeback | Num chargeback. |
Os avisos chegam na postbackUrl da cobrança, no formato descrito em Webhooks. Um ciclo recusado chega com creditCardPayment.status diferente de 2. Para conciliar, compare o recurrenceCycle das cobranças com o que você já registrou, como em Consultar uma recorrência.
Cada ciclo repete o externalId da cobrança que abriu a recorrência.
Repete também o comprador, o carrinho e a postbackUrl. Identifique o ciclo por data.id e recurrenceCycle, nunca pelo externalId.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ010 | 403 | Produto não habilitado |
PZ101 | 422 | Valor mínimo por cobrança não atingido |
PZ102 | 422 | Valor máximo por cobrança excedido |
PZ103 | 422 | Conta sem limites de cobrança configurados |
PZ104 | 422 | Conta sem provedor de pagamento configurado |
PZ105 | 422 | Provedor de pagamento desabilitado |
PZ107 | 422 | Não foi possível criar a cobrança |
PZ108 | 422 | Configuração de pagamento da conta incompleta |
PZ200 | 422 | Cartão indisponível para cobrança internacional |
PZ201 | 422 | Apenas cartões estrangeiros são aceitos quando currency é diferente de BRL |
PZ202 | 422 | O emissor recusou este cartão em definitivo. Não é possível retentar. |
PZ203 | 422 | O emissor pediu para não retentar com este cartão até 09/11/2026 às 15:40. |
PZ501 | 422 | Recorrência não disponível para esta conta |
PZ700 | 422 | Conta sem configuração de taxas definidas para este meio de pagamento |
PZ900 | 422 | O provedor de pagamento recusou a operação |
| - | 422 | Cannot get currency rate |
PZ109 | 502 | Não foi possível confirmar a criação da cobrança com o provedor de pagamento. Verifique com o suporte antes de repetir o pedido. |
PZ901 | 503 | Não foi possível estabelecer comunicação com o provedor de pagamento. Tente novamente em instantes. |
Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.