1. Authentication

Antes de consumir cualquier endpoint de la API de Forpay, es obligatorio autenticarse y obtener un token de acceso. Todos los endpoints posteriores requieren que se incluya este token en el encabezado Authorization como un Bearer token.

Endpoint de login

Obtén el token de acceso mediante POST /login.

Consulta URL base y rutas para seleccionar el ambiente de tu integración.

Headers requeridos

country obligatorio con valor CL.
commerce obligatorio, de 5 a 30 caracteres, con el identificador de comercio asignado.
channel obligatorio, de al menos 3 caracteres, con el canal autorizado.
requestDateTime obligatorio, con fecha y hora en formato ISO 8601.
correlationId obligatorio, de al menos un carácter. Se recomienda un UUID para trazabilidad.
processId: obligatorio. Para el flujo de nuevas integraciones documentado en esta guía, utiliza HYBRID.
salesExecutiveId obligatorio, de al menos un carácter.
x-api-key correspondiente al ambiente y al plan de consumo asignado.

Parámetros de autenticación

Parámetro	Tipo	Requerido	Descripción
`username`	string	Sí	RUT + ID interno de la empresa (igual que `commerce`)
`password`	string	Sí	Contraseña cifrada en formato JWE

Envía username y password cifrado en JWE en el cuerpo JSON de POST /login.

Cómo generar el password JWE

El password debe enviarse cifrado en formato JWE (JSON Web Encryption) utilizando:

Algoritmo: RSA-OAEP-256
Cifrado: A256GCM
Librería recomendada: jose (Node.js/JavaScript)

El proceso de cifrado debe realizarse en el backend de tu sistema. Nunca compartas el password en texto plano.

Ejemplo con la librería `jose` (Node.js)

import { CompactEncrypt, importSPKI } from 'jose';

const publicKeyPem = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;

const plainPassword = process.env.FORPAY_PASSWORD;

const publicKey = await importSPKI(publicKeyPem, 'RSA-OAEP-256');

const jwe = await new CompactEncrypt(
  new TextEncoder().encode(plainPassword)
)
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .encrypt(publicKey);

// jwe es el valor de password en el body de POST /login
console.log(jwe);

Respuesta exitosa (200 OK)

{
  "statusCode": 200,
  "message": "ACCESS_CONFIRM",
  "payload": {
    "token": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0..."
  }
}

Respuesta de error (403 Forbidden)

Los errores capturados por el handler de login se devuelven como 403, incluidos errores de validación y ciertas fallas internas.

{
  "statusCode": 403,
  "message": "Prohibido",
  "code": "FORBIDDEN"
}

Cómo usar el token JWT

El token de acceso es un JWT cifrado, entregado como JWE compacto de cinco segmentos y con una vigencia de 30 minutos. Envíalo en Authorization: Bearer <token>, junto con la API key del ambiente y el contexto y permisos autorizados para el comercio y la ruta.

En las operaciones protegidas, usa el encabezado siguiente.

Authorization: Bearer <token>

Consideraciones importantes

Genera un JWE nuevo para la contraseña en cada intento de login, incluidos reintentos tras error o timeout. La entrada cifrada puede quedar registrada antes de validar la contraseña.
El token de acceso tiene vigencia de 30 minutos. Al expirar, realiza un login nuevo con un JWE de contraseña recién generado.
El acceso requiere la API key correspondiente, el contexto de comercio y canal autorizado y permiso sobre la ruta.
Automatiza el cifrado y la renovación desde tu backend.
Los errores capturados por el handler de login se responden con 403, incluidos datos mal formados, credenciales inválidas y ciertas fallas internas. Un 403 requiere revisar el detalle recibido y el contexto de la solicitud.

API Gateway también puede rechazar una solicitud antes del handler. Sus errores pueden usar un cuerpo con message, y tienen sus propios códigos de autenticación, límites o timeout. Consulta los límites de tasa, ráfaga y cuota asignados a tu API key con Forpay. Ante un 429, reduce la frecuencia y aplica espera progresiva antes de reintentar.