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.exemplo.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $PIX_TOKEN" \
  -H "Content-Type: application/json"

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

import os
import requests

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

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

<?php
$ch = curl_init('https://api.exemplo.processamento.com/v1/user/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PIX_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 Pix Processamento (4xx and 5xx) follows the same format. The most important field is requestId, which uniquely identifies the call in Pix Processamento's internal logs.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Não foi possível processar esta solicitação",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

try {
  const res = await fetch(url, { headers, body });
  if (!res.ok) {
    const err = await res.json();
    log.error('Pix Processamento error', {
      requestId: err.requestId,
      statusCode: err.statusCode,
      message: err.message,
      endpoint: url,
    });
    throw new Error(`Pix Processamento ${err.statusCode}: ${err.message} (requestId=${err.requestId})`);
  }
} catch (e) {
  // ...
}

Opening support with the requestId

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.
4. Insufficient permission, the token does not have the endpoint's scope.

Example response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "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 Pix Processamento support immediately to issue a new token and revoke the previous one.

IP whitelist for withdrawals 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 withdrawals 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.