PayZu GatewayRecorrência

Cancelar uma assinatura


Nesta páginaCancele a assinaturaFaturas em abertoConfirme o cancelamentoErros desta operação

Encerre as cobranças de uma assinatura quando o cliente desistir.

Cancele a assinatura

bash
curl -X POST https://api.sandbox.payzu.dev/v1/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc/cancel \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Cliente pediu o cancelamento" }'

Referência: Cancelar uma assinatura

CampoRegra
noteOpcional, de 1 a 255 caracteres. Volta em cancellation.note. O corpo também é opcional, e outro campo responde 400.
Idempotency-KeyOpcional. Com ela, repetir o cancelamento retorna a resposta guardada; sem ela, o segundo cancelamento é recusado porque a assinatura já está cancelada.
  • Status: o cancelamento vale para a assinatura active ou incomplete.
  • Cartão: a PayZu também encerra a recorrência na adquirente.

A assinatura cancelada pode voltar em até 30 dias.

Se o cliente mudar de ideia, use Reativar uma assinatura.

Faturas em aberto

O cancelamento decide o destino de cada fatura pending da assinatura.

Fatura pendingO que acontece
Sem tentativa paid nem refund_requestedPassa a canceled, com billing.canceled_at e cancellation.reason igual a subscription_cancellation, e sai invoice.canceled. A note fica só na assinatura.
Com uma tentativa paid ou refund_requestedNão é cancelada: segue pending, sem evento, e passa a paid quando o pagamento é concluído.

A rota de Cancelar uma fatura recusa a fatura de assinatura: para fechá-la, cancele a assinatura. As faturas fechadas aparecem em Consultar faturas, com o filtro subscription_id.

O cancelamento não desfaz o Pix já emitido.

O QR Code de uma tentativa pending vale até pix.expires_at. Se o cliente pagar nesse prazo, a fatura volta a paid e sai invoice.paid, mas a assinatura continua cancelada.

Confirme o cancelamento

A resposta 200 traz a assinatura inteira. Primeiro sai um invoice.canceled para cada fatura fechada e depois subscription.canceled, com o corpo de Assinatura cancelada.

Para conferir sem o webhook, consulte a assinatura. Os outros motivos de cancelamento, como a falta de pagamento, estão em Ciclo da assinatura.

Erros desta operação

CódigoHTTPMensagem
-404Assinatura não encontrada para o id informado.
PZ034404Recorrência não ativada para esta conta.
PZ507409Só uma assinatura ativa ou aguardando o pagamento inicial pode ser cancelada.

Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.