Autenticación

Resumen

Todas las llamadas a la API del Payment Gateway (excepto la tokenización, que usa su llave pública) requieren un token Bearer obtenido mediante el endpoint /oauth/token.

Características clave:

• Tipo de grant: Client Credentials (máquina a máquina)
• Vigencia del token: De corta duración (típicamente 1 hora) — solicite un nuevo token cuando expire
• Transporte: Use siempre HTTPS; nunca envíe credenciales por conexiones sin cifrar
• Almacenamiento: Los tokens deben almacenarse de forma segura del lado del servidor; nunca los exponga en código del lado del cliente

Obtención de un Token de Acceso

POST /oauth/token

Solicitud

curl -X POST https://{FQDN}/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "secretId": "YOUR_CLIENT_SECRET"
  }'

Respuesta (Éxito — 200)

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Respuesta (No Autorizado — 401)

{
  "status": 401,
  "message": "Unauthorized request",
  "responseCode": "SE_001"
}

Uso del Token

Incluya el token de acceso en el header Authorization de cada solicitud a la API:

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Mejores Prácticas de Gestión de Tokens

1. Almacene los tokens en caché — Reutilice el mismo token hasta que expire en lugar de solicitar uno nuevo por cada llamada a la API. El endpoint de autenticación tiene un límite de 60 solicitudes/minuto.

2. Maneje la expiración con elegancia — Cuando reciba una respuesta 401 o 403, solicite un nuevo token y reintente la solicitud original.

3. Nunca exponga credenciales del lado del cliente — El clientId y el secretId solo deben usarse desde su servidor backend (patrón Backend-for-Frontend). La única credencial del lado del cliente es la publicKey usada para la tokenización de tarjetas.

4. Rote los secretos periódicamente — Contacte al equipo de Inyo para rotar su secreto de cliente si sospecha que ha sido comprometido.

Autenticación vs. Tokenización

Límites de Tasa

Cuando se alcanza el límite de tasa, la API devuelve HTTP 429. Implemente backoff exponencial con jitter en su lógica de reintentos.