PayZu PaymentsRecorrência no cartão

Criar uma recorrência


Nesta páginaCrie a recorrênciaReceba os ciclosErros desta operação

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.

CampoRegra
intervalMonthly ou Annual. Daily serve só para testes no sandbox.
dailyIntervalDaysCom Daily, de 1 a 99 dias entre os ciclos. O padrão é 1.
endDateFim do contrato, em AAAA-MM-DD. Sem ele, o contrato não tem data para acabar.
creditCardPayment.installmentsSempre 1.
amount e cart[].unitPriceEm centavos.
bash
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"
    }
  }'

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

EventoQuando chega
recurrence.cycleA cada ciclo novo, aprovado ou negado.
charge.updateQuando o pagamento de um ciclo muda, como num estorno ou no ciclo negado que é aprovado numa nova tentativa.
chargebackNum 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ódigoHTTPMensagem
PZ010403Produto não habilitado
PZ101422Valor mínimo por cobrança não atingido
PZ102422Valor máximo por cobrança excedido
PZ103422Conta sem limites de cobrança configurados
PZ104422Conta sem provedor de pagamento configurado
PZ105422Provedor de pagamento desabilitado
PZ107422Não foi possível criar a cobrança
PZ108422Configuração de pagamento da conta incompleta
PZ200422Cartão indisponível para cobrança internacional
PZ201422Apenas cartões estrangeiros são aceitos quando currency é diferente de BRL
PZ202422O emissor recusou este cartão em definitivo. Não é possível retentar.
PZ203422O emissor pediu para não retentar com este cartão até 09/11/2026 às 15:40.
PZ501422Recorrência não disponível para esta conta
PZ700422Conta sem configuração de taxas definidas para este meio de pagamento
PZ900422O provedor de pagamento recusou a operação
-422Cannot get currency rate
PZ109502Nã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.
PZ901503Nã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.