PayZu Conta HubCobrar com Pix

Devolver um depósito


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

Devolva ao pagador um Pix recebido numa chave da conta, inteiro ou em parte, com a tarifa de devolução debitada 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 do depósito.
  • Idempotency-Key: mande uma nova por devolução.

Um corpo com outro campo, ou que não é JSON, é recusado sem devolver nada. A TED recebida, com method igual a TED, não aceita devolução, nem depois de liberada: liberar o depósito e pedir de novo vale só para o Pix.

bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Idempotency-Key: 9b2e4c6a-1d3f-4a5b-8c7d-0e9f1a2b3c4d'

Referência: Solicitar a devolução de um depósito

A resposta é o depósito inteiro; o exemplo mostra só o que muda. O débito na sua conta é o totalDebited da tentativa em refunds, com a tarifa de devolução somada.

O depósito aceita uma devolução de cada vez.

Nenhuma é aceita enquanto ele estiver retido ou houver infração MED aberta. Se receber 502, repita com a mesma Idempotency-Key e o mesmo amount, que retornam a devolução já pedida sem enviar outro Pix, ou confira refunds na consulta do depósito antes de pedir de novo.

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

Os dois avisos trazem depositId e refundId e vão só aos webhooks cadastrados. O corpo deles está em Devolução concluída e Devolução recusada. Para conciliar, consulte o depósito.

Erros desta operação

CódigoHTTPMensagem
REFUND_DISABLED403Estorno desabilitado para esta conta.
DEPOSIT_NOT_FOUND404Depósito não encontrado.
DEPOSIT_BLOCKED422O depósito está retido. Libere-o antes de solicitar a devolução.
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_TED_NOT_SUPPORTED422TED recebida não aceita devolução: a devolução é uma operação do Pix e depende do identificador end-to-end, que a TED não tem.

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