身份认证
Conta Digital API 的每个调用都在 Authorization header 中使用 Bearer Token。Token 由 PayZu Dashboard 提供。
Header 格式
每个请求都需要两个必填 header:
Authorization: Bearer SEU_TOKEN
Content-Type: application/json示例
curl https://pix.payzu.io/v1/user/balance \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Content-Type: application/json"const res = await fetch('https://pix.payzu.io/v1/user/balance', {
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
});
const balance = await res.json();import os, requests
res = requests.get(
'https://pix.payzu.io/v1/user/balance',
headers={
'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
'Content-Type': 'application/json',
},
)重要事项
- 妥善保管 token,切勿公开分享或提交到代码仓库
- token 按权限分配,每个 token 在创建时都带有指定的作用域
- token 泄露了? 立即在 PayZu Dashboard 中重新生成并吊销旧 token
错误格式
所有错误响应都遵循同样的格式。最重要的字段是 requestId,它用于在 PayZu 内部日志中定位该调用。
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Missing or invalid Bearer token",
"requestId": "cmp70zh4008dx01s6bwjb5bez"
}| 字段 | 用途 |
|---|---|
statusCode | 响应的 HTTP 状态码 |
error | 错误简称 |
message | 葡萄牙语错误描述 |
requestId | 调用的唯一 ID。提交支持工单时请附上 |
存放位置
| 存放位置 | 可以吗? |
|---|---|
| Google Secret Manager | 可以 |
| AWS Secrets Manager | 可以 |
| HashiCorp Vault | 可以 |
| CI 中的环境变量 | 可以 |
生产环境中的 .env | 不可以 |
| 前端(Web、移动端) | 绝不可以 |
支持
Primeiros passos
Em menos de 10 minutos você cria conta, valida o token, faz a primeira cobrança Pix e recebe um callback de teste. Caminho mais curto da PayZu até a primeira transação na Conta Digital.
Depósitos
Endpoints para criar cobranças Pix dinâmicas (entrada de dinheiro), consultar status, gerar comprovante e estornar valores recebidos.