PayZu PixTutoriais
Devolver um Pix recebido
Todas as chamadas levam o seu token Bearer. transactionId é o id do Pix que você recebeu.
Confirme que é um Pix recebido (DEPOSIT) e concluído.
Com amount, em reais, a devolução é parcial; sem amount, é total. Repetir o clientReference retorna a devolução já criada.
A devolução começa em refundStatus PENDING. Consulte até virar COMPLETED ou CANCELED, ou espere o webhook.
refund-pix.js
const API = 'https://pix.sandbox.payzu.dev/v1'const headers = { authorization: `Bearer ${process.env.PAYZU_TOKEN}`, 'content-type': 'application/json'}const transactionId = 'PAYZU20260814T6NX1CV9MK000000'const getPix = () => fetch(`${API}/user/transactions/${transactionId}`, { headers }).then((r) => r.json()) const pix = await getPix()if (pix.type !== 'DEPOSIT' || pix.status !== 'COMPLETED') throw new Error(`Pix ${pix.status}`)console.log(pix.payerName, pix.amount, pix.endToEndId) const response = await fetch(`${API}/refund/${transactionId}`, { method: 'POST', headers, 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) let status = refund.refundStatusfor (let i = 0; i < 12 && status === 'PENDING'; i++) { await new Promise((resolve) => setTimeout(resolve, 5000)) status = (await getPix()).refundStatus}console.log(status)
Resposta · 200 Devolução enfileirada
{ "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 parcial", "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"}
Referência: Solicitar a devolução de um Pix recebido