PayZu PixTutoriais

Devolver um Pix recebido

  1. Todas as chamadas levam o seu token Bearer. transactionId é o id do Pix que você recebeu.

  2. Confirme que é um Pix recebido (DEPOSIT) e concluído.

  3. Com amount, em reais, a devolução é parcial; sem amount, é total. Repetir o clientReference retorna a devolução já criada.

  4. 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