Autenticação
Visão Geral
A API PIX Bacen utiliza exatamente o mesmo sistema de autenticação da API padrão FyPay. Não existe rota de token específica para o formato Bacen: o token é gerado em POST https://api.fypay.me/api/auth/token e todas as requisições aos endpoints Bacen devem incluir esse token Bearer no header Authorization.
A autenticação é idêntica à da API padrão. Se você já possui credenciais e certificado, pode usá-los diretamente.
Obtendo o Token
Endpoint
POST https://api.fypay.me/api/auth/tokenEsta rota exige mTLS: o certificado de cliente X.509 (PEM, RSA 2048, válido por 2 anos, vinculado à sua conta) e a respectiva chave privada são apresentados no handshake TLS, e não em um header HTTP. Os endpoints Bacen em si não exigem certificado, apenas o token Bearer.
Request
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": "seu-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']Response (201 Created)
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}Usando o Token
Inclua o token em todas as requisições da API PIX Bacen:
curl -X PUT https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{...}'Parâmetros de Autenticação
Identificador da credencial, no formato UUID v4. Gerado no Painel FyPay, em Configurações → Credenciais.
Segredo da credencial. É exibido uma única vez no painel, no momento da geração.
Nunca exponha o clientSecret, o certificado ou a chave privada em código frontend ou repositórios públicos.
Campos da Resposta
access_tokenstringToken JWT para autenticação nas requisições.
token_typestringTipo do token. Sempre "Bearer".
expires_innumberTempo de vida do token em segundos. Não assuma um valor fixo: use este campo para agendar a renovação.
scopestringEscopo do token.
Renovação do Token
O token expira após expires_in segundos. Implemente renovação automática:
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;
}
}Erros de Autenticação
| Código | Descrição | Solução |
|---|---|---|
| 401 | Token não fornecido | Inclua o header Authorization: Bearer <token> |
| 401 | Token inválido | Verifique se o token está correto e não expirou |
| 401 | Token expirado | Obtenha um novo token via POST /api/auth/token |
| 400/401/403 | Erro no certificado ou nas credenciais em /api/auth/token (códigos PUB_*, como PUB_CERT_HEADER_MISSING, PUB_INVALID_CREDENTIALS e PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT) | Consulte a referência de erros no guia de autenticação padrão |