API Reference

¿Cómo ocupar las APIs Forpay?

Esta sección describe el flujo técnico completo para integrar con las APIs de Forpay: desde la autenticación hasta el cobro de cuotas y los procesos secundarios.

Antes de comenzar

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

1. Autenticación

Antes de consumir cualquier endpoint es necesario obtener un token de acceso cifrado. Este token tiene una duración de 30 minutos y se obtiene desde el endpoint de login.

POST /login

El token debe incluirse en el header Authorization de todas las solicitudes posteriores:

Authorization: Bearer <tu_token>

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.

Ver Autenticación para el detalle completo del proceso de login con JWE.

2. Crear cliente

Registra o asocia al cliente al comercio en el ambiente elegido mediante POST /user. Para continuar, guarda payload.customer.internalUserId de la respuesta. En este recorrido utilizaremos el valor ficticio 100001.

customer.userId es un identificador externo asignado por tu sistema, como CLIENTE-001; no es el RUT. El documento tributario se informa por separado en identificationDocument. Si el cliente ya está asociado, una respuesta exitosa puede conservar sus datos personales existentes.

Solicitud de ejemplo:

{
  "customer": {
    "userId": "CLIENTE-001",
    "identificationDocument": {
      "documentType": "RUT",
      "documentNumber": 11111111,
      "verificationNumber": "1"
    },
    "personalInformation": {
      "name": "Cliente",
      "lastName": "Ejemplo"
    },
    "contacts": {
      "email": "[email protected]",
      "phone": "56900000000",
      "cellphone": "56900000000"
    }
  }
}

Respuesta ilustrativa:

{
  "statusCode": 200,
  "message": "USER_OK",
  "payload": {
    "customer": {
      "internalUserId": 100001,
      "activationId": "",
      "userId": "CLIENTE-001"
    }
  }
}

Los datos son ficticios. Usa la información real del cliente en el ambiente correspondiente y conserva el ID devuelto por Forpay. Consulta Create User para el contrato completo.

3. Crear compromiso de pago

Este recorrido utiliza un mandato dinámico como ejemplo. Crea DYNAMIC-001 mediante POST /mandate, asociado a customer.internalUserId: 100001. Envía el header processId: HYBRID y los demás headers requeridos por la operación.

La solicitud siguiente crea únicamente la cabecera del mandato: no envía cuotas y establece needPayNow: false. Las cuotas se cargarán después mediante otra llamada.

{
  "mandate": {
    "id": "DYNAMIC-001",
    "type": "DYNAMIC",
    "name": "Mandato dinámico de ejemplo",
    "detail": "Mandato dinámico para cargar cuotas mediante solicitudes posteriores",
    "charges": {
      "startDate": "2026-12-01",
      "endDate": "2026-12-31",
      "wayToPay": "AUTOMATICO",
      "values": {
        "maximum": 200000,
        "currencyId": "PESOS"
      }
    },
    "needPayNow": false
  },
  "paymentMethods": [
    "ONECLICK"
  ],
  "urls": {
    "callback": "https://comercio.example/retorno",
    "activationWebhook": "https://comercio.example/webhooks/activacion",
    "paymentWebhook": "https://comercio.example/webhooks/pagos"
  },
  "customer": {
    "internalUserId": 100001
  }
}

Respuesta ilustrativa de creación sin firma:

{
  "statusCode": 200,
  "message": "MANDATE_CREATE_OK",
  "payload": {
    "customer": {
      "internalUserId": 100001,
      "userId": "CLIENTE-001"
    },
    "mandate": {
      "internalId": 200001,
      "id": "DYNAMIC-001"
    },
    "installments": [],
    "activation": {
      "url": "<URL_DEVUELTA_POR_FORPAY>"
    }
  }
}

Guarda payload.mandate.internalId (200001 en este ejemplo) y payload.mandate.id (DYNAMIC-001). El enlace se obtiene de payload.activation.url cuando esté presente. Utiliza exactamente el valor devuelto; la URL del ejemplo no es utilizable. La respuesta de creación no confirma una activación ni un pago.

Consulta los casos completos de Dynamic, Permanent, Subscription y OnePay.

4. Activación del compromiso

Entrega al cliente el Magic Link recibido en payload.activation.url. El enlace abre el flujo de Forpay para completar la activación y registrar el medio de pago permitido para ese mandato. En productos y configuraciones de pago inmediato también puede conducir al pago; obtener o abrir el enlace no confirma el resultado.

En una integración HYBRID, Forpay puede enviar el correo de alta cuando esa notificación esté habilitada para el comercio. Una respuesta exitosa de creación no garantiza la entrega de ese correo; tu sistema puede utilizar el enlace devuelto para presentarlo o comunicarlo al cliente.

Las URLs cumplen funciones diferentes:

CampoFunción
urls.callbackURL de retorno de la navegación del cliente. El retorno no confirma por sí solo activación ni pago.
urls.activationWebhookDestino de los eventos de activación o anulación habilitados para el comercio.
urls.paymentWebhookDestino de los eventos de pago habilitados para el comercio.

La activación es asincrónica. Actualiza el estado de tu integración a partir de los eventos correspondientes o de la consulta de estado; no interpretes el correo, el enlace o el retorno de navegación como confirmación.

Consulta Notificaciones de Activación y Notificaciones de Pago.

5. Cargar cuotas (Mandato Dinámico)

La carga de cuotas es una operación separada del alta del mandato. La numeración de esta guía no establece que completar el enlace sea requisito para llamar a POST /installments; la activación y la carga son acciones distintas. Para este ejemplo, envía POST /installments con el cliente 100001 y el mandato 200001 devueltos en los pasos anteriores.

Este request agrega una cuota de 25000 PESOS con vencimiento el 10 de diciembre de 2026. El ID DYNAMIC-001-01 lo asigna tu sistema y debe identificar ese cobro de forma única. No envíes payNow en esta operación.

{
  "customer": {
    "internalUserId": 100001
  },
  "product": {
    "internalId": 200001,
    "type": "DYNAMIC"
  },
  "installments": [
    {
      "id": "DYNAMIC-001-01",
      "installmentNumber": 1,
      "type": "CUOTA",
      "name": "Cuota 1 de ejemplo",
      "amount": 25000,
      "installmentDueDate": "2026-12-10",
      "state": "PENDIENTE",
      "currencyId": "PESOS",
      "currencyConvert": "TO_DAY"
    }
  ],
  "installmentsNumber": 1,
  "urls": {
    "paymentWebhook": "https://comercio.example/webhooks/pagos"
  }
}

Respuesta ilustrativa:

{
  "statusCode": 200,
  "message": "INSTALLMENTS_CREATE",
  "payload": {
    "product": {
      "internalId": 200001,
      "type": "DYNAMIC"
    },
    "installments": [
      {
        "id": "DYNAMIC-001-01",
        "installmentNumber": 1,
        "type": "CUOTA",
        "name": "Cuota 1 de ejemplo",
        "amount": 25000,
        "installmentDueDate": "2026-12-10",
        "state": "PENDIENTE",
        "currencyId": "PESOS",
        "currencyConvert": "TO_DAY",
        "internalId": 300001
      }
    ]
  }
}

Guarda el internalId devuelto para cada cuota (300001 en este ejemplo) junto con su ID externo. Crear una cuota no significa que esté pagada. Los resultados de cobro se conocen mediante los eventos habilitados de paymentWebhook y las consultas de estado.

El mandato dinámico permite que tu integración cargue nuevos cobros cuando corresponda; no configura por sí mismo una recurrencia mensual como una suscripción. Consulta Create Installments antes de enviar nuevas cuotas.

6. Cobro de cuotas

Forpay procesa los cobros según las condiciones y el estado del compromiso. Los eventos de pago se envían al paymentWebhook configurado cuando están habilitados para el comercio, de acuerdo con el medio de pago y el estado del intento.

Guarda los identificadores recibidos para relacionar el evento con su mandato y cuota. También puedes consultar un mandato por su ID interno para conocer su estado.

Consulta Notificaciones de Pago para los payloads de cada medio y estado.

Procesos secundarios

Anular un compromiso de pago

DELETE /mandate/cancel/internalId/{mandateId}/internalUserId/{internalUserId}

Envía description en la query como motivo de cancelación, con una cadena no vacía. La anulación se notifica al activationWebhook configurado cuando el evento está habilitado para el comercio.

Cambiar el estado de una cuota

PUT /installments/status/change

Permite marcar una cuota como pagada (state: 2) o anulada (state: 6) desde tu sistema. La respuesta de éxito es 204 No Content. Envía product y exactamente uno de installments o payments en la raíz. Usa IDs externos para mandato y cuotas, o IDs internos para ambos. Consulta el contrato de cambio de estado.

Consultar un mandato

GET /mandate/internalId/{mandateId} // ID generado por Forpay
GET /mandate/id/{mandateExternalId} // ID asignado por ti

Retorna toda la información del compromiso: datos del cliente, estado del mandato, cuotas y sus estados. La búsqueda puede hacerse por IDs internos de Forpay o por los IDs externos de tu sistema.

Diagrama de flujo completo

Los números corresponden a los seis pasos de esta guía, cuyo ejemplo utiliza un mandato dinámico. Los pasos 4 y 5 representan acciones separadas: su numeración no establece que completar el enlace sea un requisito para llamar a POST /installments.

1. Autenticación
   Tu sistema → POST /login → token de acceso
        ↓
2. Crear cliente
   Tu sistema → POST /user → guarda el internalUserId recibido
        ↓
3. Crear compromiso de pago
   Tu sistema → POST /mandate
   Envía customer.internalUserId y guarda el ID interno del mandato.
        ├─────────────────────────────────────────────┐
        ↓                                             ↓
4. Activación del compromiso                   5. Cargar cuotas (Mandato Dinámico)
   Comparte el enlace recibido.                  Tu sistema → POST /installments
   El cliente completa el flujo                  Usa el cliente y el mandato
   de inscripción del medio.                     devueltos en los pasos 2 y 3.
        └─────────────────────────────────────────────┘
                              ↓
6. Cobro de cuotas
   Forpay procesa los cobros del compromiso.
   Tu sistema recibe los eventos habilitados y consulta el estado.

activationWebhook informa los eventos de activación habilitados para el comercio. paymentWebhook informa los eventos de pago según el medio y su estado. El diagrama no establece que las notificaciones deban llegar en un único orden.

Seguimiento del ejemplo dinámico

Los siguientes identificadores son ficticios y se usan únicamente para mostrar su relación. En tu integración debes conservar los valores que devuelva la API.

DatoValor del ejemploUso posterior
ID interno del cliente devuelto por POST /user100001customer.internalUserId al crear el mandato y las cuotas
ID externo que tu sistema asigna al mandatoDYNAMIC-001mandate.id en la creación
ID interno del mandato devuelto por Forpay200001product.internalId, consulta y anulación por ID interno
ID externo que tu sistema asigna a la cuotaDYNAMIC-001-01installments[].id al crearla
ID interno de la cuota devuelto por Forpay300001Identificación interna de esa cuota en operaciones posteriores

Procesos secundarios

Estas operaciones se utilizan cuando las necesitas y no forman pasos adicionales de la creación:

GET /mandate/internalId/200001
PUT /installments/status/change
DELETE /mandate/cancel/internalId/200001/internalUserId/100001?description=Solicitud%20del%20cliente

En el cambio de estado, usa product.internalId: 200001 y los identificadores internos de las cuotas, como 300001, de acuerdo con el contrato de la operación. La variante con IDs externos se explica por separado en las fichas correspondientes; no envíes simultáneamente customer.userId y customer.internalUserId.

Updated 2 days ago

Did this page help you?

Updated 2 days ago

Did this page help you?