Internal transfer

Move balance between two PayZu accounts instantly, without going out over the Pix network, ideal for transfers between a head office and its branches or paying partners who are also on PayZu.

POSTPOST /internal-transfer/internal-transfer GETGET /internal-transfer/internal-transfer Idempotência Webhooks

When to use

Transfer between accounts of the same operation (headquarters/branch)
Payment to a partner that is also a PayZu customer
Internal balance movement (wallets, operational sub-accounts)

Create transfer

You need the accountNumber (6 digits) of both payer and receiver. The payer must match the account authenticated by the token.

curl -X POST https://api.payzu.processamento.com/v1/internal-transfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payerAccountNumber": "000000",
    "receiverAccountNumber": "987654",
    "amount": 100.50,
    "description": "Pagamento referente a fatura #1234",
    "callbackUrl": "https://seusite.com.br/webhooks/payzu",
    "clientReference": "transfer-abc-123"
  }'

const res = await fetch('https://api.payzu.processamento.com/v1/internal-transfer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payerAccountNumber: '000000',
    receiverAccountNumber: '987654',
    amount: 100.50,
    description: 'Pagamento referente a fatura #1234',
    callbackUrl: 'https://seusite.com.br/webhooks/payzu',
    clientReference: 'transfer-abc-123',
  }),
});

res = requests.post(
    'https://api.payzu.processamento.com/v1/internal-transfer',
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        'payerAccountNumber': '000000',
        'receiverAccountNumber': '987654',
        'amount': 100.50,
        'description': 'Pagamento referente a fatura #1234',
        'callbackUrl': 'https://seusite.com.br/webhooks/payzu',
        'clientReference': 'transfer-abc-123',
    },
)

Fields

Field	Type	Required	Description
`payerAccountNumber`	string	Yes	Payer account (6 digits). Must match the token.
`receiverAccountNumber`	string	Yes	Destination account (6 digits).
`amount`	number	Yes	Amount in BRL. Minimum R$ 0.01.
`description`	string	No	Free text up to 500 characters.
`callbackUrl`	string	No	URL to receive updates.
`clientReference`	string	No	External identifier (idempotência). Max 64 chars.
`virtualAccount`	string	No	Virtual sub-account (multi-tenant). Max 50 chars.

Full schema at POST /internal-transfer.

Query

Accepts id, clientReference or virtualAccount (use only one).

curl "https://api.payzu.processamento.com/v1/internal-transfer?clientReference=transfer-abc-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Differences vs Pix Payment

Aspect	Internal transfer	Pix withdrawal (`/withdraw`)
Destination	PayZu account	Any bank/account
Fee	Per account fee schedule	Per fee schedule
Settlement	Instant	Pix in seconds
Identifier	`accountNumber` (6 digits)	Pix key or QR Code

The destination account's accountNumber comes from the PayZu partner. The platform does not expose a public account directory.