Cancelar uma assinatura
Encerre as cobranças de uma assinatura quando o cliente desistir.
Cancele a assinatura
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" }'{
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"status": "canceled",
"updated_at": "2026-11-20T14:02:11.438Z",
"billing": {
"anchor_at": "2026-11-11T03:00:00.000Z",
"next_at": null,
"canceled_at": "2026-11-20T14:02:11.438Z",
"renewal_failures": 0
},
"grace": null,
"cancellation": {
"reason": "merchant_request",
"note": "Cliente pediu o cancelamento"
}
}Referência: Cancelar uma assinatura
| Campo | Regra |
|---|---|
note | Opcional, de 1 a 255 caracteres. Volta em cancellation.note. O corpo também é opcional, e outro campo responde 400. |
Idempotency-Key | Opcional. 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
activeouincomplete. - 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 pending | O que acontece |
|---|---|
Sem tentativa paid nem refund_requested | Passa 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_requested | Nã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ódigo | HTTP | Mensagem |
|---|---|---|
| - | 404 | Assinatura não encontrada para o id informado. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ507 | 409 | Só 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.