Devolver um Pix recebido
Devolva ao pagador um Pix recebido, inteiro ou em parte.
Peça a devolução
O corpo é obrigatório: envie {} para devolver o total.
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"
}'{
"id": "PAYZU20260810JD4WQ2R7ZB000000",
"status": "COMPLETED",
"amount": 100,
"type": "DEPOSIT",
"method": "PIX",
"qrCodeText": null,
"qrCodeBase64": null,
"qrCodeUrl": null,
"generatedName": "Fulano de Tal",
"generatedDocument": "12345678901",
"generatedEmail": null,
"payerName": "Fulano de Tal",
"payerDocument": "12345678901",
"payerInstitutionIspb": "12345678",
"payerInstitutionName": "Banco X",
"payerAccountNumber": null,
"serviceFeeCharged": 1.5,
"withdrawPixKey": null,
"withdrawPixType": null,
"receiverName": "Loja Exemplo",
"receiverDocument": "11222333000181",
"receiverInstitutionIspb": "00000000",
"receiverInstitutionName": "PayZu",
"receiverAccountNumber": "000000",
"endToEndId": "E12345678202508101200abcdef01234",
"clientReference": "pedido-42",
"refundEndToEndId": null,
"refundAmount": 30.5,
"refundStatus": "PENDING",
"refundReason": "CUSTOMER_REQUEST",
"refundDescription": "Devolução pedida pelo cliente",
"refundedAt": null,
"cancellationReason": null,
"paidAt": "2025-08-10T12:00:00.000Z",
"createdAt": "2025-08-10T11:59:00.000Z",
"updatedAt": "2026-08-11T09:00:00.000Z"
}const transactionId = 'PAYZU20260810JD4WQ2R7ZB000000'
const response = await fetch(`https://pix.sandbox.payzu.dev/v1/refund/${transactionId}`, {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'content-type': 'application/json'
},
body: JSON.stringify({
amount: 30.5,
description: 'Devolução pedida pelo cliente',
clientReference: 'refund-2026-0001'
})
})
const refund = await response.json()
if (!response.ok) throw new Error(`${refund.errorCode}: ${refund.message}`)
console.log(refund.refundStatus, refund.refundAmount)Referência: Solicitar a devolução de um Pix recebido
| Campo | Regra |
|---|---|
amount | Valor em reais da devolução parcial. A soma das devoluções em andamento e concluídas não pode passar do valor do Pix. |
description | Aceito no corpo, ao lado de amount e clientReference. Qualquer outro campo é recusado com 400, sem details. |
clientReference | Com 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ção | Transação | Webhooks da conta |
|---|---|---|
| Total | Passa a REFUNDED. | Recebem TRANSACTION_REFUNDED. |
| Parcial | Segue 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
| Status | O que significa |
|---|---|
PENDING | Devolução pendente. |
COMPLETED | Devolução concluída. |
CANCELED | Devolução cancelada. |
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZC610 | 400 | O valor de reembolso deve ser maior que zero. |
PZC611 | 400 | O valor de reembolso excede o valor disponível da transação. |
PZC403 | 403 | Reembolso não habilitado para esta conta. |
PZC310 | 404 | Transação não encontrada. |
PZC221 | 409 | Esta transação já foi reembolsada. |
PZC200 | 422 | Saldo insuficiente para esta operação. |
PZC220 | 422 | Apenas depósitos ou saques podem ser reembolsados. |
PZC223 | 422 | Transação de liquidação de cartão não pode ser reembolsada nem alterada. |
PZS202 | 422 | Limite diário de saque excedido. |
PZS206 | 422 | Limite diário não configurado para esta conta. |
PZC500 | 424 | Devolução indisponível na instituição financeira desta transação. |
PZG429 | 429 | Limite 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.