ipg rest – manual de integración
TRANSCRIPT
1
IPG Rest – Manual de integración
El presente documento está dirigido a los desarrolladores que desean integrarse con la
solución IPG de fiserv para procesar pagos en sistemas de e-commerce y utilizando la
opción Rest API. Para su total comprensión e interpretación se requieren conocimientos
intermedios – avanzados sobre el consumo de servicios web Restful. Así mismo, es
importante que el desarrollador conozca por completo el lenguaje de programación que
utilizará para implementar su solución.
El objetivo principal de este documento es guiar al desarrollador para la configuración de
un entorno de pruebas (Sandbox) donde pueda probar las operaciones que ofrece IPG en
su opción Rest API.
2
Contenido 1. Introducción .................................................................................................................................... 3
2. Flujo de integración ......................................................................................................................... 3
3. Primeros Pasos ................................................................................................................................ 3
4. Estructura de las solicitudes HTTP .................................................................................................. 4
5. Configuración del entorno de pruebas ........................................................................................... 5
6. Definición de los endpoints ............................................................................................................. 9
6.1 Transacciones de venta ............................................................................................................. 9
6.1.1 Transacciones primarias (Sale, Pre-Auth y Credit) ............................................................. 9
6.1.2 Consultar el estado de una transacción u orden ............................................................. 10
6.1.3 Transacciones secundarias (Void, Post-Auth y Return) ................................................... 10
6.2 Cargos recurrentes (Payment Schedules) ............................................................................... 11
6.2.1 Creación de payment schedule ........................................................................................ 11
6.2.2 Consulta de payment schedule ........................................................................................ 11
6.2.3 Cancelación de un payment schedule .............................................................................. 11
6.2.4 Actualización de payment schedule ................................................................................. 11
6.3 Payment URL ........................................................................................................................... 12
6.4 Payment tokens (Data Vault) .................................................................................................. 12
7. Flujo de integración con 3D Secure ............................................................................................... 13
7.1 Ejemplo de transacción autenticada con 3DS ..................................................................... 14
7.2 Autenticación ...................................................................................................................... 16
7.3 Finalizar una transacción autenticada con 3DS ................................................................... 17
8. Buenas prácticas y anotaciones técnicas ...................................................................................... 17
Apéndices .......................................................................................................................................... 19
Apéndice I. Estructura de objetos JSON. ....................................................................................... 19
Apéndice II. Generación de Message-signature............................................................................ 20
3
1. Introducción
IPG es la solución de fiserv que te permite procesar transacciones desde un sitio web a
través de un canal seguro y se adapta a las necesidades del comercio para realizar
operaciones bancarias como pagos, devoluciones, cancelaciones, pre-autorizaciones y
post-autorizaciones; así como consultar el estatus de las transacciones, generación de
Payment URL y completa personalización de la experiencia al comprador.
IPG Rest API ofrece un conjunto de herramientas que permiten realizar pagos a través de
la definición de un Servicio Web. A diferencia de la solución Connect, la opción Rest API
permite a los desarrolladores definir por su cuenta el flujo de operación y cobro de las
transacciones, así como completa personalización de los formularios para capturar la
información de los tarjetahabientes. Adicionalmente, se puede integrar a cualquier tipo de
aplicación web gracias a que la comunicación consiste en el intercambio de mensajes
(solicitudes HTTP) desde la aplicación al servidor de IPG.
La integración por Rest API está orientada a un desarrollo más robusto que requiera
funcionalidades superiores a la opción Connect, requiere un equipo de desarrollo más
especializado, pero permite que el aplicativo desarrollado sea escalable y tener control
completo del flujo transaccional.
2. Flujo de integración
El proceso de comunicación entre el Gateway de IPG y tu aplicación se realiza a través de
la construcción de peticiones HTTP. Estas peticiones son enviadas y procesadas por el
servidor de IPG, posteriormente se genera una respuesta que tu aplicación debe capturar
e interpretar para mostrar el resultado o continuar procesando.
La respuesta puede ser recibida en tu propio servidor a través de una URL que permita el
método POST.
Una vez obtenida la respuesta, es responsabilidad de la lógica del negocio y del comercio
definir qué desea realizar con ella; algunos ejemplos van desde almacenar en su propia
base de datos, enviar correos electrónicos/mensajes de texto de confirmación, o
simplemente mostrar un cuadro de dialogo con el resultado de la operación.
3. Primeros Pasos
Para comenzar la integración con la Rest API, asegúrate de contar con la siguiente
información:
• API Key. Es una clave que identifica al comercio y proporciona permiso para
procesar las transacciones dentro del servidor.
4
• API Secret. Es el equivalente a una contraseña PRIVADA y no debe ser compartida
con nadie, se utiliza en conjunto con API Key para autenticarte cada que envías una
solicitud HTTP.
• Archivo postman_environment.json. Es la definición de tu entorno personalizado
para realizar pruebas.
• Archivo postman_collection.json. Es una colección de solicitudes HTTP
preconstruidas que contienen transacciones de ejemplo para probar la API.
4. Estructura de las solicitudes HTTP
Una solicitud HTTP es un mensaje que cuenta con una estructura y está compuesta por
diversas partes descritas a continuación:
• Endpoint: es un recurso que vive en un servidor web, este recurso puede ser
consultado desde una aplicación cliente que lo solicite y devuelve una respuesta.
Su estructura es la de una URL, por ejemplo:
https://webserver.com/getOrders?param1=value1¶m2=value2...¶mn=valuen
El endpoint anterior corresponde al recurso getOrders que vive en el servidor que
es accesible a través de la URL https://webserver.com.
Es posible enviar parámetros adicionales que complementen la solicitud.
• Método: especifica la operación que realiza el endpoint que estamos consultado y
puede tomar los siguientes valores:
GET: Obtener información.
POST: Enviar información.
DELETE: Borrar un recurso.
PATCH: Actualizar un recurso existente.
Además de estos métodos existen algunos otros, sin embargo, no son utilizados
por IPG Rest API.
• Cuerpo/Payload: Es el contenido o información que estamos enviando dentro de
nuestra solicitud HTTP. Este elemento únicamente existe para las peticiones con
método POST, PATCH. IPG Rest API permite únicamente objetos JSON dentro del
cuerpo de la solicitud, para más información sobre su estructura consulta el
Apéndice I.
• Encabezados: los encabezados especifican al servidor el tipo de mensaje que
estamos enviando, el contenido, los parámetros de autenticación, tamaño del
mensaje, etc. La finalidad de los encabezados es indicar al servidor cómo debe
interpretar la solicitud. En el caso de IPG Rest API se requieren los siguientes
encabezados para todas las peticiones que envíe tu aplicación.
5
Encabezado Valor
Content-Type application/json
Api-Key El valor de tu API Key
Client-Request-Id Identificador único para cada solicitud. Se sugiere utilizar el estándar UUID de 128 bits. Ej. ED280816-E404-444A-A2D9-FFD2D171F928
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. Ej. 1582828266
Message-Signature Es un hash generado con los datos que estamos enviando. Se utiliza para que el servidor garantice la autenticidad de la solicitud HTTP.
La definición completa de la API la puedes consultar en el sitio para desarrolladores de
fiserv México. https://docs.firstdata.com/org/fdmexico/docs/api
5. Configuración del entorno de pruebas
Con la finalidad de que realices todas las pruebas necesarias para poder ejecutar y probar
las es necesario que cuentes con la herramienta Postman, esta herramienta te permite
construir y enviar peticiones HTTP, así como recibir la respuesta desde el servidor que
consultemos. A continuación, se describe el procedimiento de instalación y configuración
de la herramienta.
1. Descarga Postman de forma gratuita, disponible en el siguiente enlace:
https://www.postman.com/downloads/. Se sugiere utilizar la versión 7.18.0 o
superior, ya que para el desarrollo de este documento se utilizó esa versión base.
2. Instala la herramienta en tu computadora.
3. La primera ocasión que ejecutamos la herramienta se presentará una pantalla de
inicio de sesión. En caso de no contar con una cuenta registrada en Postman,
selecciona la opción enmarcada en la siguiente imagen.
6
4. Dentro de la pantalla principal de Postman tendrás que importar la colección y el
entorno de pruebas correspondiente a las pruebas preconstruidas para verificar el
funcionamiento correcto de la API. Para ello, presiona el botón “Importar/Import”
ubicado en la parte superior izquierda.
5. En la ventana emergente selecciona el botón “Choose Files” y selecciona los
archivos de la colección y entorno a cargar. El nombre de estos archivos termina
con “.postman_collection.json” y “.postman_environment.json”
respectivamente. Puedes seleccionar ambos archivos al mismo tiempo.
7
6. Para verificar que la colección y el entorno se hayan cargado correctamente revisa
lo siguiente:
a. La colección con nombre “IPG REST API – Test Collection” se
encuentra en la pestaña “Colecciones/Collections” en el panel lateral
izquierdo de la aplicación.
b. En la parte superior derecha de la aplicación encontrarás una lista
desplegable en donde se encuentran los entornos cargados en la
herramienta. Selecciona el entorno de pruebas correspondiente al
entorno de pruebas de IPG. Tendrá una apariencia similar a la siguiente.
8
7. Modifica tus credenciales (ApiKey y ApiSecret) proporcionadas por fiserv.
a. Presiona el engrane ubicado en la parte derecha donde se muestra el
entorno seleccionado.
b. Presiona en el nombre del entorno de pruebas, llena con tus
credenciales las variables “api_key” y “api_secret” de la tabla que se
muestra.
c. Presiona el botón “Actualizar/Update”.
d. Cierra la ventana emergente.
8. Ejecuta la solicitud de prueba (request) con nombre “API TEST” seleccionándola
y presionando el botón “Enviar/Send”. Es muy importante que utilices la colección
proporcionada, ya que contiene scripts de código que permiten construir cada una
de las peticiones automáticamente de acuerdo con la estructura definida en la
documentación de la API. Deberás obtener una respuesta como la que se muestra
a continuación.
9
9. Si el resultado es similar al anterior y el “Status Code” de la respuesta HTTP es igual
a 200, puedes ejecutar cualquier solicitud HTTP de la colección.
6. Definición de los endpoints
En el entorno de pruebas todas las peticiones deberán apuntar a la siguiente URL:
https://cert.api.firstdata.com/gateway/v2
Cuando termines de realizar tus pruebas se ter proporcionará acceso a un entorno
productivo que deberá apuntar a una URL de producción.
Para consultar la estructura de los payload a enviar o recibir para cada uno de los endpoint,
visita la sección “Schemas” del sitio https://docs.firstdata.com/org/fdmexico/docs/api .
6.1 Transacciones de venta 6.1.1 Transacciones primarias (Sale, Pre-Auth y Credit)
Transacciones primarias
Nombre de la transacción (Payload) Descripción
PaymentCardSaleTransaction Realiza una venta directa utilizando los datos de una tarjeta de crédito/débito.
PaymentCardCreditTransaction Realiza la operación de otorgar un crédito a la tarjeta de crédito/débito que enviemos.
PaymentCardPreAuthTransaction
Aparta los fondos de la tarjeta enviada y los retiene hasta que se realiza la operación Post-Auth correspondiente.
PaymentTokenSaleTransaction
Realiza una venta directa utilizando un token almacenado en Data Vault.
PaymentTokenCreditTransaction
Realiza la operación de otorgar un crédito a la tarjeta asociada con el token enviado.
10
PaymentTokenPreAuthTransaction
Aparta los fondos de la tarjeta asociada al token enviado y los retiene hasta que se realiza la operación Post-Auth correspondiente.
6.1.2 Consultar el estado de una transacción u orden
Endpoint utilizado para consultar el estatus de alguna transacción efectuada, ya sea
primaria o secundaria. No requiere payload y se envía el identificador de la transacción u
orden a consultar en la URL. Se recibe un Payload de tipo TransactionResponse u
OrderResponse respectivamente a la respuesta.
6.1.3 Transacciones secundarias (Void, Post-Auth y Return)
Para efectuar este tipo de transacciones se requiere haber ejecutado previamente una
transacción primaria y saber su Id de transacción u orden. La transacción realicemos tendrá
efecto sobre la transacción u orden con Id enviado en la URL.
Transacciones secundarias
Nombre de la transacción (Payload) Descripción
VoidTransaction Cancela una transacción primaria.
PostAuthTransaction Efectúa la Post-Auth a una transacción de tipo Pre-Auth. Retira los fondos del tarjetahabiente.
ReturnTransaction
Devuelve efectivo al medio de pago utilizado en una transacción primaria.
11
6.2 Cargos recurrentes (Payment Schedules) 6.2.1 Creación de payment schedule
Nombre de la transacción (Payload) Descripción
PaymentMethodPaymentSchedulesRequest Crea un cargo recurrente usando datos de tarjeta de crédito/débito.
ReferencedOrderPaymentSchedulesRequest Crea un cargo recurrente para una orden previamente enviada usando su medio de pago enviado.
6.2.2 Consulta de payment schedule
Consulta un Schedule creado con anterioridad utilizando el identificador de orden que
enviamos en la URL. La respuesta es de tipo RecurringPaymentDetailsResponse.
6.2.3 Cancelación de un payment schedule
Cancela un cargo recurrente definido en el payment Schedule con el identificador de orden
enviado en la URL.
6.2.4 Actualización de payment schedule
En caso de requerir actualizar un cargo recurrente existente, se necesita enviar el
identificador de orden en la URL y actualizar los datos necesarios en el Payload que
enviamos. La respuesta obtenida es TransactionResponse.
Nombre de la transacción (Payload) Descripción
PaymentMethodPaymentSchedulesRequest Crea un cargo recurrente usando datos de tarjeta de crédito/débito.
ReferencedOrderPaymentSchedulesRequest Crea un cargo recurrente para una orden previamente enviada usando su medio de pago enviado.
12
6.3 Payment URL
La Rest API de IPG permite generar URLs de pago de un solo uso que pueden ser
distribuidas por un canal externo. Estas URL son generadas de forma dinámica y permiten
al comercio distribuirlas a través de un canal externo como email, mensajes de texto,
WhatsApp, etc. a sus clientes. La respuesta es un objeto JSON de tipo
PaymentUrlResponse.
Payment URL
Nombre de la transacción (Payload) Descripción
PaymentUrlRequest Crea una URL de un solo uso para concluir una venta.
6.4 Payment tokens (Data Vault)
Data Vault es un servicio que te permite generar Tokens asociados a medios de pago
empleados previamente, estos tokens permanecen almacenados en el servidor de IPG y
puedes usarlos para realizar transacciones primarias sin necesidad de solicitar al
comprador todos los datos de su tarjeta en cada transacción.
Payment tokens
Nombre de la transacción (Payload) Descripción PaymentCardPaymentTokenizationRequest Crea un token de pago en el servidor de IPG
asociándolo a tu tienda. Se envían los datos de la tarjeta de crédito/débito.
ReferencedOrderPaymentTokenizationRequest Crea un token de pago en el servidor de IPG asociándolo a tu tienda. Se utiliza el medio de pago enviado con la orden referenciada.
13
7. Flujo de integración con 3D Secure
La definición de la API permite autenticar transacciones utilizando el esquema de 3DS 2.1
para evitar fraudes y contra cargos por parte del tarjetahabiente. A diferencia de nuestras
otras soluciones, para autenticar una transacción es necesario adjuntar un objeto de
nombre “authenticationRequest” a un Payload de transacciones primarias (véase la
sección 6.1.1 Transacciones primarias.
Authentication Request (3DS 2.1)
Parámetro Descripción Valor
authenticationType Define el tipo de autenticación que solicitaremos
Secure3D21AuthenticationRequest
termURL Url del comercio donde se recibirá la respuesta a la autenticación
Ejemplo: https://micomercio.com/finalize3ds.php
methodNotificationURL Url en el servidor del comercio en donde se recibe el resultado de la transacción
Ejemplo: https://micomercio-server.com/notification.php
challengeIndicator Indica la preferencia para solicitar contraseña 3DS
01 – Sin preferencia 02 – No solicitar contraseña
03 – Preferir solicitar contraseña 04 - Obligatorio
14
7.1 Ejemplo de transacción autenticada con 3DS
{
"transactionAmount": {
"total": "1.00",
"currency": "MXN"
},
"requestType": "PaymentCardSaleTransaction",
"paymentMethod": {
"paymentCard": {
"number": "5579220000000012",
"securityCode": "123",
"expiryDate": {
"month": "12",
"year": "22"
}
}
},
"authenticationRequest": {
"authenticationType": "Secure3D21AuthenticationRequest",
"termURL": "http://localhost/3DS/finalize.php",
"methodNotificationURL": "https://micomercio.com/logs/notification.php",
"challengeIndicator": "03"
}
}
El payload del ejemplo anterior pertenece a una transacción de venta autenticada con
3DS. La respuesta obtenida por parte de IPG deberá ser similar a la siguiente:
15
{
"clientRequestId": "91e98916-c5f0-4520-93b3-d520e635fc30",
"apiTraceId": "rrt-0657cd7557d7d3602-b-ea-21046-17325498-1",
"ipgTransactionId": "84531462889",
"orderId": "R-6fd2afaf-d16a-40bd-a579-80be51f840a9",
"transactionType": "SALE",
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2022"
},
"bin": "557922",
"last4": "0012",
"brand": "MASTERCARD"
},
"paymentMethodType": "PAYMENT_CARD"
},
"country": "Mexico",
"transactionTime": 1583257456,
"authenticationResponse": {
"type": "3D_SECURE",
"version": "1.0",
"params": {
"payerAuthenticationRequest": "eJxVUttuwjAM/ZWK9zZJKVCQiQRD00ACFZimaW
8hdaGMpqWXwfb1S0o7mF/ic+w49nHg9ZAjzrYoqxw5LLEoxB6tOBx3gs16Y/ej0BWRiOyQ9YXt0V1oi95
gaPt0hz0W+R4Vww6HYLLBM4cvzIs4VZw51HGBtFCXzeVBqJKDkOfpfMV7tQFpICSYz2ec3Q3IjQIlEuSr
WH5a64m1lWkZiyDdAql5kGmlyvybe74HpAVQ5Sd+KMusGBFyuVycTOzTIlWnWKGTXIGYOJB7U0FlvELXu
8YhRxI8V9GyeCeLadL1s2PZPb8tPuKf43IMxGRAKErkLnUp7dKuxQYjzxuxPpCaB5GYRjijVA948yEzT0
weAo8EaPFzVLKdo0WA1yxVqDO0mH8+hFhI3X9z3Jt/ejH6ylLL5ruM+gOfGYVrwpSKtTauy261DABirpB
meaRZvvb+fYpfztmzWQ==",
"termURL": "http://localhost/3DS/finalize.php",
"merchantData": "MD___________100202003031744162484e/PFufMsX/JBm38pjt
3qVJZizjM=_____555555_____________11111111111______R-6fd2afaf-d16a-40bd-
a5790ww__________________________________________________________________________
_______________return-
url?_____________________________________________________________________________
__________VRQR-6fd2afaf-d16a-40bd-a579-80be51f840a999e3af",
"acsURL": "https://3ds-acs.test.modirum.com/mdpayacs/pareq"
}
}
}
16
7.2 Autenticación
El objeto authenticationResponse contiene la información necesaria para autenticar la
transacción. El siguiente paso es enviar los valores que contiene “merchantData”,
“payerAuthenticationRequest” y “termURL” como parámetros POST hacia la URL
recibida en “acsURL”. Una vez realizado el POST, el cliente será redireccionado a la página
de autenticación correspondiente de su banco emisor en donde se le solicitará ingrese su
contraseña de 3D Secure.
Una vez autenticados con 3DS, ocurrirá una redirección hacia la URL especificada en el
parámetro “termURL” junto con esta redirección viajan dos parámetros POST codificados
que contienen la respuesta de la autenticación con la que podrémos concluir la transacción
inicial del ejemplo. Estos dos parámetros tienen por nombre “PaRes” y “MD”.
17
7.3 Finalizar una transacción autenticada con 3DS
Se deberá enviar una solicitud HTTP con el siguiente Payload y especificando el ID de la
transacción original en la URL. Esto confirmará la operación y se realizará el cobro
correspondiente a la operación. La respuesta final será de tipo TransactionResponse
Parámetro Descripción Valor
authenticationType Tipo de autenticación utilizada
Secure3D10AuthenticationUpdateRequest
payerAuthenticationResponse Respuesta de la autenticación
Valor recibido en PaRes
merchantData Valor recibido en “MD”
8. Buenas prácticas y anotaciones técnicas
1. Asegúrate de almacenar en un lugar seguro tus credenciales (API Key y API
Secret). Es muy importante conservar estos datos protegidos y que no sean
accesibles desde un navegador.
Sugerencia:
Puedes guardar estas credenciales en una base de datos definiendo un único
usuario y que solamente sea accesible desde host autorizados; también puedes
crear un archivo de configuración en un directorio NO PÚBLICO, de esta manera
únicamente tu sabrás la ubicación del archivo y no tendrán acceso a personas no
autorizadas.
2. En caso de utilizar código JavaScript en tu sitio, evita cualquier tipo de log en un
entorno productivo, ya que imprimir mensajes pueden servir de guía a un agente no
autorizado para modificar de manera local el archivo JavaScript.
3. Evita almacenar cualquier dato sensible de tus usuarios o credenciales en variables
de JavaScript.
4. Cualquier proceso que involucre la consulta de información como credenciales o
datos sensibles deberá realizarse en un lenguaje ejecutado del lado del servidor
como PHP o ASP.NET. Jamás consultes tu base de datos directamente desde
código JavaScript.
Sugerencia
Si en realidad necesitas realizar una consulta a una base de datos, puedes crear un
archivo auxiliar PHP o ASP.NET y enviar una petición Ajax desde JavaScript.
Gracias a que este archivo es ejecutado por el servidor, puedes construir en él, la
18
conexión con la BD y de esta forma devolver el resultado de la consulta a tu archivo
JavaScript original. No olvides limitar la conexión de tu archivo auxiliar para que solo
permita peticiones desde el host donde se encuentra el mismo sitio web.
5. Como medida de seguridad adicional, evita permitir el listado de directorios desde
tu hosting. Muchos proveedores de hosting tienen esta opción habilitada de manera
predeterminada. De esta forma evitas la descarga del código fuente de tus archivos.
6. Para reducir las transacciones no reconocidas o fraudulentas se sugiere utilizar
siempre la autenticación con 3D Secure.
7. Si el proceso de tu sitio web lo permite, se sugiere autenticar y tener un registro de
todos los usuarios que lo utilizan.
8. Para evitar transacciones duplicadas, es importante incluir el parámetro “orderId”
definido dentro del objeto “Order” para las transacciones primarias.
19
Apéndices
Apéndice I. Estructura de objetos JSON.
La estructura base de un objeto JSON es la siguiente:
{
“key1”:”value1”,
“key2”:”value2”,
.
.
.
“keyN”:”valueN”
}
Todas las claves (key) son una cadena de texto que identifica al valor que mandamos
como “value”. Los valores posibles que se pueden enviar son numéricos, cadenas de
texto (solo estos se colocan entre comillas), booleanos, otros objetos JSON y arreglos de
objetos JSON.
Ejemplo.
{
"merchantName":"fiserv Mexico",
"merchantAddress":{
"street":"Jaime Balmes",
"streetNumber":"11D",
"country": "Mexico"
},
"contact":[
{
"id":1,
"name":"main",
"type": "phone",
"value":"55 1102 0600"
},
{
"id":2,
"name":"main email",
"type":"email",
"value":"[email protected]"
}
]
}
20
Apéndice II. Generación de Message-signature
Para generar el header Message-signature que se requiere enviar en cada una de las
peticiones HTTP que enviamos al servidor de IPG se deben considerar el siguiente
procedimiento.
Algoritmo: HMAC Sha256
Encoding: Base64
Firmado con: API Secret
1. Generar una cadena de texto con la siguiente estructura:
API_KEY + CLIENT_REQUEST_ID + TIMESTAMP + PAYLOAD
2. Utilizar el algoritmo HMAC Sha256 para firmar la cadena anterior utilizando tu API
SECRET.
3. Convertir en base 64 la cadena obtenida luego de aplicar el algoritmo HMAC
Sha256.
Nota: el PAYLOAD se debe enviar como una cadena removiendo todos los espacios y
saltos de línea, por ejemplo:
Payload Original Payload enviado
{ “name”:”Fiserv”, “location”: “Jaime Balmes 11D” }
{“name”:”Fiserv”,“location”:“Jaime Balmes 11D”}