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

Onde guardar

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.

Formato de erro

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

{
  "errorCode": "PZA203",
  "message": "Acesso não permitido a partir do endereço de IP 203.0.113.10.",
  "statusCode": 403,
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

O catálogo completo, com os campos opcionais details[] e retryAfterSeconds, está em Códigos de erro.

Sempre logue o requestId nos seus erros: é o primeiro dado que o suporte pede, e o snippet de logging com a estratégia completa de retry está em Tratamento de erros.

Abrir suporte com o requestId

Escopos do token

Cada token carrega um ou mais escopos, e eles definem quais rotas ele abre. O mesmo token pode ter DEPOSIT e WITHDRAW.

As consultas DICT (GET /v1/pix/key e POST /v1/pix/qrcode/read) aceitam qualquer um dos dois escopos.

Um token sem o escopo exigido pela rota recebe 403 com errorCode PZA200.

Resolvendo erros

401 Unauthorized

As causas mais comuns, em ordem:

1. Token ausente, header Authorization não foi enviado.
2. Token incorreto, typo, espaço em branco extra, encoding errado.
3. Token revogado, foi rotacionado e você está usando o antigo.

Exemplo de resposta:

{
  "errorCode": "PZA100",
  "message": "Autenticação necessária ou token inválido.",
  "statusCode": 401,
  "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 PayZu imediatamente para emissão de novo token e revogação do anterior.

Whitelist de IP

A whitelist de IP define de quais endereços a conta aceita chamadas. A checagem roda em toda rota /v1 autenticada por token, nas consultas e nas operações que movem dinheiro, e usa o IP público de origem da requisição.

A mensagem de PZA203 e de PZA205 traz o IP de origem que chegou à PayZu. Um IP novo de saída só passa a ser aceito depois de cadastrado, e o IP antigo segue aceito até ser removido.

Remover o último IP cadastrado revoga, na mesma operação, todos os tokens da conta com escopo WITHDRAW. A partir daí, chamadas com esses tokens recebem 401, e a conta aceita chamadas de qualquer IP com os tokens que restaram.

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.