Transfers between accounts

The money does not go through Pix: the destination is always another PayZu account, identified by its Pix key. For any other destination, use a withdrawal.

IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer \
  -H "Authorization: Bearer $PAYZU_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "toPixKey": "financeiro@lojaparceira.com.br",
    "comment": "Repasse do mês"
  }'

import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000,
    toPixKey: 'financeiro@lojaparceira.com.br',
    comment: 'Repasse do mês',
  }),
});
const transferencia = await res.json();

{
  "id": "hubp-20261005L9C3VH6KMA127431",
  "status": "CONFIRMED",
  "side": "SENT",
  "amount": 10000,
  "serviceFee": 100,
  "totalDebited": 10100,
  "counterparty": {
    "name": "Loja Parceira Ltda",
    "document": "12.345.678/0001-95",
    "pixKey": "financeiro@lojaparceira.com.br"
  },
  "comment": "Repasse do mês",
  "providerRejectedReason": null,
  "callbackUrl": null,
  "createdAt": "2026-10-05T15:02:44.010Z",
  "confirmedAt": "2026-10-05T15:02:44.418Z",
  "failedAt": null
}

Repeated request

The Idempotency-Key follows the withdrawal rules, and the comparison uses amount and destination. The same key with another amount or destination is refused with 409 TRANSFER_IDEMPOTENCY_KEY_REUSED.

On a 502 where the bank did not respond (PROVIDER_UNAVAILABLE) or refused temporarily (PROVIDER_REFUSED with details.status 408 or 429), the transfer may have gone out. It stays REQUESTED, with no result, and the amount stays out of the available balance:

• The API does not resolve it on its own: no webhook or lookup gives the result earlier. PayZu checks with the bank, and the transfer moves to CONFIRMED or FAILED.
• Repeating with the same Idempotency-Key returns the original, still REQUESTED, without sending another one. A new key creates another transfer.
• Until the result is checked, it counts toward that day's daily cap.

A final refusal from the bank leaves the transfer FAILED and returns the amount.

Both sides

The same transfer appears in both accounts, and side says which side:

Only a confirmed transfer generates a webhook.

Look up

• GET /transactions/internal-transfer/{transferId} and GET /transactions/internal-transfer, scope INTERNAL_TRANSFER_READ. The list includes both sides; ?side=SENT or ?side=RECEIVED filters one. It also filters by status, dateFrom and dateTo.
• A transfer from another account, or one that does not exist, responds 404 TRANSFER_NOT_FOUND.

Limits

• Insufficient balance refuses the whole transfer, and the check uses totalDebited. TRANSFER_INSUFFICIENT_BALANCE carries details.available and details.required.
• The amount must be between the account's minimum and maximum transfer, in internalTransfer in the limits.
• The daily cap is its own, separate from withdrawals: dailyInternalTransfer. 0 blocks every transfer and limit: null means no cap. Going over it responds 422 TRANSFER_DAILY_LIMIT.
• Up to 5 requests per minute per credential and 10 per account. Above that, the API responds 429 with Retry-After.

Rejections

The ones that call for another destination or a change on the account:

All rejections, with the code, are in Transfer to another PayZu account, and credential and scope rejections are in Authentication.