PayZu PixTutoriais

Transferir entre contas PayZu

  1. Todas as chamadas levam o seu token Bearer. receiverAccountNumber é a conta PayZu de destino, e clientReference identifica esta transferência no seu sistema.

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

  3. O valor vai em reais. A conta pagadora precisa ser a do token, senão a resposta é PZC400.

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

  5. A transferência liquida na própria chamada: a resposta 200 já vem COMPLETED, com a tarifa em serviceFeeCharged. Trate as recusas pelo errorCode.

  6. GET /internal-transfer busca a transferência pelo clientReference, pelo id ou pelo virtualAccount. Enquanto ela não existe, a resposta é 404 com PZC301.

transfer-between-accounts.js
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)
Resposta · 200 Transferência concluída
{  "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