Authentication

How to send

Every call requires two mandatory headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Example of an authenticated call to query the balance:

curl https://api.payzu.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $PAYZU_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://api.payzu.processamento.com/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

import os
import requests

res = requests.get(
    'https://api.payzu.processamento.com/v1/user/balance',
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)
balance = res.json()

req, _ := http.NewRequest("GET", "https://api.payzu.processamento.com/v1/user/balance", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("PAYZU_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.payzu.processamento.com/v1/user/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PAYZU_TOKEN'),
    'Content-Type: application/json',
  ],
]);
$balance = json_decode(curl_exec($ch), true);

Where to store

Recommendations:

• Google Secret Manager, ideal if you already use GCP.
• HashiCorp Vault, for self-hosted setups.
• AWS Secrets Manager, the AWS equivalent.
• Environment variable in CI, never commit it.

Error format

Every error response from PayZu (4xx and 5xx) follows the same format. The most important field is requestId, which uniquely identifies the call in PayZu's internal logs.

{
  "errorCode": "PZA203",
  "message": "Access not allowed from this IP address.",
  "statusCode": 403,
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

The full catalog, including the optional details[] and retryAfterSeconds fields, is in Error codes.

Always log the requestId in your errors: it is the first thing support asks for, and the logging snippet with the full retry strategy is in Error handling.

Opening support with the requestId

Token scopes

A token carries one or more scopes, and they define which routes it opens. The same token can have both DEPOSIT and WITHDRAW.

DICT lookups (GET /v1/pix/key and POST /v1/pix/qrcode/read) accept either scope.

A token without the scope the route requires receives 403 with errorCode PZA200.

Resolving errors

401 Unauthorized

The most common causes, in order:

1. Missing token, the Authorization header was not sent.
2. Incorrect token, typo, extra whitespace, wrong encoding.
3. Revoked token, it was rotated and you are using the old one.

Example response:

{
  "errorCode": "PZA100",
  "message": "Authentication required or invalid token.",
  "statusCode": 401,
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

403 Forbidden

The token is valid but does not have permission for the operation. Check whether the endpoint requires an additional scope or whether your account is enabled for the resource (for example, internal transfer may require prior approval).

Rotation

If the token leaks, contact PayZu support immediately to issue a new token and revoke the previous one.

IP whitelist for Pix payments and transfers

An extra layer of protection for the operations that move money out of the account. When the whitelist is active, POST /v1/withdraw, POST /v1/withdraw/qrcode and POST /v1/internal-transfer only accept calls from the registered IPs. Any other IP receives 403 with errorCode PZA203, even with a valid token. The GET queries of these same routes go through the same validation.

How to manage

Management is self-service in the web panel, under the Security menu, IP whitelist section. Every addition or removal requires step-up confirmation (operation password), and all changes are recorded for audit.

Limits:

• Up to 20 active IPs per account.
• Up to 5 additions every 5 minutes.

Best practices

• Register the fixed egress IPs of your infrastructure (NAT/egress). A dynamic IP from a local machine will break on the first rotation.
• When migrating infrastructure, add the new IP before removing the old one. That way Pix payments keep flowing during the transition.
• Treat PZA203 in your code as a configuration error, not a business error: alert your infra team instead of retrying.