身份认证
概述
PIX Bacen API 使用与标准 FyPay API 完全相同的认证体系。不存在 Bacen 格式专用的令牌路由：令牌通过 POST https://api.fypay.me/api/auth/token 生成，所有对 Bacen 端点的请求都必须在 Authorization 请求头中携带该 Bearer 令牌。
认证方式与标准 API 完全相同。如果您已有凭证和证书，可以直接使用。
获取令牌
Endpoint
POST https://api.fypay.me/api/auth/token此路由要求 mTLS：X.509 客户端证书（PEM、RSA 2048、有效期 2 年、已关联到您的账户）及其私钥在 TLS 握手 中出示，而不是通过 HTTP 请求头发送。Bacen 端点本身不需要证书，只需要 Bearer 令牌。
请求
curl -X POST https://api.fypay.me/api/auth/token \
--cert client.crt \
--key client.key \
-H "Content-Type: application/json" \
-d '{
"clientId": "6967c0a0-3566-48d0-8c13-717038b52279",
"clientSecret": "your-client-secret"
}'import fs from 'node:fs';
import { Agent, request } from 'undici';
const mtlsAgent = new Agent({
connect: {
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
},
});
const { body } = await request('https://api.fypay.me/api/auth/token', {
method: 'POST',
dispatcher: mtlsAgent,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientId: process.env.FYPAY_CLIENT_ID,
clientSecret: process.env.FYPAY_CLIENT_SECRET,
}),
});
const { access_token, expires_in } = await body.json();import os
import requests
response = requests.post(
'https://api.fypay.me/api/auth/token',
json={
'clientId': os.environ['FYPAY_CLIENT_ID'],
'clientSecret': os.environ['FYPAY_CLIENT_SECRET'],
},
cert=('client.crt', 'client.key'),
)
access_token = response.json()['access_token']响应 (201 Created)
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}使用令牌
在所有 PIX Bacen API 请求中携带令牌：
curl -X PUT https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'认证参数
凭证标识符，UUID v4 格式。在 FyPay 控制面板 的 设置 → 凭证 中生成。
凭证密钥。仅在生成时于控制面板中显示 一次。
切勿在前端代码或公开仓库中暴露 clientSecret、证书或私钥。
响应字段
access_tokenstring用于请求认证的 JWT 令牌。
token_typestring令牌类型。始终为 "Bearer"。
expires_innumber令牌有效期（秒）。不要假设固定值：请使用此字段安排续期。
scopestring令牌作用域。
令牌续期
令牌在 expires_in 秒后过期。请实现自动续期：
import fs from 'node:fs';
import { Agent, request } from 'undici';
class TokenManager {
private token: string | null = null;
private expiresAt = 0;
private readonly agent = new Agent({
connect: {
cert: fs.readFileSync(process.env.FYPAY_CLIENT_CERT_PATH!),
key: fs.readFileSync(process.env.FYPAY_CLIENT_KEY_PATH!),
},
});
async getToken(): Promise<string> {
const safetyMarginMs = 30_000;
if (!this.token || Date.now() >= this.expiresAt - safetyMarginMs) {
await this.refreshToken();
}
return this.token!;
}
private async refreshToken(): Promise<void> {
const { body } = await request('https://api.fypay.me/api/auth/token', {
method: 'POST',
dispatcher: this.agent,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientId: process.env.FYPAY_CLIENT_ID,
clientSecret: process.env.FYPAY_CLIENT_SECRET,
}),
});
const data = (await body.json()) as { access_token: string; expires_in: number };
this.token = data.access_token;
this.expiresAt = Date.now() + data.expires_in * 1000;
}
}认证错误
| 状态码 | 描述 | 解决方案 |
|---|---|---|
| 401 | 未提供令牌 | 添加 Authorization: Bearer <token> 请求头 |
| 401 | 令牌无效 | 检查令牌是否正确且未过期 |
| 401 | 令牌已过期 | 通过 POST /api/auth/token 获取新令牌 |
| 400/401/403 | /api/auth/token 的证书或凭证错误（PUB_* 错误码，如 PUB_CERT_HEADER_MISSING、PUB_INVALID_CREDENTIALS 和 PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT） | 请参阅标准认证指南中的错误参考 |