身份认证

如何发送

每次调用都需要两个必填 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 内部日志中唯一标识该次调用。

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

字段	用途
`statusCode`	响应的 HTTP 状态码(与 status 一致)。
`error`	错误简称(`Unauthorized`、`Bad Request`、`Internal Server Error`)。
`message`	葡萄牙语描述错误内容。用于日志记录,而非展示给最终用户。
`requestId`	PayZu 中该次调用的唯一 ID。开支持工单时附上此 ID,他们可以直接追溯。

请始终在错误日志中记录 requestId。当您以"生产环境出错"开支持工单时,团队首先要的就是这个 ID。有 requestId 几分钟即可定位问题;没有则可能要花几个小时。

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

通过 requestId 开启支持

提交工单知识库支持门户

错误排查

401 Unauthorized

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

Token 缺失,未发送 Authorization header。
Token 错误,拼写错误、多余空格、编码错误。
Token 已吊销,已轮换但您仍在使用旧 token。
权限不足,该 token 不具备此 endpoint 所需的作用域。

响应示例:

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

403 Forbidden

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

轮换

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

On this page