PayZu PixDevoluções e MED

Devolver um Pix recebido


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

Devolva ao pagador um Pix recebido, inteiro ou em parte.

Peça a devolução

O corpo é obrigatório: envie {} para devolver o total.

bash
curl -X POST https://pix.sandbox.payzu.dev/v1/refund/PAYZU20260810JD4WQ2R7ZB000000 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 30.5,
    "description": "Devolução pedida pelo cliente",
    "clientReference": "refund-2026-0001"
  }'

Referência: Solicitar a devolução de um Pix recebido

CampoRegra
amountValor em reais da devolução parcial. A soma das devoluções em andamento e concluídas não pode passar do valor do Pix.
descriptionAceito no corpo, ao lado de amount e clientReference. Qualquer outro campo é recusado com 400, sem details.
clientReferenceCom a mesma referência e o mesmo valor, a PayZu retorna o pedido já criado enquanto a devolução está PENDING ou COMPLETED. Com outro valor, ou com o pedido em outro status, como cancelado, a resposta é 409.

O valor devolvido sai do seu saldo disponível no momento do pedido e conta no limite diário de saque da conta. Sem saldo ou limite, o pedido é recusado na hora.

A resposta 200 confirma só o pedido.

Ela vem com refundStatus: "PENDING". Se o banco recusar, ou se faltar saldo ou limite no reprocessamento, refundStatus vira CANCELED e o valor que tiver sido debitado volta ao seu saldo.

A rota aceita até 10 pedidos por minuto.

Acima disso, a resposta é 429, com o tempo de espera em retryAfterSeconds.

Confirme a devolução

O canal recomendado é o callback na callbackUrl da cobrança, que recebe a transação atualizada quando a devolução termina.

DevoluçãoTransaçãoWebhooks da conta
TotalPassa a REFUNDED.Recebem TRANSACTION_REFUNDED.
ParcialSegue COMPLETED até a soma devolvida alcançar o valor do Pix; refundStatus, refundAmount, refundEndToEndId e refundedAt mostram a devolução.Recebem TRANSACTION_REFUNDED, com status: COMPLETED enquanto a soma devolvida não alcança o valor do Pix e REFUNDED quando alcança.

Sem callbackUrl nem webhook, acompanhe a devolução por GET /pix, lendo refundStatus. O corpo do aviso está em Devolução concluída.

Status da devolução

StatusO que significa
PENDINGDevolução pendente.
COMPLETEDDevolução concluída.
CANCELEDDevolução cancelada.

Erros desta operação

CódigoHTTPMensagem
PZC610400O valor de reembolso deve ser maior que zero.
PZC611400O valor de reembolso excede o valor disponível da transação.
PZC403403Reembolso não habilitado para esta conta.
PZC310404Transação não encontrada.
PZC221409Esta transação já foi reembolsada.
PZC200422Saldo insuficiente para esta operação.
PZC220422Apenas depósitos ou saques podem ser reembolsados.
PZC223422Transação de liquidação de cartão não pode ser reembolsada nem alterada.
PZS202422Limite diário de saque excedido.
PZS206422Limite diário não configurado para esta conta.
PZC500424Devolução indisponível na instituição financeira desta transação.
PZG429429Limite de reembolsos atingido. Tente novamente em 1 minuto.

Os códigos de autenticação e de validação estão no Catálogo de erros.