En este documento se especifica las caracteristicas de la API, los tipos de transacciones soportadas, la seguridad que se utiliza para la autentificación y los distintos servicios que se disponen.

Esta API, dispone servicios de pagos con tarjetas de Crédito, Débito o Prepago de las marcas: MASTERCARD y VISA emitidas tanto en Chile como en el extranjero.

En KLAP existen dos distintos modelos de procesamiento:

• Modelo PSP en el que un Facilitador de Pago es el encargado de prestar servicios y realizar el pago a los Sub-Comercios
• Modelo Gateway donde el e-commerce realiza la negociación con KLAP y el gateway sólo responde por los protocolos de comunicación entre el e-commerce y KLAP.

Más adelante se explicará en detalle las caracteristicas de cada modelo.

Antes de ver los servicios que posee la API, se debe tener en claro las siguientes definiciones:

Autorización

Transacción que realiza validaciones para que la operación pueda realizarse exitosamente, verificando que la tarjeta esté activa, que la cuenta asociada tenga fondos suficientes, etc., y reserva el monto correspondiente a la operación.

Captura

Transacción que hace efectiva la operación previamente autorizada, cargando en la cuenta del tarjetahabiente el monto de la autorización y de las incrementales (si las hubiera) en una sola operación.

Incremental

Transacción asociada a una autorización, que incrementa el monto de la operación previamente autorizada, extendiendo a la vez el plazo para su captura.

Cargo demorado

Transacción que realiza un cargo en la cuenta del tarjetahabiente asociado a una autorización pero posterior a la captura.

Consulta de Estado de Cuenta

Transacción que permite validar la información de la cuenta del tarjetahabiente. Para efectuar esta operación, se realiza una autorización por monto cero.

Reversa

Transacción que anula una transacción previamente realizada, por problemas como: fallo en la conexión, tiempo de espera expirado, entre otros.

Esta transacción permite anular las siguientres transacciones:

• Autorización
• Captura
• Incremental
• Cargo Demorado

Cancelación Autorización

Transacción que anula una operación previamente autorizada a solicitud del cliente.

Esta transacción sólo puede efectuarse para anular:

• Autorización

Anulación

Transacción que anula una operación previamente realizada por el cliente.

Esta transacción permite anular las siguientres transacciones:

• Captura
• Cargo Demorado

En esta API, existen dos modalidades de transacciones de Pago:

• Autorización y Captura Simultánea
• Autorización y Captura Diferida

Autorización y Captura Simultánea

En este tipo de transacción, se realiza la autorización y captura en simultáneo, se realiza enviando solamente UNA solicitud, y está permitida para tarjetas de Crédito, Débito y Prepago.

Para tarjetas de Crédito, esta operación puede efectuarse como compra normal o en cuotas, teniendo para ello las siguientes opciones:

• Cuotas financiadas por el comercio
• Cuotas financiadas por el emisor

Autorización y captura diferida

Este tipo de transacción, es posible generar una transacción de autorización cierto día y realizar el envío de la captura correspondiente a la operación algún día posterior (dentro de los plazos establecidos para ello).

Esto también conlleva que se pueda incrementar el monto anteriormente autorizado y previamente a realizar la captura, o pueda realizar un cobro posterior a la captura mediante el servicio de cargo demorado.

• Los Montos deben estar en Pesos Chilenos (ISO 4217 = CLP)
• No soporta CORS
• No soporta Anulación Parcial. (por el momento)

Reglas de la API

• El campo consumer_transaction_id debe ser único (incluso en días y transacciones distintas).
• Todos los requerimientos deben ser realizados sobre HTTPS TLS 1.2. Los requerimientos sobre HTTP fallarán.
• Los campos del nodo card deben ser encriptados utilizando el algoritmo AES-256. El procedimiento para compartir la llave se acordará en otro documento.
• Todos los requerimientos son autenticados. Debe incluir el encabezado Api-Key: <key>.

Idempotencia

La API soporta idempotencia, por lo tanto puedes reintentar un requerimiento sin peligro de que el recurso se cree dos veces. Para esto debes incluir el encabezado Idempotency-Key: <key>, donde key es un identificador único de tu sistema o UUID. La clave tiene una validez de 24 horas.

Gestión de llaves

Los campos del nodo card se deben enviar encriptados por una llave simétrica utilizando el algoritmo AES-256. Para establecer la llave simétrica, el comsumidor de la API debe generar y enviar a KLAP un componente de la llave con sus respectivos dígitos de chequeo. KLAP generará y enviará otro componenente. Luego, ambos actores deberán cargar los componentes en sus HSMs, generando la llave final y verificando que los digitos de chequeo coincidan. Esta llave debe ser cambiada cada 3 años.

Versión 1.0

• Modelo PSP
• Transacciones con tarjeta MASTERCARD
• Transacciones con tarjeta de Crédito
• Pagos Recurrentes
• Pagos Card-on-File (CoF)
• Cuotas Comercio
• Cuotas Emisor

Versión 1.1

• Transacciones con tarjeta VISA
• Transacciones con tarjeta de Débito y Prepago

• Modelo Gateway
• Autorización y Captura Diferida
• Incremental
• Demorado
• Consulta de Estado de Cuenta
• Autorización y Captura Diferida (Crédito, Débito y Prepago)

Version 3.2109

• Se agrega campos code y message a respuesta 200
• Campo card opcional en transacciones subsiguientes.

Version 3.2112

• Anulación Parcial MASTERCARD y VISA
• Se agrega campo branch_id y terminal_id para soportar varias sucursales y terminales en modelo PSP y Gateway

Versión 3.2203

• Consulta de Transacción por el campo consumer_transaction_id o por el campo mc_code

Versión 3.22xx

• 3D-Secure

Versión 3.2xxx

• Transacciones con tarjeta MAESTRO
• Transacciones con tarjeta AMERICAN EXPRESS

El campo consumer_transaction_id es el identificador único por transacción y con este campo se realiza la vinculación entre Autorización y Captura, Reversas, Anulaciones, entre otros. Por lo tanto, este campo debe ser único incluso en días y transacciones distintas.

Por ejemplo:

"consumer_transaction_id": "935f4328-8217-405a-a22b-8464fa7aac9e"

Todos los requerimientos son autenticados. Debe incluir el encabezado Api-Key.

Por ejemplo:

Api-Key: YHw0yzEef0KnFD

Idempotency Key es un identificador único que dado a su propiedad, permite enviar dos o más veces una transacción idéntica y así conseguir el mismo resultado que se realizó en primera instancia.

Esta propiedad, permite re-intentar una transacción que haya sido aprobada, pero que ha tenido una interrupción entre el cliente y la API, enviando una nueva solicitud con los mismos valores para Idempotency-Key y de los datos en el cuerpo del mensaje.

Este valor es asignado en la cabecera de la solicitud de la siguiente manera Idempotency-Key

Por ejemplo:

Idempotency-Key: 935f4328-8217-405a-a22b-8464fa7aac9e

Los requerimientos deben ser realizados sobre HTTPS sobre TLS 1.2 o superior.

En el cuerpo del mensaje existe un campo card en el que se envian los datos. Éstos debe ser encriptados utilizando el algoritmo AES-256.

Por ejemplo:

"card": "mOoT6vkSI7z0ahhF7kN32cXAshL26UYHw0yzEef0KnFDbhtQRv6b1hoMkmdOCQsg"

El campo card corresponde a los datos de la tarjeta encriptados. Para encriptar los datos de la tarjeta, se debe enviar como una cadena de caracteres concatenada el Número de la Tarjeta o Primary Account Number (PAN), Fecha de Expiración de la tarjeta (formato aamm), Nombre del Tarjetahabiente impreso en la tarjeta, y de manera opcional el CVV que generalmente se encuentra impreso al reverso de la tarjeta. El formato para enviar a encriptar los datos debe ser el siguiente:

Actualmente en el modelo PSP (Payment Service Provider) para el Data Element-43 se enviará: el nombre del PSP de un largo máximo de 7 caracteres, más el nombre del comercio asociado al campo merchant.name y lo que se incluya en el campo additional_data.soft_descriptor.

Por ejemplo: Si el nombre del PSP es PAYMENT y en el cuerpo del mensaje en el campo merchant.name se envía: Store 123 y additional_data.soft_descriptor se envía Compra 12345, para este caso el soft-descriptor será:

  PAYMENT*STORE 123 Compra 12345

Para el modelo Gateway para el Data Element-43 se enviará: el nombre del comercio, y lo que se incluya en el campo additional_data.soft_descriptor.

Por ejemplo: Si el nombre del comercio es KLAP y en el campo additional_data.soft_descriptor se envía Compra 12345, para este caso el soft-descriptor será:

  KLAP Compra 12345

En el Soft-Descriptor (Data Element-43) hacia la marca de la tarjeta sólo se podrá enviar los primeros 14 caracteres.

• El Cobro Card-on-File corresponde a una transacción donde el tarjetahabiente autoriza al comercio almacenar los datos de la tarjeta, para posteriormente autorizar uno o más cobros por algun servicio, o producto.
• Este cobro es una transaccion iniciada por el tarjetahabiente y puede ser de distintos montos.
• La transaccion de almacenamiento de la tarjeta debe incluir el Card-Verfication-Value o CVV, y en el campo charge_type.code debe ir un 2.

Por ejemplo:

    "charge_type": {
      "code": 2
    }

• El Cobro Recurrente corresponde a una serie de pagos en plazos regulares y acordados previamente con el tarjetahabiente, estos cobros generalmente están asociados a servicios digitales o físicos.
• Este cobro es una transaccion iniciada por el comercio.
• El primer cobro debe incluir el Card-Verfication-Value o CVV, y en el campo charge_type.code debe ir un 3.

Por ejemplo:

    "charge_type": {
      "code": 3
    }

En este modelo, el Facilitador de Pago o PSP, es el encargado de prestar servicios que incluyen la liquidación y/o pago de las sumas que corresponden a cada sub-commercio por concepto de las transacciones efectuadas con tarjetas de pago a través de la API.

Cada PSP está encargado de pagar a cada uno de los sub-comercios asumiendo esta responsabilidad frente a KLAP.

Para este modelo, KLAP proporcionará una Api-Key la cual será utilizada unicamente por el PSP, la cual es secreta e intransferible. Y debe ser proporcionada en cada solicitud que se realice.

La sección Financiero corresponde a las transacciones solicitadas a voluntad del comercio o del tarjetabiente.

En este modelo, el Facilitador de Pago o PSP, es el encargado de prestar servicios que incluyen la liquidación y/o pago de las sumas que corresponden a cada sub-commercio por concepto de las transacciones efectuadas con tarjetas de pago a través de la API.

Cada PSP está encargado de pagar a cada uno de los sub-comercios asumiendo esta responsabilidad frente a KLAP.

Para este modelo, KLAP proporcionará una Api-Key la cual será utilizada unicamente por el PSP, la cual es secreta e intransferible. Y debe ser proporcionada en cada solicitud que se realice.

La sección Reversa corresponde a las transacciones solicitadas por el PSP para revertir el estado de una transacción.

En este modelo, el Facilitador de Pago o PSP, es el encargado de prestar servicios que incluyen la liquidación y/o pago de las sumas que corresponden a cada sub-commercio por concepto de las transacciones efectuadas con tarjetas de pago a través de la API.

Cada PSP está encargado de pagar a cada uno de los sub-comercios asumiendo esta responsabilidad frente a KLAP.

Para este modelo, KLAP proporcionará una Api-Key la cual será utilizada unicamente por el PSP, la cual es secreta e intransferible. Y debe ser proporcionada en cada solicitud que se realice.

La sección Consulta corresponde a las transacciones solicitadas por el PSP para consultar por el estado de una transacción.