PayZu GatewayRecorrência

Alterar uma assinatura


Nesta páginaAltere a assinaturaConfirme a alteraçãoErros desta operação

Reajuste o valor de quem já assina ou atualize o metadata de uma assinatura, sem mudar o plano nem as outras assinaturas dele.

Altere a assinatura

bash
curl -X PATCH https://api.sandbox.payzu.dev/v1/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 16990,
    "metadata": {
      "internal_id": "5678"
    }
  }'

Referência: Alterar uma assinatura

Envie só o que muda. Campo fora dos três abaixo responde 400.

CampoStatus da assinaturaRegra
amountactiveNovo valor de cada ciclo, em centavos, de no mínimo 500 (R$ 5,00).
credit_card.card_idactiveUm cartão salvo do mesmo cliente. A troca de cartão ainda não está disponível na assinatura no cartão, e a assinatura no Pix não tem cartão: nos dois casos, a chamada é recusada.
metadataactive ou canceledSubstitui o mapa inteiro, com os limites de Metadados.
  • Cobranças já geradas: o valor novo vale para as cobranças ainda não geradas e entra na próxima fatura, com o desconto que ainda estiver em vigor.
  • Desconto em vigor: se ele deixa o próximo ciclo abaixo de 500, a PayZu recusa o valor novo.
  • Cartão: a PayZu atualiza o valor na adquirente antes de gravar. Se a adquirente não aceitar, nada muda.
  • Assinatura incomplete: o metadata não muda enquanto a adesão espera o pagamento, porque é ele que identifica a adesão que uma nova criação aproveita.

Alterar o plano não muda quem já assina.

A assinatura guarda o nome, o valor e a periodicidade da adesão. Para reajustar várias assinaturas, altere cada uma por esta rota.

Confirme a alteração

A resposta 200 traz a assinatura inteira, já alterada, e sai subscription.updated, com o corpo de Assinatura alterada.

Um corpo sem nenhum dos três campos recebe a assinatura como está e não envia evento. Para conferir depois, consulte a assinatura.

Erros desta operação

CódigoHTTPMensagem
PZ503400O valor da assinatura, com o desconto em vigor, precisa ser de no mínimo R$ 5,00.
-404Assinatura não encontrada para o id informado.
PZ034404Recorrência não ativada para esta conta.
PZ501409Só uma assinatura ativa pode ter o valor ou o cartão alterado.
PZ502409O metadata não pode ser alterado enquanto a assinatura aguarda o pagamento inicial.
PZ504422A assinatura é paga por Pix e não tem cartão.
PZ505422A troca de cartão de assinatura no cartão ainda não está disponível.
PZ506503Não foi possível atualizar o valor da assinatura agora. Tente de novo.

O amount abaixo de 500 responde 400, com amount em fields. Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.