Índice

1. ¿Qué necesito?
2. Proceso de Integración con Fiserv
3. Arquitectura básica
4. Construcción de Peticiones HTTP
   • Requerimientos Generales
     • Generación de Mensaje Firma
     • Headers HTTP
     • Flujo 3DSecure
     • Manejo de Respuesta de Transacciones
   • Transacciones
     • Venta Directa
     • Venta MSI
     • Ventas Pre-auth y Post-auth
     • Tokenización de tarjetas
     • Generación de PaymentURL
     • Pagos Recurrentes Calendarizados
     • Recurrentes MIT (Merchant Initiated Transactions)
    

¿Qué necesito?

• Tener control sobre el código fuente del front-end para crear tus formularios de cobro y back-end para poder lanzar peticiones a nuestro Gateway. Como en este tipo de desarrollo el control del formulario donde se introducen los datos sensibles del tarjetahabiente queda del lado del comercio, es obligatorio contar, o que se encuentre en proceso de trámite, una certificación PCI por parte del equipo de desarrollo/comercio para el momento en que se quiera salir a producción.
• API KEY. Es tu clave de acceso que es otorgada por First Data al desarrollador para comunicarse con el Gateway.
• API SECRET. Es el equivalente a una contraseña. Este valor se utiliza para firmar tu mensaje y que el Gateway garantice la autenticidad de este. JAMÁS compartas esta contraseña ni la coloques en tu sitio web.
• Con motivos de seguridad, la integración que realices necesita contar con la capacidad de construir peticiones HTTP con certificado SSL (HTTPS). Opcional. Una herramienta que te permita construir peticiones HTTP como Postman para realizar tus pruebas. Contamos con un entorno preconfigurado disponible Aquí.

Volver al índice ›

Proceso de Integración con Fiserv

¡Listo, has decidido que API REST es la solución para tu comercio! A continuación, los pasos a seguir:

1. Ponte en contacto con un asesor comercial para llevar a cabo tu proceso de afiliación.
2. Vía correo electrónico recibirás tus credenciales de API, StoreID y números de tarjetas de prueba para que puedas comenzar tu desarrollo.
3. Una vez tu integración esta lista en ambiente de pruebas, da aviso para coordinar una sesión de certificación. En esta sesión te pediremos hacer unas ventas de prueba y probaremos casos de éxito y rechazo en donde te pediremos que:
   1. Se muestre el monto correcto al tarjetahabiente
   2. Se muestre el orderId asociado a la transacción. Esto es para temas de soporte, ya que de esta manera para cualquier aclaración será mucho más sencillo encontrar la transacción en nuestro sistema, y brindarte un mejor servicio.
   3. En caso de rechazo un manejo correcto del error.
4. Cuando tu comercio se haya certificado de forma correcta entonces se te liberarán tus credenciales productivas con credenciales de API y StoreID nuevos.

Volver al índice ›

Arquitectura básica

La integración con REST API sugiere utilizar una arquitectura MVC (Modelo-Vista-Controlador). Es importante construir las peticiones HTTP utilizando un lenguaje de servidor como PHP en el controlador de la vista y no hacerlas desde el frontend, ya que esto se considera como una práctica insegura.

El proceso general para realizar una petición HTTP siguiendo MVC dentro de un sitio web consiste en:

1. Colocar el formulario para que el cliente ingrese los datos de su medio de pago y parámetros adicionales.
2. Enviar el formulario de pago hacia el controlador en donde se construirá la petición HTTP por medio de un POST (puede realizarse a través de JQuery y una petición Ajax).
3. Cuando el controlador recibe la petición, se deben realizar las validaciones que se consideren necesarias. Una vez se haya depurado la información, construir la petición HTTP de acuerdo con la transacción que se está realizando hacia el API de Fiserv.
4. Capturar la respuesta del API REST.
5. Una vez capturada la respuesta, puedes devolverla a tu vista a través de la respuesta en la petición Ajax que realizaste. De esta forma es posible construir una notificación de éxito/fracaso y mostrarla al usuario.

Volver al índice ›

Construcción de Peticiones HTTP

A continuación, la guía sobre cómo construir las peticiones HTTP para interactuar con nuestra API. Te recordamos que contamos con un entorno preconfigurado disponible Aquí.

Headers HTTP

Para realizar cualquier transacción deberemos incluir los siguientes Headers en nuestra petición HTTP de la siguiente forma:

Volver al índice ›

Generación de Mensaje-Firma

Para cada una de las solicitudes HTTP que enviemos es necesario generar un Hash (Message-Signature) que utiliza nuestro servidor para validar la autenticidad e integridad del mensaje. Este hash es enviado en el header dentro de la petición HTTP como Message-Signature. Detalles

Algoritmo: HMAC SHA256

Encoding: Base64

Firmado con: "API SECRET" provista al comercio por parte de fiserv

Paso 1 - Generar una cadena de texto con la siguiente estructura  msgSignatureString =   API_KEY + CLIENT_REQUEST_ID + TIMESTAMP + PAYLOAD.

En donde:

• API_KEY: Es la clave de acceso a la API provista por fiserv. Ejemplo: tOqWgOZAFq6aAYpqyQtAGVkjfo2Qp3lUxd
• CLIENT_REQUEST_ID: Es un identificador único para cada transacción. Se recomienda utilizar el formato UUIDv4 universally unique identifier (UUID) de 128 bits hay diferentes librerías dependiendo el lenguaje de programación que utilicemos que nos podrían ayudar con esta tarea.
• TIMESTAMP: Valor correspondiente al número de milisegundos transcurridos desde el 01/01/1970 hasta el instante en que se está realizando la petición. También se le conoce como Epoch time. Ejemplo: 1650590066714
• PAYLOAD: Cuerpo/Body de la solicitud, el cual irá cambiando según el tipo de solicitud. En caso de que el Payload sea nulo, se debe considerar como una cadena vacía. El payload deberá ser serializado sin espacios en blanco ni saltos de línea como se muestra a continuación.

Paso 2 - Firmar la cadena resultante usando el algoritmo HMAC SHA256 y utilizando como llave tu API SECRET.

Paso 3 - Obtener la representación en base64 de la cadena resultante del paso anterior. El resultado de esto es lo que incluiremos como valor en el header Message-Signature de nuestra petición.

Volver al índice ›

Flujo 3DSecure

3D Secure es la nueva forma de autenticar pagos desarrollada por las marcas que posibilita la realización de compras seguras en Internet y autentifica al comprador como legítimo titular de la tarjeta que se está utilizando.

De esta manera se garantiza la total seguridad en las transacciones.

Existen algunas peticiones que no necesitan pasar por este flujo, como lo son: las transacciones recurrentes MIT (Merchant Initiated Transactions), generación de tokens, generación de paymentURL y postautorizaciones.

Sin embargo, la MAYORÍA de las transacciones que realicemos por default necesitan pasar por el flujo de 3DSecure en nuestras tiendas, por ejemplo: ventas directas, ventas a MSI, ventas con token, recurrencias programadas, preautorizaciones, etc. Es decir, todas las transacciones con los siguientes requestType, pasan por 3DS.

• PaymentCardPreAuthTransaction (preautorizaciones con tarjeta)
  
• PaymentCardSaleTransaction  (ventas con tarjeta)
• PaymentTokenPreAuthTransaction (preautorizaciones con token)
• PaymentTokenSaleTransaction (ventas con token)

Por ello es importante que comprendamos el flujo de las transacciones con 3Dsecure. A continuación, el diagrama de un flujo de autenticación 3DS. Para mayor información, ver la narrativa de cada uno de los procesos según el número informado sobre la figura.

Volver al índice ›

Transacción Primaria

1. Primary Transaction se refiere a la transacción inicial donde, dentro del payload podremos encontrar el tipo de operativa que se quiere realizar (venta directa, venta msi, etc.) y la información del tarjetahabiente. Esta petición inicial siempre deberá incluir el objeto authenticationRequest y deberá contener los siguientes parámetros:

Es recomendable proporcionar los datos de facturación y envío dentro de la transacción para reducir el riesgo de rechazos por autenticación. Para realizar esto, asegúrate de proporcionar los datos dentro de tu petición de venta.

El siguiente JSON representa una transacción de venta con los requerimientos mínimos:

Agregar iframe

2. En este paso debemos validar si la respuesta del Gateway contiene el elemento ‘3DSMethod’. No todos los emisores soportan la recolección de datos usando el formulario de 3DSMethod. Este elemento contiene un iframe que deberás incrustar en tu sitio; este no presenta ninguna interfaz gráfica y su única funcionalidad es recolectar información del usuario, ayudando a identificar potenciales transacciones fraudulentas. En caso contrario, continuaremos con el flujo con lo que se indica en el paso 6.

A continuación, se muestra un JSON de respuesta con este formato:

Validar Datos de Sesión 3DS

2.  Una vez hayamos incrustado el iframe y se haya mandado el formulario html indicado en la respuesta anterior, debemos validar si recibimos datos de sesión para 3ds dentro de nuestra methodNotificationURL.

Confirmar datos de sesión 3DS

3.  Si recibiste la notificación con los datos de sesión de 3DS dentro de los primeros 10 segundos a la url definida en tu methodNotificationURL.

URL: https://cert.api.firstdata.com/gateway/v2/payments/{ipgTransactionId} (donde el ipgTransactionId lo obtendremos de la respuesta previa).

Payload:

NOTA: El campo storeId no es mandatorio. 

5.  Si no se obtiene un iframe de respuesta en un lapso de 10 segundos, en estos escenarios no se enviará ninguna información a methodNotificationURL y el flujo deberá continuar enviando el estatus.

EXPECTED_BUT_NOT_RECEIVED

Esto se realiza enviando una petición PATCH con la siguiente información:

URL: https://cert.api.firstdata.com/gateway/v2/payments/{ipgTransactionId} (donde el ipgTransactionId lo obtendremos de la respuesta previa).

Payload:

NOTA: El campo storeId no es mandatorio.

Validar el tipo de flujo 3DS

6.      Una vez se haya concluido este flujo el sistema determinará el flujo de 3DS para la transacción. Cuando una transacción es considerada de bajo riesgo, es aplicado el flujo Frictionless o sin fricción. En este caso, el Gateway procederá a autorizar la transacción sin algún input adicional por parte del tarjetahabiente pasando directamente al paso 10, caso contrario seguiremos al paso 7.

Challenge Request

7.     Cuando se completa el llamado al API y el sistema detecta que se trata de un flujo con Challenge, la transacción no es autorizada de forma inmediata. En su lugar, obtendrás el estatus WAITING y los parámetros para redirigir al tarjetahabiente con el Directory Server del emisor para poder autenticar la operación:

El campo authenticationResponse contendrá la siguiente información:

Deberás implementar un formulario html que se envíe automáticamente dentro de tu sitio web con la información provista.

Proceso de Challenge

8. Una vez enviado el POST, el comprador será redirigido a la pantalla de autenticación 3DS en donde, dependiendo de las reglas de su emisor, se autenticará mediante el mecanismo que el banco utilice, por ejemplo: ingresar token o clave.

Confirmación de Challenge Response

9. Cuando se ingresa la clave correcta, el comprador será redirigido a la URL que definimos como "termURL" en el paso 1, junto con las siguientes parámetros POST

Completar la transacción: deberás construir una petición PATCH para confirmar los resultados de la autenticación al Gateway. Los componentes para enviar dentro de la petición son los siguientes:

URL: https://cert.api.firstdata.com/gateway/v2/payments/{ipgTransactionId}. Donde el ipgTransactionId lo obtendremos de la respuesta previa.

La respuesta a esta petición deberá contener el resultado final de la autenticación:

Volver al índice ›

Mapeo de Respuestas

10.     Mapeamos de manera correcta nuestra respuesta según la sección de Manejo de Respuestas informada en este manual.

Volver al índice ›

Transacciones

Venta Directa

En el caso de una venta directa utilizaremos el siguiente formato de Payload/Body en nuestra request.

Esta petición consta de cuatro objetos necesarios estos se detallan a continuación:

Petición Venta Directa

Volver al índice ›

Venta MSI

Para una venta a meses sin intereses, será igual a una Venta Directa, solo agregaremos el objeto “order” al Payload.

Volver al índice ›

Ventas Pre-Auth y Post-Auth

Para una venta pre-auth será igual a una Venta Directa solo, que en esta ocasión, el requestType será “PaymentCardPreAuthTransaction”.

Para el proceso de post-auth simplemente debemos apuntar a el Endpoint: https://cert.api.firstdata.com/gateway/v2/payments/84533163643

*se debe sustituir 84533163643 por el valor devuelto en ipgTransactionId de la respuesta exitosa de la Pre-Auth que vamos a autorizar.

Payload:

Volver al índice ›

Tokenización de tarjetas

Para utilizar el token debemos seguir el siguiente esquema

Volver al índice ›

Generación de Payment URL

Volver al índice ›

Pagos recurrentes calendarizados

Estos se caracterizan por ser iniciados por el cliente y por tener un número finito de cobros a efectuar. Es decir, los cobros dejarán de aplicarse una vez se termine el tiempo especificado.

En el caso de una venta con pagos recurrentes calendarizados será igual que una venta directa pero modificaremos el requestType:PaymentMethodPaymentSchedulesRequest y agregaremos los objetos startDate, frequency,purchaseOrderNumber ([string] número de contrato) y numberOfPayments.

Volver al índice ›

Recurrentes MIT (Merchant Initiated Transactions)

Estos se caracterizan por ser iniciados por el comercio y funcionan como una suscripción. Es decir, se continuarán efectuando los cobros hasta que el cliente explícitamente cancele el servicio.

Los cargos recurrentes iniciados por el comercio (MIT) son cobros efectuados de forma frecuente al tarjetahabiente y permiten variar el monto de cada cobro. Nuestra API permite este tipo de transacciones especificando el tipo de transacción recurrente "recurringType" FIRST (para la transacción inicial) y REPEAT (para transacciones subsecuentes).

Nota. Todas las transacciones recurrentes requieren "purchaseOrderNumber" para que sean procesadas correctamente.

Payload

Transacción Subsecuente

Volver al índice ›