Transferir entre contas PayZu
Todas as chamadas levam o seu token Bearer. receiverAccountNumber é a conta PayZu de destino, e clientReference identifica esta transferência no seu sistema.
GET /user retorna o accountNumber da conta do token, que vai em payerAccountNumber. GET /user/balance mostra o saldo disponível; o débito é o valor mais a tarifa.
O valor vai em reais. A conta pagadora precisa ser a do token, senão a resposta é PZC400.
Se a chamada ficar sem resposta, repita com o mesmo clientReference. Com o mesmo valor e as mesmas contas, a PayZu retorna a transferência já feita em vez de criar outra.
A transferência liquida na própria chamada: a resposta 200 já vem COMPLETED, com a tarifa em serviceFeeCharged. Trate as recusas pelo errorCode.
GET /internal-transfer busca a transferência pelo clientReference, pelo id ou pelo virtualAccount. Enquanto ela não existe, a resposta é 404 com PZC301.
const API = 'https://pix.sandbox.payzu.dev/v1'const headers = { authorization: `Bearer ${process.env.PAYZU_TOKEN}`, 'content-type': 'application/json'}const receiverAccountNumber = '987654'const amount = 100.5const clientReference = 'transfer_abc_123' const account = await fetch(`${API}/user`, { headers }).then((r) => r.json())const balance = await fetch(`${API}/user/balance`, { headers }).then((r) => r.json())if (balance.balanceAvailable < amount) throw new Error(`Saldo disponível: ${balance.balanceAvailable}`) const transfer = () => fetch(`${API}/internal-transfer`, { method: 'POST', headers, signal: AbortSignal.timeout(10_000), body: JSON.stringify({ payerAccountNumber: account.accountNumber, receiverAccountNumber, amount, description: 'Pagamento referente a fatura #1234', clientReference }) }) let responsetry { response = await transfer()} catch { response = await transfer()}const result = await response.json()if (!response.ok) throw new Error(`${result.errorCode}: ${result.message}`)console.log(result.status, result.id, result.serviceFeeCharged) const found = await fetch(`${API}/internal-transfer?clientReference=${clientReference}`, { headers }).then((r) => r.json())console.log(found.status, found.receiverName)
{ "id": "PAYZU20260506Q8ZR3VN6HT000000", "status": "COMPLETED", "amount": 100.5, "type": "WITHDRAW", "qrCodeText": null, "qrCodeBase64": null, "qrCodeUrl": null, "generatedName": null, "generatedDocument": null, "generatedEmail": null, "serviceFeeCharged": 0, "payerName": "Joao Silva", "payerDocument": "12345678901", "payerInstitutionIspb": "23066240", "payerInstitutionName": "PAYZU IP LTDA.", "payerAccountNumber": "000000", "withdrawPixKey": null, "withdrawPixType": null, "receiverName": "Maria Santos", "receiverDocument": "98765432109", "receiverInstitutionIspb": "23066240", "receiverInstitutionName": "PAYZU IP LTDA.", "receiverAccountNumber": "987654", "endToEndId": null, "clientReference": "transfer_abc_123", "createdAt": "2026-05-06T14:25:00.000Z", "updatedAt": "2026-05-06T14:25:00.123Z", "paidAt": "2026-05-06T14:25:00.123Z", "refundEndToEndId": null, "refundAmount": null, "refundStatus": null, "refundReason": null, "refundDescription": null, "refundedAt": null, "cancellationReason": null}
Referência: Transferir para outra conta PayZu