PayZu Conta HubCobrar com Pix

Devolver uma cobrança


Nesta páginaPeça a devoluçãoConfirme a devoluçãoErros desta operação

Devolva ao pagador o valor de uma cobrança paga, inteiro ou em parte, com a tarifa de devolução debitada da sua conta além do valor.

Peça a devolução

  • Tudo o que resta: chame a rota sem corpo ou com {}.
  • Uma parte: envie só amount, em centavos, até o refundableAmount da consulta da cobrança.
  • Idempotency-Key: mande uma nova por devolução.
  • Cota: a devolução conta na cota do saque, de 5 por minuto por credencial e 10 por conta.

Um corpo com outro campo, ou que não é JSON, é recusado com 400 e nada é devolvido.

bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/api/v1/transactions/payment/P20261005113205K7Q2M9XB4TC127431/refund' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Idempotency-Key: 5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f' \
  --header 'Content-Type: application/json' \
  --data '{ "amount": 1000 }'

Referência: Solicitar a devolução de uma cobrança

A resposta é a cobrança inteira; o exemplo mostra só o que muda. O que sai da sua conta é o totalDebited da tentativa em refunds, com a tarifa de devolução somada.

Se receber 502, repita com a mesma Idempotency-Key e o mesmo amount.

A resposta traz a devolução já pedida, no estado em que estiver, sem enviar outro Pix. Isso vale também para uma devolução recusada: para tentar de novo, use outra chave. Sem a chave, repetir depois que a primeira concluiu faz uma segunda devolução.

Confirme a devolução

DesfechoAvisoTentativa em refunds
O valor voltou ao pagador.REFUND_COMPLETEDSETTLED
O banco recusou e o valor voltou ao seu saldo.REFUND_FAILEDRELEASED, com o motivo em rejectedReason
Ainda em andamento.-PROCESSING

Os dois avisos trazem refundId e paymentId, e o corpo deles está em Devolução concluída e Devolução recusada. Para conferir, consulte a cobrança e olhe a tentativa mais recente.

Quando a devolução total conclui, a cobrança passa a REFUNDED e refundedAt é preenchido. O comprovante da cobrança continua disponível.

Erros desta operação

CódigoHTTPMensagem
REFUND_DISABLED403Estorno desabilitado para esta conta.
PAYMENT_NOT_FOUND404Pagamento não encontrado.
REFUND_ABOVE_REMAINING422O valor do estorno é maior do que o que resta a devolver deste pagamento.
REFUND_ABOVE_TICKET_MAX422O valor do estorno está acima do limite por operação desta conta.
REFUND_ALREADY_REFUNDED422Este pagamento já foi estornado integralmente.
REFUND_INFRACTION_OPEN422Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho.
REFUND_INSUFFICIENT_BALANCE422Saldo insuficiente para estornar este pagamento.
REFUND_IN_FLIGHT422Já existe um estorno em andamento para este pagamento. Aguarde o desfecho antes de pedir outro.
REFUND_NOT_PAID422Só é possível estornar um pagamento que foi pago.

Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.