Autenticación del API Bancario

El API Bancario usa un flujo de dos pasos: primero autenticás al cliente con correo y contraseña, después intercambiás el token resultante por un access token JWT que firma todas las demás llamadas.

Los tres endpoints del grupo Auth son los únicos que no llevan Authorization. Todo el resto del API exige Authorization: Bearer <access_token>.

Paso 1 — Login#

POST /api/public/v1/auth/login

Cuerpo requerido: email (formato email) y password.

{
  "email": "operaciones@comercio.com",
  "password": "••••••••"
}

La respuesta 200 devuelve en data:

Cada elemento de assignments trae assignment_id, owner_type, owner_id, tenant_id, tenant_code, country_code, role, roles y status. Elegí el assignment_id del contexto con el que vas a operar.

Paso 2 — Intercambio de token#

POST /api/public/v1/auth/token/exchange

Cuerpo requerido: gidp_id_token (el del paso 1) y assignment_id (el contexto elegido).

{
  "gidp_id_token": "eyJhbGciOi...",
  "assignment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

La respuesta 200 devuelve en data:

claims incluye sub, subject_kind, user_type, tenant_id, owner_type, owner_id, roles, scopes, country_code, locale, channel, idp, idp_sub e idempotency_key.

claims.idempotency_key es un campo reservado que siempre viene vacío: ignoralo. La idempotencia va en el header Idempotency-Key.

Paso 3 — Usar el Bearer#

El esquema de seguridad declarado es BearerAuth: HTTP bearer con formato JWT.

Authorization: Bearer <access_token>

El contexto viaja dentro del token: no se envían tenant_id, owner_id ni owner_type como parámetros en las operaciones de negocio. El token acota por sí solo a qué cuentas y pagos podés acceder.

Cuando el token está ausente, vencido o es inválido, la respuesta es 401 con response_code: UNAUTHORIZED. Si el token es válido pero el contexto no autoriza el recurso, es 403 con FORBIDDEN. No hay refresh token: para renovar, repetí login e intercambio (pasos 1 y 2) antes del vencimiento, recomendado al 80 % de expires_in, o al recibir un 401.

Contraseñas#

POST /api/public/v1/auth/request-set-password

Inicia el proceso de establecer o restablecer la contraseña del correo indicado. No requiere autenticación previa y responde siempre igual, exista o no la cuenta, para no revelar si un correo está registrado.

{
  "email": "operaciones@comercio.com"
}

Límites de tasa#

Actualmente aplican en autenticación y validación de cuentas. Al superarlos, se responde 429 (TOO_MANY_REQUESTS). Reintentá con espera exponencial.

Acceso al sandbox#

Tilopay emite las credenciales de prueba a solicitud; coordiná el acceso con el contacto de tu comercio en Tilopay.