Estructura de una petición REST

 

 

Para que el comercio pueda realizar la petición a través del método “trataPeticionREST” del interfaz REST de Redsys, es necesario intercambiar una serie de datos, tanto en los mensajes de petición como en los mensajes de respuesta.

El comercio debe hacer llegar al TPV Virtual una petición POST mediante la interfaz REST. En dicha petición se enviará un JSON que incluya los siguientes parámetros:

  • Ds_SignatureVersion: Constante que indica la versión de firma que se está
  • Ds_MerchantParameters: Cadena en formato JSON con todos los parámetros de la petición codificada en Base 64 y sin retornos de carro (En la sección de anexos se incluye la lista de parámetros que se pueden enviar en una solicitud de pago).
  • Ds_Signature: Firma de los datos enviados. Es el resultado del HMAC SHA256 de la cadena JSON codificada en Base 64 enviada en el parámetro

 

NOTA: la conexión requiere del uso de un sistema de firma basado en HMAC SHA-256, que autentica entre sí al servidor del comercio y al TPV Virtual. Para desarrollar el cálculo de este tipo de firma, el comercio puede realizar el desarrollo por sí mismo utilizando las funciones estándar de los diferentes entornos de desarrollo, si bien, para facilitar los desarrollos ponemos a su disposición librerías (PHP, JAVA y .NET) cuya utilización se presenta en detalle en esta guía en los siguientes apartados y que están a su disposición en la siguiente dirección:

http://www.redsys.es/wps/portal/redsys/publica/areadeserviciosweb/descargaDeDocumentacionYEjecutables/

 

 

Identificar    la    versión   de    algoritmo    de    firma    a    utilizar (Ds_SignatureVersion)

 

En la petición se debe identificar la versión concreta de algoritmo que se está utilizando para la firma. Actualmente se utiliza el valor HMAC_SHA256_V1 para identificar la versión de todas las peticiones, por lo que este será el valor del parámetro Ds_SignatureVersion.

 

Montar la cadena de datos de la petición (Ds_MerchantParameters)

 

En la petición se deben enviar todos los parámetros necesarios para identificar el tipo de operación que se desea realizar. Todos los parámetros se montarán en formato JSON, y el nombre de cada parámetro deberá indicarse en mayúsculas o con estructura “CamelCase” (Por ejemplo: DS_MERCHANT_AMOUNT o Ds_Merchant_Amount).

A continuación, se muestran un ejemplo del objeto JSON de una petición:

{"DS_MERCHANT_AMOUNT":"145","DS_MERCHANT_ORDER":"1446068581","DS_MERCHANT_MERCHANTC ODE":"999008881","DS_MERCHANT_CURRENCY":"978","DS_MERCHANT_TRANSACTIONTYPE":"0","DS_MER
CHANT_TERMINAL":"1","DS_MERCHANT_MERCHANTURL":"http:\/\/www.prueba.com\/urlNotificacion.php"
,"DS_MERCHANT_PAN":"454881********04","DS_MERCHANT_EXPIRYDATE":"1512","DS_MERCHANT_CVV2 ":"123"}

 

Una vez montada la cadena JSON con todos los campos, es necesario codificarla en BASE64 sin retornos de carro para asegurarnos de que se mantiene constante y no es alterada en el proceso de envío.

A continuación, se muestra el objeto JSON codificado en BASE64:

eyJEU19NRVJDSEFOVF9BTU9VTlQiOiIxNDUiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjE0NDYwNjg1ODEiLCJEU1 9NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3 OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiL CJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmlj YWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfUEFOIjoiNDU0ODgxMjA0OTQwMDAwNCIsIkRTX01FUkNIQU5UX 0VYUElSWURBVEUiOiIxNTEyIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyJ9

 

La cadena resultante de la codificación en BASE64 será el valor del parámetro Ds_MerchantParameters.

 

 

Firmar los datos de la petición (Ds_Signature)

 

Para calcular la firma es necesario utilizar una clave específica para cada terminal. Se puede obtener la clave accediendo al Portal de Administración, opción Consulta datos de Comercio, en el apartado “Ver clave”, tal y como se muestra en la siguiente imagen:

 

Ver clave

 

NOTA IMPORTANTE

Esta clave debe ser almacenada en el servidor del comercio de la forma más segura posible para evitar un uso fraudulento de la misma. El comercio es responsable de la adecuada custodia y mantenimiento en secreto de dicha clave.

 

Una vez se tiene montada la cadena de datos a firmar (Ds_MerchantParameters) y la clave específica del terminal, se debe calcular la firma siguiendo los siguientes pasos:

  1. Se genera una clave específica por operación. Para obtener la clave derivada a utilizar en una operación se debe realizar un cifrado 3DES entre la clave del comercio, la cual debe ser previamente decodificada en BASE 64, y el valor del número de pedido de la operación (Ds_Merchant_Order).
  2. Se calcula el HMAC SHA256 del valor del parámetro Ds_MerchantParameters y la clave obtenida en el paso
  3. El resultado obtenido se codifica en BASE 64, y el resultado de la codificación será el valor del parámetro Ds_Signature.

 

Utilización de librerías de ayuda

 

En los apartados anteriores se ha descrito la forma de acceso al SIS utilizando la entrada REST y el sistema de firma basado en HMAC SHA256. En este apartado se explica como se utilizan las librerías disponibles en PHP, JAVA y .NET para facilitar los desarrollos y la generación de los campos del formulario de pago. El uso de las librerías suministradas por Redsys es opcional, si bien simplifican los desarrollos a realizar por el comercio.

 

Librería PHP

Librería JAVA

Librería .NET