Para garantizar la seguridad y la integridad de las operaciones que realices, todas las operaciones que envíes a tu TPV Virtual deben ir correctamente firmadas. Así, te aseguras que ninguna comunicación ha sido alterada durante el trascurso del mensaje desde tu servidor hasta Redsýs.
El proceso de firma es muy sencillo y es independiente de cada tipo de operación, por lo que el proceso que debes seguir para realizar el firmado es siempre el mismo. Para calcular la firma es necesario utilizar una clave específica para cada terminal. Esta clave se puede obtener accediendo al Portal de Administración del TPV Virtual, donde deberás acceder a la opción «Consulta datos del Comercio». En el listado de terminales, encontrarás el icono de una llave: clicando en él accederás a una ventana emergente que mostrará tu clave del terminal.
Otra forma de acceder es, dentro de la configuración del propio terminal, pulsando el botón «Ver clave de firma» situado en la parte superior de la página.
Nota importante
Debes almacenar esta clave en tu servidor de la manera más segura posible para evitar un uso fraudulento de la misma. Eres la única persona responsable de la adecuada custodia y mantenimiento en secreto de dicha clave. Si en algún momento crees que tu clave ha podido estar comprometida, ponte en contacto con tu entidad bancaria inmediatamente.
Proceso de firma de la operación
Una vez se tiene montada la cadena de datos que vas a firmar (normalmente será el campo Ds_MerchantParameters) y la clave específica del terminal, se debe calcular la firma siguiendo los pasos que se detallan a continuación. Vamos a usar como ejemplo la siguiente cadena de datos:
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiI5OTkiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjEyMzQ1Njc4OTAiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0sucGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsS08ucGhwIn0=Recuerda que los datos que vas a tener que firmar deben ya estar codificados en Base64URL, de lo contrario, la firma que obtengas va a ser errónea. Si descodificas estos datos, verás los datos de la operación que se está tratando de enviar, pero esto es irrelevante para el ejemplo salvo por el número de pedido, incluido en la petición, que es muy importante en este proceso, y en este caso es 1234567890. Firmaremos utilizando el algoritmo HMAC SHA-512.
1. Generación de la clave específica para la operación
Para obtener la clave específica de la operación, debes realizar un cifrado AES CBC, usando como vector de inicialización un vector de ceros, entre tu clave de comercio (la que has obtenido de la configuración del terminal) y el número de pedido de la operación.
Es muy importante que tengas en cuenta que la clave que uses debe tener exactamente 16 caracteres. Como es muy probable que tu clave tenga más o menos, debes pre-procesarla:
- Si la clave tiene más de 16 caracteres, cogerás los primeros 16. Para la clave estándar de pruebas sq7HjrUOBfKmC576ILgskD5srU870gJ7, será sq7HjrUOBfKmC576.
- Si la clave tiene menos de 16 caracteres, rellenarás por la derecha con ceros hasta completar los 16. Si la clave estándar de pruebas tuviera doce caracteres, rellenaríamos con cuatro ceros por la derecha, quedando sq7HjrUOBfKm0000.
En este ejemplo, vamos a tomar que la clave de prueba es la original y hemos tenido que recortarla hasta quedarnos con los 16 primeros caracteres. Hecho esto, debemos realizar un cifrado AES CBC del número de pedido con la clave que hemos tratado, y codificar en Base64 el resultado obtenido.
AES CBC requiere de un vector de inicialización (IV), que en este caso debe ser un vector de ceros. Usar un vector de ceros como IV no compromete la encriptación, ya que esto es sólo un paso accesorio. El verdadero algoritmo de firma es HMAC SHA-512.
A esto le llamamos diversificar la clave con el número de pedido, y para nuestro ejemplo con el número de pedido indicado, el resultado es RWt3/IPTzYRMXsQtkiGRKg==.
2. Cálculo del HMAC SHA-512 del parámetro a firmar
Deberás de calcular el HMAC SHA-512 del valor del parámetro que vas a firmar (en este ejemplo, el parámetro DS_MerchantParameters que contiene el string que hemos detallado más arriba) utilizando la clave que has obtenido en el paso anterior.
3. Obtención de Ds_Signature
Por último, deberás codificar el resultado del paso 2 en Base64URL, y este será tu parámetro Ds_Signature final. Para el ejemplo que nos ocupa, el resultado sería sNshBlGLKfv04FBXKt_lMaueFt_yA7VZ1Mw4USg4HiLehAdiQ8xUt5pEM-oHvXCBNZJKZkk7ogzPjhxDW3hAEQ.
Una vez completado todo el proceso, debes montar los parámetros finales. En este caso hemos firmado una petición REST de devolución, pero como hemos comentado, el proceso de firma es igual en todos los modelos de integración y tipos de operación.
Con este tipo de firma, el parámetro Ds_SignatureVersion debe enviarse con el valor HMAC_SHA512_V2.
Para nuestro ejemplo, los parámetros resultantes serían así:
{"Ds_MerchantParameters":"eyJEU19NRVJDSEFOVF9BTU9VTlQiOiI5OTkiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjEyMzQ1Njc4OTAiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0sucGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsS08ucGhwIn0=","Ds_Signature":"sNshBlGLKfv04FBXKt_lMaueFt_yA7VZ1Mw4USg4HiLehAdiQ8xUt5pEM-oHvXCBNZJKZkk7ogzPjhxDW3hAEQ","Ds_SignatureVersion":"HMAC_SHA512_V2"}Verificar la respuesta del TPV Virtual
Cuando recibas la notificación (o cualquier mensaje firmado, sea el canal que sea) desde el TPV Virtual, deberás firmar los datos recibidos y comparar la firma con la recibida desde los servicios de Redsýs para verificar que se ha mantenido la integridad del mensaje. El proceso es muy parecido al que se ha descrito anteriormente, y sólo cambia en que deberás primero obtener el número de pedido.
- Como te hemos contado anteriormente, el número de pedido juega un papel clave a la hora de firmar la operación, y lo necesitarás para poder calcular la firma de los parámetros que has recibido. Esto puedes hacerlo descodificando los parámetros que te han llegado en Base64, y obteniendo el valor del campo Ds_Order.
- Una vez tienes este valor, debes seguir exactamente el mismo proceso que se ha detallado en el proceso de firma de la operación:
- Genera la clave específica de la operación con AES CBC y codifica el resultado en Base64.
- Calcular el HMAC SHA-512 del parámetro que estas firmando con la clave obtenida: recuerda que debes firmar el parámetro en Base64 tal y como te ha llegado, sin descodificar.
- Obtén el Ds_Signature codificando en Base64URL el resultado del paso anterior.
- Cuando obtienes tu Ds_Signature, compáralo con el Ds_Signature que te ha llegado en el mensaje, y si coinciden, entonces puedes procesar dicho mensaje.
De esta manera, te asegurarás de que los mensajes que has recibido desde tu TPV Virtual no han sido alterados de ninguna manera durante la comunicación. Es muy importante que siempre verifiques las firmas de cualquier mensajería que trates antes de realizar cualquier acción (confirmar un pedido, enviar un producto, etcétera…) ya que de lo contrario, podrías comprometer toda tu operativa.
Ejemplos para el cálculo de la firma
Una manera muy sencilla de realizar la firma de los parámetros y no preocuparte por programar todo el proceso es usar nuestras bibliotecas de firma ya preparadas y probadas para que tú sólo debas preocuparte de integrarla en tu sistema. Puedes acceder a todas las bibliotecas de firma para ayudarte durante la integración en el área de descargas.
Además, recuerda que siempre estamos disponibles para ayudarte a integrar tu TPV Virtual a través de nuestros canales habituales de ayuda.