PayZu Docs

每次调用都要带一个和密码一样重要的 Bearer 令牌：教你怎么发送、如何安全保管，以及收到 401 或 403 时该怎么办。

如何发送

每次调用都需要两个必填 header:

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

带认证的余额查询调用示例:

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

存储位置

绝不要将 token 暴露在前端、公开仓库或日志中。请把它当作密码:存放于密钥库,通过环境变量注入。

推荐方案:

Google Secret Manager,如果您已在使用 GCP,这是理想选择。
HashiCorp Vault,适用于自托管环境。
AWS Secrets Manager,AWS 的等价方案。
CI 环境变量,切勿提交到代码库。

错误格式

PayZu 所有的错误响应(4xx 和 5xx)都遵循同一格式。最重要的字段是 requestId,它在 PayZu 内部日志中唯一标识该次调用。

{
  "errorCode": "PZA203",
  "message": "不允许从此 IP 地址访问。",
  "statusCode": 403,
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

字段	用途
`errorCode`	目录中的稳定代码(例如 `PZA203`)。用它而非消息来编写你的逻辑。
`message`	葡萄牙语描述错误内容。用于日志记录,而非展示给最终用户。
`statusCode`	响应的 HTTP 状态码(与 status 一致)。
`requestId`	PayZu 中该次调用的唯一 ID。开支持工单时附上此 ID,他们可以直接追溯。

完整目录(含可选字段 details[] 和 retryAfterSeconds)见错误代码。

请始终在错误日志中记录 requestId:这是支持团队首先要的信息;日志片段和完整的重试策略见错误处理。

通过 requestId 开启支持

提交工单

令牌作用域

每个 token 带有一个或多个作用域,它们决定该 token 可以调用哪些路由。同一个 token 可以同时拥有 DEPOSIT 和 WITHDRAW。

作用域	可调用的路由
`DEPOSIT`	Pix 收款:`POST /v1/pix`、`GET /v1/pix` 和 `GET /v1/pix/qr-code/:transactionId`。
`WITHDRAW`	付款与资金流出:`POST /v1/withdraw`、`POST /v1/withdraw/qrcode`、`GET /v1/withdraw`、`POST /v1/internal-transfer`、`GET /v1/internal-transfer` 和 `POST /v1/refund/:transactionId`。

DICT 查询(GET /v1/pix/key 和 POST /v1/pix/qrcode/read)接受这两个作用域中的任意一个。

缺少路由所需作用域的 token 会收到 403,errorCode 为 PZA200。

错误排查

401 Unauthorized

最常见的原因,按顺序排列:

Token 缺失,未发送 Authorization header。
Token 错误,拼写错误、多余空格、编码错误。
Token 已吊销,已轮换但您仍在使用旧 token。

响应示例:

{
  "errorCode": "PZA100",
  "message": "需要身份验证或令牌无效。",
  "statusCode": 401,
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

403 Forbidden

Token 有效,但无权执行该操作。请检查 endpoint 是否需要额外作用域,或您的账户是否已开通该功能(例如内部转账可能需要预先审批)。

轮换

如果 token 泄露,请立即联系 PayZu 支持,以便签发新 token 并吊销旧 token。

Pix 付款与转账的 IP 白名单

为资金流出账户的操作提供额外一层保护。白名单启用后,POST /v1/withdraw、POST /v1/withdraw/qrcode 和 POST /v1/internal-transfer 仅接受来自已登记 IP 的调用。其他任何 IP 都会收到 403,errorCode 为 PZA203,即使 token 有效。这些路由的 GET 查询也经过同样的校验。

如何管理

在 Web 面板中自助管理,位于安全菜单的 IP 白名单 部分。每次添加或删除都需要 step-up 确认(操作密码),所有变更均记录审计。

限制:

每个账户最多 20 个生效 IP。
每 5 分钟最多 5 次添加。

被锁定禁止变更的账户在尝试添加或删除 IP 时会收到 403,errorCode 为 PZA204。此时请联系支持团队。

最佳实践

登记基础设施的 固定出口 IP(NAT/egress)。本地机器的动态 IP 会在第一次变化时失效。
迁移基础设施时,先添加新 IP,再删除旧 IP,这样过渡期间 Pix 付款不会中断。
在代码中将 PZA203 视为配置错误而非业务错误:应通知基础设施团队,而不是重试。

身份认证