Autenticação

Como enviar

Toda chamada precisa de dois headers obrigatórios:

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Exemplo de chamada autenticada para consultar o saldo:

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);

Onde guardar

Nunca expõe o token no front-end, em repositório público ou em logs. Trata como senha: armazena em vault e injeta por variável de ambiente.

Recomendações:

Google Secret Manager, ideal se você já usa GCP.
HashiCorp Vault, pra setups self-hosted.
AWS Secrets Manager, equivalente AWS.
Variável de ambiente em CI, nunca commita.

Toda resposta de erro da Pix Processamento (4xx e 5xx) segue o mesmo formato. O campo mais importante é o requestId, ele identifica univocamente a chamada nos logs internos da Pix Processamento.

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

Campo	Para que serve
`statusCode`	Código HTTP da resposta (espelha o status).
`error`	Nome curto do erro (`Unauthorized`, `Bad Request`, `Internal Server Error`).
`message`	Descrição em PT do que aconteceu. Use no log, não para usuário final.
`requestId`	ID único da chamada na Pix Processamento. Envie esse ID ao abrir chamado de suporte, eles rastreiam direto.

Sempre logue o requestId nos seus erros. Ao abrir suporte com "deu erro em produção", o time pede esse ID primeiro. Quem tem o requestId tem investigação em minutos; quem não tem, leva horas.

try {
  const res = await fetch(url, { headers, body });
  if (!res.ok) {
    const err = await res.json();
    log.error('Pix Processamento erro', {
      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) {
  // ...
}

Abrir suporte com o requestId

Abrir ticket Base de conhecimento Portal de suporte

Resolvendo erros

401 Unauthorized

As causas mais comuns, em ordem:

Token ausente, header Authorization não foi enviado.
Token incorreto, typo, espaço em branco extra, encoding errado.
Token revogado, foi rotacionado e você está usando o antigo.
Permissão insuficiente, o token não tem o escopo do endpoint.

Exemplo de resposta:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

403 Forbidden

O token é válido mas não tem permissão para a operação. Verifica se o endpoint exige escopo adicional ou se sua conta está habilitada para o recurso (por exemplo, transferência interna pode exigir aprovação prévia).

Rotação

Se o token vazar, contata o suporte da Pix Processamento imediatamente para emissão de novo token e revogação do anterior.

Whitelist de IP para saques e transferências

Camada extra de proteção para as operações que movem dinheiro para fora da conta. Quando a whitelist está ativa, POST /v1/withdraw, POST /v1/withdraw/qrcode e POST /v1/internal-transfer só aceitam chamadas dos IPs cadastrados. Qualquer outro IP recebe 403 com errorCode PZA203, mesmo com token válido. As consultas GET dessas mesmas rotas passam pela mesma validação.

Como gerenciar

A gestão é self-service no painel web, no menu Segurança, seção Whitelist de IP. Cada adição ou remoção exige confirmação step-up (senha de operação), e todas as alterações ficam registradas em auditoria.

Limites:

Até 20 IPs ativos por conta.
Até 5 cadastros a cada 5 minutos.

Conta travada para alterações responde 403 com errorCode PZA204 ao tentar adicionar ou remover IPs. Nesse caso, contate o suporte.

Boas práticas

Cadastre os IPs de saída fixos da sua infraestrutura (NAT/egress). IP dinâmico de máquina local vai quebrar na primeira troca.
Ao migrar de infraestrutura, adicione o novo IP antes de remover o antigo. Assim os saques continuam fluindo durante a transição.
Trate PZA203 no seu código como erro de configuração, não de negócio: alerta o time de infra em vez de retentar.