Autenticación
Descripción General
La API PIX Bacen utiliza exactamente el mismo sistema de autenticación que la API estándar de FyPay. No existe una ruta de token específica para el formato Bacen: el token se genera en POST https://api.fypay.me/api/auth/token y todas las solicitudes a los endpoints Bacen deben incluir ese token Bearer en el encabezado Authorization.
La autenticación es idéntica a la de la API estándar. Si ya tiene credenciales y certificado, puede usarlos directamente.
Obtención del Token
Endpoint
POST https://api.fypay.me/api/auth/tokenEsta ruta exige mTLS: el certificado de cliente X.509 (PEM, RSA 2048, válido por 2 años, vinculado a su cuenta) y su clave privada se presentan en el handshake TLS, no en un encabezado HTTP. Los endpoints Bacen en sí no exigen certificado, solo el token Bearer.
Solicitud
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": "su-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']Respuesta (201 Created)
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}Uso del Token
Incluya el token en todas las solicitudes de la 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 Autenticación
Identificador de la credencial, en formato UUID v4. Se genera en el Dashboard de FyPay, en Configuración → Credenciales.
Secreto de la credencial. Se muestra una sola vez en el dashboard, en el momento de la generación.
Nunca exponga el clientSecret, el certificado ni la clave privada en código frontend o repositorios públicos.
Campos de la Respuesta
access_tokenstringToken JWT para autenticar las solicitudes.
token_typestringTipo de token. Siempre "Bearer".
expires_innumberTiempo de vida del token en segundos. No asuma un valor fijo: use este campo para programar la renovación.
scopestringAlcance del token.
Renovación del Token
El token expira después de expires_in segundos. Implemente renovación 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;
}
}Errores de Autenticación
| Código | Descripción | Solución |
|---|---|---|
| 401 | Token no proporcionado | Incluya el encabezado Authorization: Bearer <token> |
| 401 | Token inválido | Verifique que el token sea correcto y no haya expirado |
| 401 | Token expirado | Obtenga un nuevo token vía POST /api/auth/token |
| 400/401/403 | Error de certificado o de credenciales en /api/auth/token (códigos PUB_*, como PUB_CERT_HEADER_MISSING, PUB_INVALID_CREDENTIALS y PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT) | Consulte la referencia de errores en la guía de autenticación estándar |