DESARROLLADORES

Aquí encontrarás todo lo necesario para integrar nuestra pasarela de pago de forma rápida y sencilla

Selecciona la opción a consultar:

MODELOS DE INTEGRACIÓN

Conexión InSite


Introducción

El objetivo principal es el de disponer de un proceso de pago rápido, sencillo e integrado al máximo en las páginas de la tienda web, adaptado completamente al diseño del comercio online, fácil de usar y de integrar, pero a la vez que mantenga la seguridad sobre los datos de pago introducidos por el cliente, evitando que el comercio tenga que soportar costosos procesos de seguridad derivados del cumplimiento obligatorio de la normativa PCI DSS .

Facilitamos las "piezas" o campos necesarios del formulario de pago de forma que se integran uno a uno perfectamente incrustados en la página checkout de la tienda web y además cada elemento se personaliza en diseño con estilos configurables, en perfecta sintonía del diseño del resto de la página web del comercio.

La seguridad se preserva de forma que el formulario resultante con la información de pago de los clientes queda inaccesible al mismo servidor del comercio o de terceros que hayan podido comprometer el servidor web del comercio.

Ventajas de la conexión InSite

Con la solución de pago inSite el comercio o tienda online consigue una serie de ventajas que favorecen el aumento de la conversión de ventas:

  • Una experiencia de pago sencilla y satisfactoria para sus clientes, al estar totalmente integrada en las páginas web del comercio y sin saltos de navegación.

  • Mayor control del flujo de checkout y pago, ya que toda petición se realiza de forma síncrona por parte del servidor de la tienda web y sin necesidad de procesos asíncronos de “escucha”.

  • Facilidad de uso en su integración.

  • Alto nivel de seguridad, similar a la solución basada en redirección del cliente hacia una página de pago externa.

En definitiva, además de un proceso de pago totalmente integrado en el checkout al comprador, se permite al comercio una mayor flexibilidad y control en el proceso de pago, pudiendo además separar los pasos de captura de datos y ejecución de la operación.

Flujo de Conexión InSite

El siguiente esquema presenta el flujo general de una operación realizada con el TPV Virtual a través de la conexión InSite

flujo insite

1 - El comercio presenta el formulario de pago al titular

2 - Redsys completa el formulario de pago del comercio con los campos de captura de datos de tarjeta

3- El titular introduce sus datos de tarjeta y acepta el pago. Los datos se envían a Redsys sin pasar por el servidor del comercio

4 - Redsys genera un ID de operación y se lo informa al comercio (*)

5 - El comercio lanza la operación de pago Host to Host utilizando el ID de operación recibido

* El ID de operación tendrá una validez de 7 días desde su fecha de generación

En resumen, los datos de pago introducidos por el cliente son enviados desde la página del comercio al TPV Virtual, donde se almacenan temporalmente y se asocian a un Id de Operación que se devuelve al comercio. Con este ID de operación (que viene a ser un “alias” de los datos de pago del cliente) el comercio puede solicitar posteriormente y directamente al tpv virtual la realización de la operación de pago deseada.

Creación de la página de pago y obtención del identificador de operación

Como primer paso para poder integrar los campos de introducción de datos de tarjeta directamente en su propia página web, se debe incluir el fichero Javascript alojado en el servidor de Redsys con la siguiente línea de código (el fichero varía según se vaya a usar el entorno de pruebas o el entorno de producción real):

					
// SandBox
<script src="https://sis-i.redsys.es:25443/sis/NC/inte/redsys2.js"></script>

// Producción
<script src="https://sis.redsys.es/sis/NC/redsys.js"></script>
					
				  

El siguiente paso para incluir los elementos del formulario de pago depende de la alternativa que se desee implementar. A la hora de integrar la conexión inSite existen dos posibilidades:

a) Integración unificada (todo en uno): Los elementos de pago, como las cajas de introducción de número de tarjeta, fecha de caducidad, cvv.. y botón de pago se incrustan como un solo elemento que se adapta a la pagina del comercio (responsive) , con diseño ligero y estilos CSS personalizables. Incluye por defecto ayudas interactivas animadas y una buena usabilidad al usuario.

b) Integración por elementos independientes: los campos se deben incrustar cada uno de forma independiente dentro de la página web de la tienda web, lo que permite el control total del diseño, posición..etc.

Integración unificada

En esta modalidad de la integración inSite se proveerá un único iframe de tamaño muy ajustado en el que se incluirá el formulario de pago al completo. En cuanto a la personalización del mismo, se podrán aplicar los estilos CSS que el comercio requiera a los diferentes elementos.

Incluye elementos interactivos que facilitan la usabilidad, como el reconocimiento de la marca de tarjeta, mostrando el logo de la misma, verificación de los formatos y contenidos conforme los introduce el usuario y resaltando visualmente al momento si alguno es incorrecto (check digit, fecha cad…).

Una vez importado el fichero, se deberá crear el formulario de pago. Para recoger de forma segura los datos de tarjeta, Redsys creará y alojará los campos de introducción de dichos datos.

Se deberá crear un único contenedor, con un id único, ya que se deberá indicar para que se genere iframe con los elementos en él.

					
<div id="card-form"/>
					
				

Al finalizar la carga de la página, se deberá ejecutar una función proporcionada por el propio API, incluyéndose en el atributo onLoad de la misma. De esta forma se asegura que en el entorno de Redsys se disponga de los datos necesarios para la generación del ID de la forma correcta:

					
<body onload="loadRedsysForm()">
					
				

A continuación, se incluirá una función de escucha de mensajes (listener) para recibir el ID de operación cuando éste se genere. Para facilitar la integración, Redsys proporciona en su API una función (storeIdOper) en la que se deberá indicar en qué elemento del DOM se debe almacenar el ID de operación una vez sea generado. En este ejemplo se crea un input de tipo “hidden”.

					
<input type="hidden" id="token" ></input>
<!-- Listener de recepción de ID de operación -->
window.addEventListener("message", function receiveMessage(event) {
	storeIdOper(event,"token");
});
					
				

Una vez preparado el envío de datos y la posterior recepción, se llamará a la función proporcionada para generar los elementos de introducción de datos de tarjeta:

					
<!-- Petición de carga de iframe -->
getInSiteForm('card-form', estiloBoton, estiloBody, estiloCaja, estiloInputs, 'Pagar con Redsys',
 fuc, terminal, merchantOrder);

					
				

Como parámetros de las funciones se indicará el id del contenedor reservado para su generación, así como el estilo requerido para los diferentes elementos (formato CSS). En esta modalidad, se podrán incluir estilos para diferentes elementos:

  • Botón de pago: Se permite la personalización completa del botón de pago.

  • Cuerpo del formulario: Se recomienda utilizar para establecer un color de fondo o modificar el color o estilo de los textos.

  • Caja de introducción de datos: Se podrá establecer un color de fondo diferenciado para la caja de introducción de datos. El color del texto aplicado en este elemento se aplicará al “placeholder” de los elementos.

  • Inputs de introducción de datos: Se recomienda su uso si se quiere utilizar un tipo de letra diferente o modificar el color del texto de los campos de introducción de datos.

Adicionalmente, se podrá personalizar de igual forma el texto a incluir en el botón de pago y, por último, se deberá informar el valor del FUC, terminal y número de pedido en la petición de carga del iframe con el formulario de pago.

De esta forma, cuando el cliente introduzca sus datos de tarjeta en los elementos generados por Redsys y pulse el botón de pago, se generará y almacenará en el formulario del comercio un ID asociado a la operación para que éste formalice la compra sin necesidad de tratar datos de tarjeta.

Demo interactiva

A continuación se puede simular el proceso de introducción de datos de tarjeta y posterior generación de ID de operación.

Tarjeta de crédito o débito

Integración de elementos independientes

En esta modalidad de la integración inSite se permitirá a los comercios una total personalización de la página de pago, por lo que podrá colocar los campos de introducción de datos de tarjeta y el botón de pago con total libertad, al generar iframes diferenciados y personalizables con estilos para cada uno de ellos.

Una vez importado el fichero, se deberá crear el formulario de pago. Para recoger de forma segura los datos de tarjeta, Redsys creará y alojará los campos de introducción de dichos datos.

Se deberán crear contenedores vacíos, con un id único, ya que se deberá indicar para que se genere el campo de introducción de datos en él.

					
<div class="cardinfo-card-number">
  <label class="cardinfo-label" for="card-number">Numero de tarjeta</label>
  <div class='input-wrapper' id="card-number"></div>
</div>
<div class="expiry-date">
  <div class="cardinfo-exp-date">
	<label class="cardinfo-label" for="expiration-date">Mes Caducidad (MM)</label>
	<div class='input-wrapper' id="expiration-month"></div>
  </div> 
<div class="cardinfo-exp-date2">
	<label class="cardinfo-label" for="expiration-date2">Año Caducidad (AA)</label>
	<div class='input-wrapper' id="expiration-year"></div>
</div>
<div class="cardinfo-cvv">
	<label class="cardinfo-label" for="cvv">CVV</label>
	<div class='input-wrapper' id="cvv"></div>
</div>
</div>
					
				

En este ejemplo, se trata de los elementos con id “card-number”,”expirationmonth”,” expiration-year” y “cvv”.

Al finalizar la carga de la página, se deberá ejecutar una función proporcionada por el propio API, incluyéndose en el atributo onLoad de la misma. De esta forma se asegura que en el entorno de Redsys se disponga de los datos necesarios para la generación del ID de la forma correcta:

					
<body onload="loadRedsysForm()">
					
				

A continuación, se incluirá una función de escucha de mensajes (listener) para recibir el ID de operación cuando éste se genere.

Para facilitar la integración, Redsys proporciona en su API una función (storeIdOper) en la que se deberá indicar en qué elemento del DOM se debe almacenar el ID de operación una vez sea generado.

En este ejemplo se crea un input de tipo “hidden”.

					
<input type="hidden" id="token" ></input>
<!-- Listener de recepción de ID de operación -->
window.addEventListener("message", function receiveMessage(event) {
	storeIdOper(event,"token");
});
					
				

Una vez preparado el envío de datos y la posterior recepción, se llamará a las funciones proporcionadas para generar los elementos de introducción de datos de tarjeta:

					

getCardInput('card-number',estilos);
getExpirationMonthInput('expiration-month', estilos);
getExpirationYearInput('expiration-year', estilos);
getCVVInput('cvv', estilos);
getPayButton('boton', estilos,'Pagar con Redsys',fuc,terminal, merchantOrder);
					
				

Como parámetros de las funciones se indicará el id del contenedor reservado para su generación, así como el estilo requerido para el mismo (formato CSS).

Adicionalmente, se podrá personalizar el texto a incluir en el botón de pago.

Se deberá informar el valor del FUC, terminal y número de pedido en la petición de carga del iframe con el botón de pago.

De esta forma, cuando el cliente introduzca sus datos de tarjeta en los elementos generados por Redsys y pulse el botón de pago, se generará y almacenará en el formulario del comercio un ID asociado a la operación para que éste formalice la compra sin necesidad de tratar datos de tarjeta.

Solicitud de operación a partir del identificador generado

Una vez el comercio haya recibido y almacenado el ID de operación, podrá lanzar la operación requerida utilizando el interfaz WebService habitual. En dicha peticion WebService, no será preciso indicar los datos de tarjeta, en su lugar solo es necesario indicar el valor del parametro "Ds_Merchant_idOper" correspondiente al ID generado en el paso anterior.

Para obtener mas información se recomienda consultar la documentación de la conexión WebService

Adicionalmente, desde Redsys se pone a disposición de los comercios librerías que simplifican esta conexión para Java y PHP incluyendo la posibilidad de gestionar el protocolo 3DSecure. Su descarga está disponible en la sección de Descargas y documentación de la web de desarrolladores de Redsys:

Autenticación 3D Secure InSite

Los comercios que utilicen la conexión inSite tienen la posibilidad de incluir el protocolo 3DSecure (3DS) para autenticar a los titulares y obtener un nivel adicional de protección ante fraude.

Incluir la autenticación 3DS implica redirigir la navegación del cliente hacia el servidor de autenticación del banco/entidad emisora de la tarjeta para que éste pueda solicitar las credenciales necesarias. Este paso debe realizarse tras recoger los datos de tarjeta tal y como se describe en los apartados anteriores.

Para utilizar la autenticación 3DS, el terminal del TPV virtual debe estar configurado por parte de su entidad financiera para soportar autenticación 3D Secure. Igualmente podría ser necesario que por configuración del TPV virtual este paso no solo sea opcional, sino que sea requerido para la correcta autorización de las operaciones (si tiene dudas consulte la configuración 3DS a su entidad financiera proveedora del TPV virtual).

Para proceder a autenticar al cliente con 3DS, en la petición directa vía Webservice descrita en el punto anterior, deberá indicarse expresamente mediante el parámetro opcional Ds_Merchant_DirectPayment que deberá llevar asignado el valor “3DS”, lo que indica que el comercio está preparado para manejar las autenticaciones 3DS.

Incluir este parámetro implica la activación del siguiente flujo:

  1. El TPV virtual no procesa inmediatamente la solicitud de operación en cuanto la recibe, sino que en su lugar,

  2. se verifica la posibilidad de iniciar el protocolo de autenticación (tanto para el comercio -configuración 3DS permitida- como para la tarjeta introducida por el cliente -capacidad 3DS disponible-). Si el terminal no está configurado para permitir 3DS o la tarjeta no requiere/soporta autenticación por 3DS, se procede a procesar la solicitud de operación sin requerir autenticación 3DS y se responderá de forma normal (flujo de 1 paso) del resultado de la misma.

  3. Se obtiene, entre otros datos, la URL a la cual el comercio debe redirigir al navegador del cliente para su autenticación.

  4. El TPV virtual devuelve al comercio los datos necesarios para que inicie la redirección del titular a la URL de autenticación del banco emisor de la tarjeta.

  5. El servidor del comercio debe redirigir la navegación del cliente hacia la URL del banco de la tarjeta, donde se procederá a la autenticación 3DS.

  6. El servidor del comercio recibirá de vuelta la navegación del cliente tras el proceso de autenticación, incluyendo los datos resultado.

  7. El servidor del comercio deberá completar la transacción con un segundo mensaje WebService al TPV virtual, incluyendo los datos obtenidos como resultado de la autenticación 3DS.

Ejemplo:

					
<REQUEST>
	<DATOSENTRADA>
		<DS_MERCHANT_IDOPER>455097a74c21b761be86acb26c32609dce222e66</DS_MERCHANT_IDOPER>
		<DS_MERCHANT_ORDER>1234ased1711</DS_MERCHANT_ORDER>
		<DS_MERCHANT_AMOUNT>42</DS_MERCHANT_AMOUNT>
		<DS_MERCHANT_CURRENCY>978</DS_MERCHANT_CURRENCY>
		<DS_MERCHANT_MERCHANTCODE>999008881</DS_MERCHANT_MERCHANTCODE>
		<DS_MERCHANT_TERMINAL>1</DS_MERCHANT_TERMINAL>
		<DS_MERCHANT_TRANSACTIONTYPE>0</DS_MERCHANT_TRANSACTIONTYPE>
		<DS_MERCHANT_DIRECTPAYMENT>3DS</DS_MERCHANT_DIRECTPAYMENT>
	</DATOSENTRADA>
	<DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_SIGNATUREVERSION>
	<S_SIGNATURE>PcQKZ9rHY1Q5Ta6Sf1uy64Skm7ZA53Oq5lEXM9QIj0Q=</DS_SIGNATURE>
</REQUEST>
					
				
Respuesta de la petición

En la respuesta de la petición WebService se informarán, además de los datos de la operación (aún no realizada), los siguientes parámetros necesarios para redirigir al cliente a autenticarse con su banco emisor:

Ds_AcsUrl: URL del ACS al que hay que redirigir al usuario.
Ds_PaRequest: Parámetro necesario para identificar la operación.
Ds_MD: Identificador de sesión.

Ejemplo:

					
					
<RETORNOXML>
	<CODIGO>0</CODIGO>
	<OPERACION>
		<Ds_Amount>42</Ds_Amount>
		<Ds_Currency>978</Ds_Currency>
		<Ds_Order>1234ased1711</Ds_Order>
		<Ds_Signature>8in9WK+f5wuT/CGvHYLZqpi6jHtMB/FjmKR0JJWkz8Y=</Ds_Signature>
		<Ds_MerchantCode>999008881</Ds_MerchantCode>
		<Ds_Terminal>1</Ds_Terminal>
		<Ds_TransactionType>0</Ds_TransactionType>
		<Ds_AcsUrl>https://sas-i.redsys.es:26443/sas/Secure</Ds_AcsUrl>
		<Ds_PaRequest>eJxVksFSwjAQhl+lU2e8SZKaQotLmGrr6KHIAB48xnQH6kALSav17U2gKB4y2W+T7P7zb2Da7bbe J2p
		T1tXEZwPqe1ipuiir9cR/XT3eRP5UwGqjEdMlqlajgByNkWv0ymLi68LIsvuSpmSVGoajgMcB ZRHldMgY47cRpTQeUV/A
		PFngQUDfS9hWgwDIGW1RrTayagRIdbh/ngkehmwUA+kRdqifU7HMFnk2 T/Js8fCUzFZATmmo5A6Fqi2psvaur26jO2+vW
		3yXxlsgkOM5qLqtGv0trEwgZ4BWb8WmafZjQra1 kttNbRogLgvkT9a8dZGxVbqyEPlH0r2kCc3Tty5fZXSWvrI8Tb7smg
		BxN6CQDYqzGR6Nx4yPeQjk mAe5c+0FHXDrQg+wdz2SE7j8JYM1X9vZfIt4FFn1ZwLs9nWF9oZ98BtDgUZZ/f32J/7hyTm
		sGmva 5aA4C4LImX08cTVLaw2P2amoAyDuLennSPpfYKN/v+MHGte/sQ==</Ds_PaRequest>
		<Ds_MD>d65b7415dcda4c1d1f92a864be56e5987f3702fd</Ds_MD>
	</OPERACION>
</RETORNOXML>
					

					
Redirección al cliente

Una vez recibida la respuesta, el comercio deberá hacer una redirección al cliente (a través de un formulario POST) a la URL recibida, indicando los siguientes parámetros:

PaReq: Se informará el valor recibido anteriormente en el parámetro Ds_PaRequest de la petición WebService.
MD: Se informará el valor recibido anteriormente en el parámetro Ds_MD de la petición WebService.
TermUrl: Se informará la URL a la que el ACS retornará la respuesta tras la autenticación.

Una vez que el usuario de la tarjeta realice la autenticación en la URL de su banco emisor, la respuesta (vía redirección) del ACS al servidor del comercio contendrá los siguientes parámetros:

PaRes: Parámetro necesario para enviar al SIS una vez finalizado el proceso.
MD: Identificador de sesión.

Confirmación de autenticación

Una vez recogidos los parámetros por el servidor de la tienda, debe lanzarse una nueva petición WS hacia el TPV virtual SIS con los datos obtenidos del resultado de la autenticación del cliente, informando ambos parámetros adicionales en los siguientes campos:.

Ds_Merchant_PaResponse: Parámetro, recibido en la respuesta del ACS, necesario para enviar al SIS una vez finalizado el proceso.
Ds_Merchant_Md: Identificador de sesión recibido en la respuesta del ACS.

Ejemplo:

					
					
<REQUEST>
	<DATOSENTRADA>
		<DS_MERCHANT_PARESPONSE>eJzFWFmzosqyfudXrOjz6O3NICrscK0TxaSABTILbwjIIIMCyvDrL66pV3f0jd3n3odLhF
		KVZCZfZWV9ldT6332RP92jukmr8vkb/hf27SkqgypMy/j5m2UK36lv/35Zm0kdRZwRBbc6elnDqGn8OHpK w+dvddj4ad/
		5TYqXwXKxIkiawHAKI7EljuPknMIwjF5h317We6BHzatNU1wmm4VfBiS+nC+xHwbE YupM1wqfDN5RvUyg/iLW6Ed3en0d
		JH7Zvqz94MqIygu5WOAreo2+d9dFVIvci8HrkN8DyOvsFijm Gn0Tr9Ef9vvbo9VMQ+rT8AVmoFc5gEHO7aHJYwpn4ZAD3
		fR7XqMPjXXot9HLB9wnjP4bJ/8mF2v0 Vb6+PNyBorpNvskJ8df+egpdPUV2eKFX1Br97K2j/lKV0aQxGXy21+gPaBe/fM
		F+vuaT70m6Ng8v ….</DS_MERCHANT_PARESPONSE>
		<DS_MERCHANT_MD>d65b7415dcda4c1d1f92a864be56e5987f3702fd</DS_MERCHANT_MD>
		<DS_MERCHANT_ORDER>1234ased1711</DS_MERCHANT_ORDER>
		<DS_MERCHANT_AMOUNT>42</DS_MERCHANT_AMOUNT>
		<DS_MERCHANT_CURRENCY>978</DS_MERCHANT_CURRENCY>
		<DS_MERCHANT_MERCHANTCODE>999008881</DS_MERCHANT_MERCHANTCODE>
		<DS_MERCHANT_TERMINAL>1</DS_MERCHANT_TERMINAL>
		<DS_MERCHANT_TRANSACTIONTYPE>0</DS_MERCHANT_TRANSACTIONTYPE>
	</DATOSENTRADA>
	<DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_SIGNATUREVERSION>
	<DS_SIGNATURE>j7PusjxEhs39dvx3Oju3KjZ6+G2JnIX06o/reW9BXxM=</DS_SIGNATURE>
</REQUEST>
					
					
					

Tras el envío de la peticion WebService, Redsys enviará una contestación al comercio indicandole el resultado final de la operación.

Ejemplo:

					
					
<RETORNOXML>
	<CODIGO>0</CODIGO>
	<OPERACION>
		<Ds_Amount>42</Ds_Amount>
		<Ds_Currency>978</Ds_Currency>
		<Ds_Order>1234ased1711</Ds_Order>
		<Ds_Signature>KVwNaWSqsJWUlzpCWQENZbhHn6VJ8gRkw5CtF//cfeg=</Ds_Signature>
		<Ds_MerchantCode>999008881</Ds_MerchantCode>
		<Ds_Terminal>1</Ds_Terminal>
		<Ds_Response>0000</Ds_Response>
		<Ds_AuthorisationCode>745638</Ds_AuthorisationCode>
		<Ds_TransactionType>0</Ds_TransactionType>
		<Ds_SecurePayment>1</Ds_SecurePayment>
		<Ds_Language>1</Ds_Language>
		<Ds_Card_Type>C</Ds_Card_Type>
		<Ds_MerchantData></Ds_MerchantData>
		<Ds_Card_Country>724</Ds_Card_Country>
		<Ds_Card_Brand>1</Ds_Card_Brand>
	</OPERACION>
</RETORNOXML>
					

					

Conexión por Web Service

Descripción general del flujo

El siguiente esquema presenta el flujo general de una operación realizada con el TPV Virtual.

descripcion general del flujo

1 - El titular selecciona los productos que desea comprar e introduce los datos de tarjeta en un formulario mostrado por el comercio.

2 - El comercio envía los datos del pago al TPV virtual.

3 - Una vez realizado el pago, el TPV virtual informa del resultado de la operación.

4 - El comercio devuelve la informacion del resultado del pago al titular.

Mensaje de petición de pago WebService

Para que el comercio pueda realizar la petición a través del Web Service de Redsys,es necesario intercambiar una serie de datos, tanto en los mensajes de petición como en los mensajes de respuesta.

La estructura del mensaje siempre será la misma, estableciendo como raíz del mismo el elemento <REQUEST>. En su interior siempre deben encontrarse tres elementos que hacen referencia a:

  • Datos de la petición de pago: Elemento identificado por la etiqueta <DATOSENTRADA>.

  • Versión del algoritmo de firma: Elemento identificado por la etiqueta <DS_SIGNATUREVERSION>.

  • Firma de los datos de la petición de pago: Elemento identificado por la etiqueta <DS_SIGNATURE>.

A continuación se muestra un ejemplo de un mensaje de petición de pago:

                   
<REQUEST>
<DATOSENTRADA>
<DS_MERCHANT_AMOUNT>145</DS_MERCHANT_AMOUNT>
<DS_MERCHANT_ORDER>1444904795</DS_MERCHANT_ORDER>
<DS_MERCHANT_MERCHANTCODE>999008881</DS_MERCHANT_MERCHANTCODE>
<DS_MERCHANT_CURRENCY>978</DS_MERCHANT_CURRENCY>
<DS_MERCHANT_PAN>XXXXXXXXXXXXXXXX</DS_MERCHANT_PAN>
<DS_MERCHANT_CVV2>XXX</DS_MERCHANT_CVV2>
<DS_MERCHANT_TRANSACTIONTYPE>0</DS_MERCHANT_TRANSACTIONTYPE>
<DS_MERCHANT_TERMINAL>871</DS_MERCHANT_TERMINAL>
<DS_MERCHANT_EXPIRYDATE>XXXX</DS_MERCHANT_EXPIRYDATE>
</DATOSENTRADA>
<DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_SIGNATUREVERSION>
<DS_SIGNATURE>
VV3acxBgABrS5VYcLyJD1KqIsa2pPdvajPBG510lFfg=
</DS_SIGNATURE>
</REQUEST>
          
                    
                    
Pasos a seguir para montar el mensaje de petición de pago

Para facilitar la integración del comercio, a continuación se explica de forma detallada los pasos a seguir para montar el mensaje de petición de pago.

Montar la cadena de datos de la petición

Se debe montar una cadena con todos los datos de la petición en formato XML dando como resultado el elemento <DATOSENTRADA>. Se debe tener en cuenta que existen varios tipos de peticiones y según el tipo varía la estructura del mensaje y los parámetros que se envían y reciben.

Podemos diferenciar tres tipos de peticiones:

  • Peticiones de pago (con envío de datos de tarjeta).

  • Peticiones de pagos recurrentes (con envío de datos de tarjeta).

  • Peticiones de Confirmación/Devolución.

Para comercios que utilicen operativas especiales como el “Pago por referencia” (Pago 1-Click), deberán incluir los campos específicos de este tipo de operativa en el elemento <DATOSENTRADA>.

Identificar la versión de algoritmo de firma a utilizar

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 elemento <DS_SIGNATUREVERSION>

Identificar la clave a utilizar para la firma

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

descripcion general del flujo Firmar los datos de la petición

Una vez se tiene montado el elemento con los datos de la petición de pago (<DATOSENTRADA>) 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 elemento <DATOSENTRADA>.

3. El resultado obtenido se codifica en BASE 64, y el resultado de la codificación será el valor del elemento <DS_SIGNATURE>

Utilización de librerías de ayuda

En los apartados anteriores se ha descrito la forma de acceso al SIS utilizando conexión por Redirección y el sistema de firma basado en HMAC SHA256. En este apartado se explica cómo 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.

Desarrollo y generación de la firma de petición WebService
                    
/*Importar el fichero principal de la librería, tal y como se muestra continuación. El comercio debe decidir
si la importación desea hacerla con la función “include” o “required”, según los desarrollos realizados. */
include_once 'redsysHMAC256_API_WS_PHP_4.0.4/apiRedsysWs.php';
/* Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación: */
$miObj = new RedsysAPIWs;
/* Calcular el elemento . Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería “createMerchantSignatureHostToHost()” con la
clave del comercio SHA 256 obtenida del módulo de administración y el elemento con los datos de la
petición de pago (), tal y como se muestra a continuación: */
$datosEntrada="145144490479599
9008881978XXXXXXXXXXXXXXXXXXX0871XXXX";
$claveSHA256 = 'Mk9m98IfEblmPfrpsawt7BmxObt98Je';
$firma = $miObj->createMerchantSignatureHostToHost($claveSHA256,
$datosEntrada);
/*Una vez obtenido el valor del elemento , ya se puedo
completar el mensaje de petición de pago y realizar la llamada Web Service. */
                    
                    
                    
/*Importar la librería, tal y como se muestra a continuación*/
<%@page import="sis.redsys.api.ApiWsMacSha256" %>
/*El comercio debe incluir en la vía de construcción del proyecto todas las
librerías(JARs) que se proporcionan:*/

/*Definir un objeto de la clase principal de la librería, tal y como se muestra a
continuación:*/
ApiWsMacSha256 apiWsMacSha256 = new ApiWsMacSha256();
/*Calcular el elemento . Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería “createMerchantSignatureHostToHost()” con la
clave del comercio SHA 256 obtenida del módulo de administración y el elemento con los datos de la
petición de pago (), tal y como se muestra a continuación:*/
String datosEntrada =
"1451444904795999008881
978XXXXXXXXXXXXXX
XXXXX0871XXXX";
String claveSHA256 = "Mk9m98IfEblmPfrpsawt7BmxObt98Je";
String firma =
apiWsMacSha256.createMerchantSignatureHostToHost(claveSHA256, datosEntrada);
/*Una vez obtenido el valor del elemento , ya se puedo
completar el mensaje de petición de pago y realizar la llamada Web Service. */
                    
                    
                        
/*Importar la librería, tal y como se muestra a continuación:*/
using RedsysAPIPrj;
/*Crear un objeto de la clase del Web Service de Redsys. Para poder realizar
esto es necesario añadir una nueva referencia web con el fichero SerClsWSEntrada.wsdl.*/
WebRedsysWs.SerClsWsEntradaService s = new
WebRedsysWs.SerClsWsEntradaService();
/*Nota: En el atributo location de la etiqueta  Del fichero
SerClsWSEntrada.wsdl, indicar si se trata del entorno real o pruebas:
https://sis-t.redsys.es:25443/sis/services/SerClsWSEntrada
(Pruebas)
https://sis.redsys.es/sis/services/SerClsWSEntrada (Real)
*/
/*Definir un objeto de la clase principal de la librería, tal y como se muestra a
continuación. Al realizar este paso se inicializan los atributos diccionario clave/valor m_keyvalues y cryp
de la clase Cryptogra (Clase auxiliar para realizar las operaciones criptográficas necesarias)*/
RedsysAPIWs r = new RedsysAPIWs();
/*Generar parametros de DATOSENTRADA (Modalidad Petición de Pago con
envío de datos de tarjeta) mediante la función:*/
string datosEntrada = r.GenerateDatoEntradaXML(amount, fuc, currency,
pan, cvv2, trans, terminal, expire);
/*Calcular el elemento . Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería “createMerchantSignatureHostToHost()” con la
clave del comercio SHA 256 obtenida del módulo de administración y el elemento con los datos de la
petición de pago (), tal y como se muestra a continuación:*/
string claveSHA256 = "Mk9m98IfEblmPfrpsawt7BmxObt98Je";
string firma = r.createMerchantSignatureHostToHost(claveSHA256,
datosEntrada);
/*Una vez obtenido el valor del elemento , ya se puedo
completar el mensaje de petición de pago y realizar la llamada Host to Host. Se genera el string XML final
de petición de pago con DATOSENTRADA, DS_SIGNATUREVERSION y DS_SIGNATURE*/
string peticionXML = r.GenerateRequestXML(datosEntrada, firma);
/*Después se llama al método trataPeticion del Web service de Redsys
pasándole como parámetro el string XML final calculado con el método GenerateRequestXML.*/
string result = s.trataPeticion(peticionXML);
                        
                      
Respuesta de pago y firma de respuesta WebService

En el presente apartado se describen los datos que forman parte del mensaje de respuesta de una petición al TPV virtual WebService. Este mensaje se genera en formato XML y a continuación se muestran ejemplos:

A. Pasos a seguir para generar la respuesta y firma del mensaje
                      
<!--Ejemplo de respuesta de pago (comercio configurado sin envío de datos de tarjeta): --> 
<RETORNOXML>
<CODIGO>0</CODIGO>
<OPERACION>
<Ds_Amount>145</Ds_Amount>
<Ds_Currency>978</Ds_Currency>
<Ds_Order>1444912789</Ds_Order>
<Ds_Signature>bAuiQOymGvYzqHi7dEeuWrRYFeUjtFH6NyOoWSl0vHU=</Ds_Signature>
<Ds_MerchantCode>999008881</Ds_MerchantCode>
<Ds_Terminal>871</Ds_Terminal>
<Ds_Response>0000</Ds_Response>
<Ds_AuthorisationCode>050372</Ds_AuthorisationCode>
<Ds_TransactionType>0</Ds_TransactionType>
<Ds_SecurePayment>0</Ds_SecurePayment>
<Ds_Language>1</Ds_Language>
<Ds_Card_Type>D</Ds_Card_Type>
<Ds_MerchantData></Ds_MerchantData>
<Ds_Card_Country>724</Ds_Card_Country>
</OPERACION>
</RETORNOXML>
          
                    
                    
                    
<!--EJEMPLO DE ESTRUCTURA DE RESPUESTA(comercio configurado con envío de datos de tarjeta) --> 
<RETORNOXML>
<CODIGO>0</CODIGO>
<OPERACION>
<Ds_Amount>145</Ds_Amount>
<Ds_Currency>978</Ds_Currency>
<Ds_Order>1449821545</Ds_Order>
<Ds_Signature>6quLImPCOSTFpwhC7+ai1L+SPdKbcGx2sgC2A/1hwQo=</Ds_Signature>
<Ds_MerchantCode>999008881</Ds_MerchantCode>
<Ds_Terminal>871</Ds_Terminal>
<Ds_Response>0000</Ds_Response>
<Ds_AuthorisationCode>109761</Ds_AuthorisationCode>
<Ds_TransactionType>0</Ds_TransactionType>
<Ds_SecurePayment>0</Ds_SecurePayment>
<Ds_Language>1</Ds_Language>
<Ds_CardNumber>XXXXXXXXXXXXXXXX</Ds_CardNumber>
<Ds_MerchantData></Ds_MerchantData>
<Ds_Card_Country>724</Ds_Card_Country>
</OPERACION>
</RETORNOXML>
                    
                    

Como se puede observar en el ejemplo anterior, la respuesta está formada por dos elementos principales:

- Código (<CODIGO>): Indica si la operación ha sido correcta o no, (no indica si ha sido autorizada, solo si se ha procesado). Un 0 indica que la operación ha sido correcta. En el caso de que sea distinto de 0, tendrá un código.

- Datos de la operación (<OPERACION>): Recoge toda la información necesaria sobre la operación que se ha realizado. Mediante este elemento se determina si la operación ha sido autorizada o no. Para conocer las posibles respuestas a la operación ver la tabla de códigos del índice.

B.Uso de librerías de ayuda para desarrollo de respuesta y firma Web Service
                    
/*Importar el fichero principal de la librería, tal y como se muestra a continuación. El comercio
debe decidir si la importación desea hacerla con la función “include” o “required”, según los
desarrollos realizados.*/
include_once
'redsysHMAC256_API_WS_PHP_4.0.2/apiRedsysWs.php';
/*Definir un objeto de la clase principal de la librería, tal y
como se muestra a continuación: */
$miObj = new RedsysAPIWs;
/*Calcular el parámetro . Para llevar a
cabo elcálculo de este parámetro, se debe llamar a la función de la librería
“createSignatureResponseHostToHost()” con la clave del comercio SHA 256 obtenida del módulo
de administración, la cadena que se desea firmar(concatenación de campos descrita en el punto 2
del apartado 4.1 del presente documento) y el número de pedido.*/
$cadenaConcatenada="1451444912789999008881978000000";
$numPedido ="1444912789";
$claveSHA256 = 'Mk9m98IfEblmPfrpsawt7BmxObt98Je';
$firma = $miObj-
>createSignatureResponseHostToHost($claveSHA256,$cadenaConcatenada,$numPedido);
/*El resultado obtenido debe ser el mismo que el valor
del parámetro  obtenido en la respuesta.*/

                    
                    
                    
/*Importar la librería, tal y como se muestra a continuación*/
<%@page import="sis.redsys.api.ApiWsMacSha256" %>
/*El comercio debe incluir en la vía de construcción del
proyecto todas las librerías(JARs) que se proporcionan:*/

/*Definir un objeto de la clase principal de la librería, tal y
como se muestra a continuación:*/
ApiWsMacSha256 apiWsMacSha256 = new
ApiWsMacSha256();
/*Calcular el elemento . Para llevar a
cabo el cálculo de este parámetro, se debe llamar a la función de la librería
“createSignatureResponseHostToHost()” con la clave obtenida del módulo de administración, la
cadena que se desea firmar(concatenación de campos descrita en el punto 2 del apartado 4.1 del
presente documento) y el número de pedido.*/
String cadenaConcatenada =
"1451444912789999008881978000000";
String $numPedido ="1444912789";
String claveSHA256 =
"Mk9m98IfEblmPfrpsawt7BmxObt98Je";
String firma =
apiWsMacSha256.createSignatureResponseHostToHost(claveSHA256,cadenaConcatenada,numPed
ido);
/*El resultado obtenido debe ser el mismo que el valor
del parámetro  obtenido en la respuesta.*/
                    
                    
                        
/* Importar la libreria que proporciona Redsys, tal y como se muestra a continuación y crear un
objeto de la clase principal de dicha librería. */
using RedsysAPIPrj;
RedsysAPIWs r = new RedsysAPIWs();
/*Convertir la cadena respuesta XML al atributo
diccionario m_keyvalues de la clave RedsysAPIWs:*/
r.XMLToDiccionary(result);
/*Calcular el parámetro . Para llevar a
cabo el cálculo de este parámetro, se debe llamar a la función de la librería
“createSignatureResponseHostToHost()” con la clave del comercio SHA 256 obtenida del módulo
de administración, la cadena que se desea firmar(concatenación de campos descrita en el punto 2
del apartado 5.1 del presente documento) y el número de pedido.*/
string claveSHA256 =
"Mk9m98IfEblmPfrpsawt7BmxObt98Je";
string cadena = r.GenerateCadena(result);
string numPedido = r.GetDictionary("Ds_Order");
string firmaCalculada =
r.createSignatureResponseHostToHost(claveSHA256, cadena, numPedido);
/*El resultado obtenido debe ser el mismo que el valor
del parámetro  obtenido en la respuesta.*/
                        
                      
Operativa DCC

A continuación se detallarán todas aquellas características adicionales de la operativa DCC que tengan los comercios que hayan contratado este servicio.

descripcion general del flujo

NOTA: Como se muestra en el gráfico la operativa DCC se basa en el envío de dos peticiones al WebService del TPV virtual. Para garantizar el correcto funcionamiento del sistema, es necesario que el comercio mantenga la sesión entre la primera y la segunda llamada al WebService. El mantenimiento de la sesión dependerá del software utilizado para realizar la llamada al WebService. Por ejemplo si se utiliza el API de Axis, será suficiente con utilizar el mismo “Stub” para las dos peticiones y fijar la propiedad setMaintainSession(true) antes de realizar la primera llamada.

Métodos de acceso

El método de acceso “trataPeticion”: permite la realización de operaciones a través del TPV virtual WebService. Se usa el mismo método tanto para realizar los pagos tradicionales como para la operativa DCC y, en función de los campos que se remitan en el XML de petición, se realizará una u otra opción.

El método de acceso “consultaDCC”: permite hacer consultas del DCC asociado a un importe y una moneda con anterioridad a ejecutar la transacción. Es meramente informativo.

Independientemente de la petición, la firma del comercio se calcula realizando el nuevo procedimiento de firma HMAC_SHA256

Mensajes de ‘Trata Petición’
Mensaje petición inicial

El mensaje de petición inicial posee las mismas características que lo descrito anteriormente.

                        
<!-- Ejemplo de petición inicial--> 
<REQUEST>
<DATOSENTRADA>
<DS_MERCHANT_AMOUNT>145</DS_MERCHANT_AMOUNT>
<DS_MERCHANT_ORDER>1444904795</DS_MERCHANT_ORDER>
<DS_MERCHANT_MERCHANTCODE>999008881</DS_MERCHANT_MERCHANTCODE>
<DS_MERCHANT_CURRENCY>978</DS_MERCHANT_CURRENCY>
<DS_MERCHANT_PAN>XXXXXXXXXXXXXXXX</DS_MERCHANT_PAN>
<DS_MERCHANT_CVV2>XXX</DS_MERCHANT_CVV2>
<DS_MERCHANT_TRANSACTIONTYPE>0</DS_MERCHANT_TRANSACTIONTYPE>
<DS_MERCHANT_TERMINAL>6</DS_MERCHANT_TERMINAL>
<DS_MERCHANT_EXPIRYDATE>XXXX</DS_MERCHANT_EXPIRYDATE>
</DATOSENTRADA>
<DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_SIGNATUREVERSION>
<DS_SIGNATURE>7ZEurW0QJVbRcCHf23kM3vNh50dDQAvu8HLmiJ/eDQA=</DS_SIGNATURE>
</REQUEST>
            
                      
                      
Mensaje de respuesta DCC

A continuación se describen los datos necesarios y sus características, que se recibirán en los mensajes de respuesta DCC del TPV virtual en el formato XML descrito anteriormente para la operativa DCC y que sirven como ejemplo para la posterior confirmación DCC.

                        
<!-- Ejemplo de respuesta DCC--> 
<RETORNOXML>
<CODIGO>0</CODIGO>
<DCC>
<moneda>826</moneda>
<litMoneda>POUND STERLING</litMoneda>
<litMonedaR>GBP</litMonedaR>
<cambio>1.369986</cambio>
<fechaCambio>2015-06-16</fechaCambio>
<importe>1.06</importe>
<checked>true</checked>
</DCC>
<DCC>
<moneda>978</moneda>
<litMoneda>Euros</litMoneda>
<importe>1.45</importe>
</DCC>
<margenDCC>0.03</margenDCC>
<nombreEntidad>SIN CAPTURA</nombreEntidad>
<DS_MERCHANT_SESION>0b33f991d36b28cf643769691f3e86140fa7d1e4</DS_MERCHANT_SESION>
</RETORNOXML>
            
                      
                      
Mensaje de confirmación DCC

A continuación se describen los datos necesarios y sus características para enviar una petición de confirmación DCC al TPV Virtual Webservice en el formato y que sirven como ejemplo para confirmar el anterior mensaje de petición DCC.

                        
<!-- Ejemplo de mensaje de confirmación de moneda DCC--> 
<REQUEST>
<DATOSENTRADA>
<DS_MERCHANT_ORDER>1444904795</DS_MERCHANT_ORDER>
<DS_MERCHANT_MERCHANTCODE>999008881</DS_MERCHANT_MERCHANTCODE>
<DS_MERCHANT_TERMINAL>6</DS_MERCHANT_TERMINAL>
<Sis_Divisa>978#1.45</Sis_Divisa>
<DS_MERCHANT_SESION>0b33f991d36b28cf643769691f3e86140fa7d1e4</DS_MERCHANT_SESION>
</DATOSENTRADA>
<DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_SIGNATUREVERSION>
<DS_SIGNATURE>yUBgA1G0UIT6CtnwoG1PJrTtzNXEtD24vsS8nIH6KR8=</DS_SIGNATURE>
</REQUEST>
            
                      
                      
Mensaje de respuesta a confirmación de moneda DCC

El mensaje de respuesta posee las mismas características que lo descrito anteriormente.

                        
<!-- Ejemplo de respuesta a confirmación de moneda DCC--> 
<RETORNOXML>
<CODIGO>0</CODIGO>
<OPERACION>
<Ds_Amount>145</Ds_Amount>
<Ds_Currency>978</Ds_Currency>
<Ds_Order>1444904795</Ds_Order>
<Ds_Signature>EtP9XhoR0njz7QDTzu7C0FB7+KJGI68s0YlKqMsse00=</Ds_Signature>
<Ds_MerchantCode>999008881</Ds_MerchantCode>
<Ds_Terminal>6</Ds_Terminal>
<Ds_Response>0909</Ds_Response>
<Ds_AuthorisationCode/>
<Ds_TransactionType>0</Ds_TransactionType>
<Ds_SecurePayment>0</Ds_SecurePayment>
<Ds_Language>1</Ds_Language>
<Ds_MerchantData/>
<Ds_Card_Country>826</Ds_Card_Country>
</OPERACION>
</RETORNOXML>
            
                      
                      

Conexión por Redirección

Descripción general del flujo

Esta forma de conexión permite trasladar la sesión del cliente final al TPV Virtual, de forma que la selección del medio de pago y la introducción de datos se llevan a cabo en el entorno seguro del servidor del TPV Virtual y fuera de la responsabilidad del comercio. Además de la sencillez de implementación para el comercio y la tranquilidad respecto a la responsabilidad de los datos de pago, este modo de conexión da cabida a la utilización de mecanismos de autenticación como el 3D Secure, donde el banco de la tarjeta solicita directamente al titular un dato secreto que permite dotar de más seguridad a las compras. El siguiente esquema presenta el flujo general de una operación realizada con el TPV virtual.

descripcion general del flujo

1 - El titular selecciona los productos que desea comprar en el comercio.

2 - El comercio redirige la sesion del navegador del cliente a la URL de Redsys. En esta URL el cliente introduce los datos de tarjeta.

3 - El TPV virtual informa al comercio del resultado de la operación.

4 - Redsys devuelve la sesion del navegador del cliente al comercio para que continue navegando en su tienda web.

Ejemplos de formulario de envío de petición

El comercio deberá montar un formulario con los parámetros de la petición de pago que debe hacer llegar al TPV virtual a través del navegador del cliente. A continuación se muestran diversos ejemplos del formulario de petición de pago:

                      
<!--Ejemplo de formulario de pago sin envío de datos de tarjeta:-->
<form name="from" action="https://sis-t.redsys.es:25443/sis/realizarPago" method="POST">
<input type="hidden" name="Ds_SignatureVersion" value="HMAC_SHA256_V1"/>
<input type="hidden" name="Ds_MerchantParameters" value="
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiI5OTkiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjEyMzQ1
Njc4OTAiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NR
VJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQR
SI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFO
VFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhw
IiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0su
cGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJ
sS08ucGhwIn0="/>
<input type="hidden" name="Ds_Signature"
value="PqV2+SF6asdasMjXasKJRTh3UIYya1hmU/igHkzhC+R="/>
</form>
          
                    
                    
                      
<!--Ejemplo de formulario de pago con envío de datos de tarjeta:-->
<form name="from" action="https://sis-t.redsys.es:25443/sis/realizarPago" method="POST">
<input type="hidden" name="Ds_SignatureVersion" value="HMAC_SHA256_V1"/>
<input type="hidden" name="Ds_MerchantParameters" value="
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiIxNDUiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjE0NDY
wNjg1ODEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19N
RVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQ
RSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEF
OVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGh
wIiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0
sucGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvd
XJsS08ucGhwIiwiRFNfTUVSQ0hBTlRfUEFOIjoiNDU0ODgxMjA0OTQwMDAwNCIsIkRTX01
FUkNIQU5UX0VYUElSWURBVEUiOiIxNTEyIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyJ9"/>
<input type="hidden" name="Ds_Signature"
value="PqV2+SF6asdasMjXasKJRTh3UIYya1hmU/igHkzhC+R="/>
</form>
          
                    
                    
Identificar la versión de algoritmo de firma a utilizar

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 petición

Se debe montar una cadena con todos los datos de la petición en formato JSON. JSON es un formato abierto de intercambio de datos basado en texto. Al igual que el XML está diseñado para ser legible e independiente de la plataforma tecnológica. La codificación de datos en JSON es muy ligera por lo que es ideal para intercambio de datos en aplicaciones Web.

El nombre de cada parámetro debe indicarse en mayúsculas o con estructura “CamelCase” (Por ejemplo: DS_MERCHANT_AMOUNT o Ds_Merchant_Amount).

Los comercios que utilicen operativas especiales como el “Pago por referencia” (Pago 1-Click), deberán incluir los parámetros específicos de su operativa como parte del objeto JSON.

Ejemplo sin envío de datos de tarjeta:
            
{"DS_MERCHANT_AMOUNT":"145","DS_MERCHANT_ORDER":"1446117555","DS_MER
CHANT_MERCHANTCODE":"999008881","DS_MERCHANT_CURRENCY":"978","DS_MER
CHANT_TRANSACTIONTYPE":"0","DS_MERCHANT_TERMINAL":"1","DS_MERCHANT_ME
RCHANTURL":"http:\/\/www.prueba.com\/urlNotificacion.php","DS_MERCHANT_URLOK
":"http:\/\/www.prueba.com\/urlOK.php","DS_MERCHANT_URLKO":"http:\/\/www.ban
csabadell.com\/urlKO.php"}          
            
            
Ejemplo con envío de datos de tarjeta:
            
{"DS_MERCHANT_AMOUNT":"145","DS_MERCHANT_ORDER":"1446068581","DS_MER
CHANT_MERCHANTCODE":"999008881","DS_MERCHANT_CURRENCY":"978","DS_MER
CHANT_TRANSACTIONTYPE":"0","DS_MERCHANT_TERMINAL":"1","DS_MERCHANT_ME
RCHANTURL":"http:\/\/www.prueba.com\/urlNotificacion.php","DS_MERCHANT_URLOK
":"http:\/\/www.prueba.com\/urlOK.php","DS_MERCHANT_URLKO":"http:\/\/www.pru
eba.com\/urlKO.php","DS_MERCHANT_PAN":"XXXXXXXXXXXXXXXX","DS_MERCHANT_E
XPIRYDATE":"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 su paso por el navegador del cliente/comprador.

A continuación se muestran los objetos JSON que se acaban de mostrar codificados en BASE64:

Ejemplo JSON codificado sin envío de datos de tarjeta:
            
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiI5OTkiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjEyMzQ1
Njc4OTAiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NR
VJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQR
SI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFO
VFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhw
IiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0su
cGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJ
sS08ucGhwIn0         
            
            
Ejemplo JSON codificado con envío de datos de tarjeta:
            
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiIxNDUiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjE0NDY
wNjg1ODEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19N
RVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQ
RSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEF
OVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGh
wIiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0
sucGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvd
XJsS08ucGhwIiwiRFNfTUVSQ0hBTlRfUEFOIjoiNDU0ODgxMjA0OTQwMDAwNCIsIkRTX01
FUkNIQU5UX0VYUElSWURBVEUiOiIxNTEyIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyJ9       
            
            

La cadena resultante de la codificación en BASE64 será el valor del parámetro Ds_Merchant_Parameters. Para la generación de este campo se utilizarán las librerías de ayuda proporcionadas por Redsys

Identificar la clave a utilizar para la firma

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

Clave de firma
Utilización de librerías de ayuda para la integración

En este apartado se explica cómo se utilizan las librerías disponibles en PHP, JAVA y .NET para facilitar los desarrollos y la generación de la firma de respuesta. El uso de las librerías suministradas por Redsys es opcional, si bien simplifican los desarrollos a realizar por el comercio.

                      
       /* Importar el fichero principal de la librería, tal y como se muestra a
continuación: */
include_once 'redsysHMAC256_API_PHP_4.0.2/apiRedsys.php';
//El comercio debe decidir si la importación desea hacerla con la función
“include” o “required”, según los desarrollos realizados.
/* Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación: */
$miObj = new RedsysAPI;
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el cálculo
de este parámetro, inicialmente se deben añadir todos los parámetros de la
petición de pago que se desea enviar, tal y como se muestra a continuación: */
$miObj->setParameter("DS_MERCHANT_AMOUNT", $amount);
$miObj->setParameter("DS_MERCHANT_ORDER", $id);
$miObj->setParameter("DS_MERCHANT_MERCHANTCODE", $fuc);
$miObj->setParameter("DS_MERCHANT_CURRENCY", $moneda);
$miObj->setParameter("DS_MERCHANT_TRANSACTIONTYPE", $trans);
$miObj->setParameter("DS_MERCHANT_TERMINAL", $terminal);
$miObj->setParameter("DS_MERCHANT_MERCHANTURL", $url);
$miObj->setParameter("DS_MERCHANT_URLOK", $urlOK);
$miObj->setParameter("DS_MERCHANT_URLKO", $urlKO);
/*Por último, para calcular el parámetro Ds_MerchantParameters, se debe
llamar a la función de la librería “createMerchantParameters()”, tal y como
se muestra a continuación: */
$params = $miObj->createMerchantParameters();
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio (obteniendola
en el panel del módulo de administración), tal y como se muestra a
continuación: */
$claveSHA256 = 'Mk9m98IfEblmPfrpsawt7Bmx0bt98Je';
$firma = $miObj->createMerchantSignature($claveSHA256);
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters y
Ds_Signature , se debe rellenar el formulario de pago con dichos valores, tal
y como se muestra a continuación: */
<form action="https://sis.redsys.es/sis/realizarPago" method="POST"
target="_blank">
<input type="text" name="Ds_SignatureVersion" value="HMAC_SHA256_V1"/>
<input type="text" name="Ds_MerchantParameters" value="<?php echo $params;
?>"/>
<input type="text" name="Ds_Signature" value="<?php echo $firma; ?>"/>
<input type="submit" value="Realizar Pago"/>
</form>
                      
                      
                      
/* Importar la librería, tal y como se muestra a continuación */
<%@page import = "sis.redsys.api.ApiMacSha256" %>
/* Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación */
ApiMacSha256 apiMacSha256 = new ApiMacSha256();
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el
cálculo de este parámetro, inicialmente se deben añadir todos los
parámetros de la petición de pago que se desea enviar, tal y como se
muestra a continuación: */
apiMacSha256.setParameter("DS_MERCHANT_AMOUNT", amount)
apiMacSha256.setParameter("DS_MERCHANT_ORDER", id)
apiMacSha256.setParameter("DS_MERCHANT_MERCHANTCODE", fuc)
apiMacSha256.setParameter("DS_MERCHANT_CURRENCY", moneda)
apiMacSha256.setParameter("DS_MERCHANT_TRANSACTIONTYPE", trans)
apiMacSha256.setParameter("DS_MERCHANT_TERMINAL", terminal)
apiMacSha256.setParameter("DS_MERCHANT_MERCHANTURL", url)
apiMacSha256.setParameter("DS_MERCHANT_URLOK", urlOK)
apiMacSha256.setParameter("DS_MERCHANT_URLKO", urlKO)
/* Por último se debe llamar a la función de la librería
“createMerchantParameters()”, tal y como se muestra a continuación: */
String params = apiMacSha256.createMerchantParameters()
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio
(obteniendola en el panel del módulo de administración), tal y como se
muestra a continuación: */
String claveSHA256 = "Mk9m98IfEblmPfrpsawt7Bmx0bt98Jev";
String firma = apiMacSha256.createMerchantParameters(claveSHA256);
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters
y Ds_Signature , se debe rellenar el formulario de pago con los valores
obtenidos, tal y como se muestra a continuación: */
<form action="https://sis.redsys.es/sis/realizarPago" method="POST"
target="_blank">
<input type="text" name="Ds_SignatureVersion" value="HMAC_SHA256_V1"/>
<input type="text" name="Ds_MerchantParameters" value= "<%= params
%>"/>
<input type="text" name="Ds_Signature" value= "<%= firma %>"/>
<input type="submit" value= "Realizar Pago"/>
</form>
                      
                      
                          
      /* Importar la librería RedsysAPI y Newronsoft.Json en su proyecto */
<%@ Import namepace="sis.redsys.api.ApiMacSha256" %>
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el cálculo
de este parámetro, inicialmente se deben añadir todos los parámetros de la
petición de pago que se desea enviar, tal y como se muestra a continuación: */
RedsysAPI r = new RedsysAPI()
r.setParameter ("DS_MERCHANT_AMOUNT", amount);
r.setParameter("DS_MERCHANT_ORDER", id);
r.setParameter("DS_MERCHANT_MERCHANTCODE", fuc);
r.setParameter("DS_MERCHANT_CURRENCY", moneda);
r.setParameter("DS_MERCHANT_TRANSACTIONTYPE", trans);
r.setParameter("DS_MERCHANT_TERMINAL", terminal);
r.setParameter("DS_MERCHANT_MERCHANTURL", url);
r.setParameter("DS_MERCHANT_URLOK", urlOK);
r.setParameter("DS_MERCHANT_URLKO", urlKO);
/* Por último se debe llamar a la función de la librería
“createMerchantParameters()” para crear los parámetros y asignar dicho valor a
la etiqueta Ds_MerchantrParameters, tal y como se muestra a continuación: */
string params = r.createMerchantParameters();
Ds_MerchantParameters.value = params;
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de este
parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio (obteniendola en
el panel del módulo de administración), tal y como se muestra a continuación:
*/
string kcSHA256 = 'Mk9m98IfEblmPfrpsawt7BmxObt98Jev';
string firma = r.createMerchantSignature(kcSHA256);
Ds_Signature.value = firma;
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters y
Ds_Signature , se debe rellenar el formulario de pago con los valores
obtenidos, tal y como se muestra a continuación: */
<form action ="https://sis.redsys.es/sis/realizarPago" method="post">
<input runat="server" type="text" id="Ds_SignatureVersion"
name="Ds_SignatureVersion" value="" />
<input runat="server" size="100" type="text" id="Ds_MerchantParameters"
name="Ds_MerchantParameters" value= "" />
<input runat="server" type="text" size="50" id="Ds_Signature" name=
"Ds_Signature" value= "" />
<input runat="server" type= "submit" value = "Realizar Pago" />
</form>
                          
                        
Desarrollo y generación Notificación Síncrona-Asíncrona

La notificación on-line es una función opcional que permite a la tienda web recibir el resultado de una transacción de forma on-line y en tiempo real, una vez que el cliente ha completado el proceso en el TPV virtual. El comercio debe capturar y validar todos los parámetros junto a la firma de la notificación on-line de forma previa a cualquier ejecución en su servidor.

                      
/*Importar el fichero principal de la librería, tal y como se muestra
a continuación. El comercio debe decidir si la importación desea hacerla con la
función “include” o “required”, según los desarrollos realizados.*/
  include_once 'redsysHMAC256_API_PHP_4.0.2/apiRedsys.php'; 

/*Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
  $miObj = new RedsysAPI; 

/*Capturar los parámetros de la notificación on-line:*/
  $version = $_POST["Ds_SignatureVersion"]; 
  $params = $_POST["Ds_MerchantParameters"]; 
  $signatureRecibida = $_POST["Ds_Signature"]; 

/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
  $decodec = $miObj->decodeMerchantParameters($params); 

/*Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
notificación on-line. Para llevar a cabo la obtención del valor de un
parámetro se debe llamar a la función “getParameter()” de la
librería con el nombre de parámetro, tal y como se muestra a
continuación para obtener el código de respuesta:*/
  $codigoRespuesta = $miObj->getParameter("Ds_Response"); 

/** NOTA IMPORTANTE: Para garantizar la seguridad y el
origen de las notificaciones el comercio debe llevar a cabo
la validación de la firma recibida y de todos los parámetros
que se envían en la notificación.*/

/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  $claveModuloAdmin = 'Mk9m98IfEblmPfrpsawt7Bmx0bt98Je'; 
  $signatureCalculada = $miObj->createMerchantSignatureNotif($claveModuloAdmin, $params); 

/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  if ($signatureCalculada === $signatureRecibida) { 
  echo "FIRMA OK. Realizar tareas en el servidor";
  } else { 
  echo "FIRMA KO. Error, firma inválida"; 
  }
                      
                      
                      
/*Importar la librería, tal y como se muestra a continuación:*/
  <%@page import = "sis.redsys.api.ApiMacSha256" %> 
  
/** El comercio debe incluir en la vía de construcción del proyecto
todas las librerías(JARs) que se proporcionan:*/
  

/* Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
  ApiMacSha256 apiMacSha256 = new ApiMacSha256(); 

/* Capturar los parámetros de la notificación on-line: */
  String version = request.getParameter("Ds_SignatureVersion"); 
  String params = request.getParameter("Ds_MerchantParameters"); 
  String signatureRecibida = request.getParameters("Ds_Signature"); 
  
/* Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
  String decodec = apiMacSha256.decodeMerchantParameters(params); 

/* Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
notificación on-line. Para llevar a cabo la obtención del valor de un
parámetro se debe llamar a la función “getParameter()” de la
librería con el nombre de parámetro, tal y como se muestra a
continuación para obtener el código de respuesta:*/
  String codigoRespuesta = apiMacSha256.getParameter("Ds_Response"); 

/**NOTA IMPORTANTE: Para garantizar la seguridad y el
origen de las notificaciones el comercio debe llevar a cabo
la validación de la firma recibida y de todos los parámetros
que se envían en la notificación.*/

/* Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  String claveModuloAdmin = "Mk9m98IfEblmPfrpsawt7Bmx0bt98Je"; 
  String signatureCalculada = apiMacSha256.createMerchantSignatureNotif(claveModuloAdmin, params); 

/* Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  if (signatureCalculada.equals(signatureRecibida)) { 
  System.out.println("FIRMA OK. Realizar tareas en el servidor");
  } else { 
  System.out.println("FIRMA KO. Error, firma inválida"); 
  }
                      
                      
                          
/* Importar la librería RedsysAPI y Newronsoft.Json en su proyecto y, a continuación, se capturan
 los parámetros de la notificación on-line: */
  RedsysAPI  r = new RedsysAPI() 


  if (Request.Form["Ds_SignatureVersion"] != null) { 
  version = Request.Form["Ds_SignatureVersion"]; 
  } 

  if (Request.Form["Ds_MerchantParameters"] != null) { 
  data = Request.Form["Ds_MerchantParameters"]; 
  } 

  if (Request.Form["Ds_Signature"] != null) { 
  signatureReceived = Request.Form["Ds_Signature"]; 
  } 

/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()” que genera
la cadena (tipo string) JSON de la respuesta, tal y como se
muestra a continuación:*/
  string deco = r.decodeMerchantParameters(data);
  
/** NOTA IMPORTANTE: Para garantizar la seguridad y el
origen de las notificaciones el comercio debe llevar a cabo
la validación de la firma recibida y de todos los parámetros
que se envían en la notificación.*/

/* Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  string kc = "Mk9m98IfEblmPfrpsawt7BmxObt98Jev"; 
  string notif  =  r.createMerchantSignatureNotif(kc, data); 

/* Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  string text = ""; 
  if (notif.Equals(signatureReceived) && notif != "") { 
  text = "SIGNATURE OK";
  } else { 
  text = "SIGNATURE KO"; 
  } 
                          
                        
Desarrollo y generación de Retorno del control de la navegación

Una vez que el cliente ha realizado el proceso en el TPV virtual, se redirige la navegación hacia a la tienda web. Este retorno a la web de la tienda se realiza hacia la URL comunicada como parámetro en la llamada inicial al TPV virtual o en su defecto, se obtiene de la configuración del terminal en el módulo de administración del TPV virtual. Se pueden disponer de URLs de retorno distintas según el resultado de la transacción (URL OK y URL KO). El comercio debe capturar y validar, en caso de que la configuración de su comercio así lo requiera (Parámetro en las URLs = SI), los parámetros del retorno de control de navegación previo a cualquier ejecución en su servidor. La utilización de las librerías de ayuda proporcionadas por Redsys para la captura y validación de los parámetros del retorno de control de navegación, se expone a continuación.

                      
/*Importar el fichero principal de la librería, tal y como se muestra
a continuación. El comercio debe decidir si la importación desea hacerla con la
función “include” o “required”, según los desarrollos realizados.*/
  include_once 'redsysHMAC256_API_PHP_4.0.2/apiRedsys.php'; 

/*Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
  $miObj = new RedsysAPI; 
  
/*Capturar los parámetros de la notificación on-line:*/
  $version = $_GET["Ds_SignatureVersion"]; 
  $params = $_GET["Ds_MerchantParameters"]; 
  $signatureRecibida = $_GET["Ds_Signature"]; 

/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
  $decodec = $miObj->decodeMerchantParameters($params); 

/*Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
notificación on-line. Para llevar a cabo la obtención del valor de un
parámetro se debe llamar a la función “getParameter()” de la
librería con el nombre de parámetro, tal y como se muestra a
continuación para obtener el código de respuesta:*/
  $codigoRespuesta = $miObj->getParameters("Ds_Response"); 

/** NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/

/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  $claveModuloAdmin = 'Mk9m98IfEblmPfrpsawt7Bmx0bt98Je'; 
  $signatureCalculada = $miObj->createMerchantSignatureNotif($claveModuloAdmin, $params); 

/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  if ($signatureCalculada === $signatureRecibida) { 
  echo "FIRMA OK. Realizar tareas en el servidor";
  } else { 
  echo "FIRMA KO. Error, firma inválida"; 
  }
                      
                      
                      
/* Importar libreria, tal y como se muestra a continuación: */
  <%@page import="sis.redsys.api.ApiMacSha256" %> 

/*El comercio debe incluir en la vía de construcción del proyecto
todas las librerías(JARs) que se proporcionan:*/
  

/*Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
  ApiMacSha256 apiMacSha256 = new ApiMacSha256(); 

/*Capturar los parámetros del retorno de control de navegación:*/
  String version = request.getParameter("Ds_SignatureVersion"); 
  String params = request.getParameter("Ds_MerchantParameters"); 
  String signatureRecibida = request.getParameters("Ds_Signature"); 

/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
  String decodec = apiMacSha256.decodeMerchantParameters(params);

/*Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
retorno de control de navegación. Para llevar a cabo la obtención del
valor de un parámetro se debe llamar a la función
“getParameter()” de la librería con el nombre de parámetro, tal y
como se muestra a continuación para obtener el código de
respuesta:*/
  String codigoRespuesta = apiMacSha256.getParameter("Ds_Response"); 

/**NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/

/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  String claveModuloAdmin = "Mk9m98IfEblmPfrpsawt7Bmx0bt98Je"; 
  String signatureCalculada = apiMacSha256.createMerchantSignatureNotif(claveModuloAdmin, params); 

/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  if (signatureCalculada.equals(signatureRecibida)) { 
  System.out.println("FIRMA OK. Realizar tareas en el servidor");
  } else { 
  System.out.println("FIRMA KO. Error, firma inválida"); 
  }
                      
                      
                          
/*Importar la librería, tal y como se muestra a continuación:*/
  using RedsysAPIPrj; 

/*Definir un objeto de la clase principal de la librería, tal y como se muestra a
continuación:*/
  RedsysAPI  r = new RedsysAPI() 

/*Capturar los parámetros del retorno de control de navegación:*/
  string version = Request.QueryString["Ds_SignatureVersion"]; 
  string params = Request.QueryString["Ds_MerchantParameters"]; 
  string signatureRecibida = Request.QueryString["Ds_Signature"]; 

/** NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/

/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
  string kc = "Mk9m98IfEblmPfrpsawt7BmxObt98Jev"; 
  string signatureCalculada  =  r.createMerchantSignatureNotif(kc, params); 

/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
  if(signatureRecibida == signatureCalculada) {
    result.InnerHTML = "FIRMA OK. Realizar tareas en el servidor."
  } else {
    result.InnerHTML = "FIRMA KO. Error, firma inválida."
  }

                          
                        

Pago InApp

En esta sección vamos a explicar como integrar el pago en tu propia app móvil. Redsys ofrece dos métodos de pago mediante aplicación móvil, por un lado pago directo y por otro lado WebView.

Configuración

Para realizar este tipo de integración, es necesario tener una configuración previa. Para ello es necesaria la configuración de una serie de parametros, algunos de ellos obligatorios y otros opcionales.


PARÁMETROS OBLIGATORIOS
  • Licencia de la aplicación: Es un código alfanumérico proporcionado por Redsys para validar las aplicaciones que hacen uso de la librería.

  • 							
    TPVVConfiguration.shared.appLicense = "mgVcwQdTzsc58RGmfSRx"
    							
    						
  • Entorno: El entorno se selecciona utilizando las constantes definidas en el objeto de configuración TPVVConfiguration.

    • Integración:
    • 								
      TPVVConfiguration.shared.appEnviroment = "int"
      								
      							
    • Producción:
    • 								
      TPVVConfiguration.shared.appEnviroment = "real"
      								
      							
  • FUC del Comercio: Es un indentificador único del comercio.

  • 								
    TPVVConfiguration.shared.appFuc = "999008881"
    								
    							
  • Terminal: Indica dentro de un mismo comercio el terminal desde el que se realiza la operación.

  • 								
    TPVVConfiguration.shared.appTerminal = "170"
    								
    							
  • Código de la moneda utilizada: En este parámetro se indica el código de la moneda con la que se realiza la operacion. Por defecto, es “978” (euros).

  • 							
    TPVVConfiguration.shared.appCurrency = "978"
    							
    						
PARÁMETROS OPCIONALES
  • Nombre del titular: Este parámetro indica el nombre del titular que realiza el pago.

  • 							
    TPVVConfiguration.shared.appMerchantTitular = "Redsys"
    							
    						
  • Métodos de Pago: Este parámetro permite especificar ciertas formas de pago (con tarjeta, Bizum, Iupay...). Este parámetro debe indicarse únicamente en WebView, en caso de no indicarse se mostrará la página con todas las formas de pago que ofrece el comercio.

  • 							
    TPVVConfiguration.shared.appMerchantPayMethods = "T"
    							
    						
  • Módulo de Pago:

  • 							
    TPVVConfiguration.shared.appMerchantModule = "PSis_Android"
    							
    						
  • URL del comercio: En esta URL se notificará al comercio el resultado de las operaciones (es preciso tener configurado este tipo de notificaciones previamente).

  • 							
    TPVVConfiguration.shared.appMerchantURL = "www.mitienda.es/notificar-pago.php"
    							
    						
  • Nombre del comercio: Este parámetro indica el nombre del comercio, de éste modo si se indica algun nombre se mostrará en la página de pago.

  • 							
    TPVVConfiguration.shared.appMerchantName = "Redsys"
    							
    						
  • Datos adicionales del comercio: En este campo, el comercio puede introducir aquellos datos que considere oportunos (referencias internas, datos propios del negocio). Tras el pago, este campo se le devolverá en la notificación al comercio.

  • 							
    TPVVConfiguration.shared.appMerchantData = "123456"
    							
    						
  • Descripción del comercio:

  • 							
    TPVVConfiguration.shared.appMerchantDescription = "XXX"
    							
    						
  • FUC del grupo de comercio:

  • 							
    TPVVConfiguration.shared.appMerchantGroup = "XX"
    							
    						
Pago directo

Las operaciones de pago directo, se realizan mediante la aplicacion nativa disponible para los sistemas operativos Android e IOs. Este tipo de pago soporta tanto pagos normales como pagos por referencia.

Configuración

Para la integración de este metodo de pago, es preciso realizar algunas configuraciones previas:

Para cada pago es preciso indicar los siguientes campos:

  • orderNumber: Código alfanumérico identificativo de la operación (debe ser único)

  • amount: Importe de la operación

  • identifier: En caso de no indicar nada realiza un pago normal, en de introducir una referencia valida se realiza un pago con referencia, y por último, para realizar un pago con solicitud de referencia hay que utilizar el valor de la constante TPVVConfiguration.shared.REQUEST_REFERENCE

  • productDescription: Descripción del producto

  • transactionType: (Utilizando las constantes definidas en TransactionType)

    • Normal: TransactionType.normal

    • Preautorización: TransactionType.preauthorization

    • Tradicional: TransactionType.traditional

  • uiViewConfig: Configuración de la vista del pago directo.

Personalización

Es posible personalizar algunos aspectos de la pantalla del pago directo tales como el logo, fondo de pantalla, colores y literales.

Para llevar a cabo la configuración de la pantalla del pago directo se hace uso del objeto del tipo TPVInAppUIConfig. Son personalizables los siguientes elementos de la pantalla.

  • Logo (Logo)

  • Color de fondo de pantalla (setBackgroundViewColor)

  • Imagen de fondo de pantalla (setBackgroundImageView)

  • Texto de botón cancelar (setCancelButtonText)

  • Texto de botón Continuar (setContinueButtonText)

  • Texto, color y fuente de número de tarjeta (setNumberCardLabel)

  • Texto color y fuente de fecha de caducidad (setExpireDateLabel)

  • Texto color y fuente de código de seguridad (setCVVLabel)

  • Texto color y fuente de texto descriptivo (setInfoPaymentLabel)

Ejemplos

Ejemplo de implementación de pago directo:

						
let labelCardNumber: PaymentUILabelConfig = PaymentUILabel.create(text: "N.º de tarjeta", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelExpiredDate: PaymentUILabelConfig = PaymentUILabel.create(text: "Caducidad", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelCVC: PaymentUILabelConfig = PaymentUILabel.create(text: "Cód. seguridad", textColor: .black,
textFont: .systemFont(ofSize: 16, weight: .semibold))

let infoPayment: PaymentUILabelConfig = PaymentUILabel.create(text: "Por favor, compruebe que el
número de tarjeta y el resto de datos son exactamente los mismos que aparecen en la tarjeta.",
textColor: .black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let uiConfig = TPVInAppUIConfig()
	.setCancelButtonText("Cancelar")
	.setContinueButtonText("Continuar")
	.setNumberCardLabel(labelCardNumber)
	.setExpireDateLabel(labelExpiredDate)
	.setCVVLabel(labelCVC)
	.setInfoPaymentLabel(infoPayment)
	.setLogo(logo: UIImage(named:"logoEntidad"))
	.setBackgroundImageView(image: UIImage(named:"background"))
	.setBackgorundViewColor(color: .lightGray)
let dpView = DirectPaymentViewController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:
paymentIdentifier, uiViewConfig: uiConfig)

dpView.delegate = self

present(dpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de pago directo solicitando referencia:

						
let labelCardNumber: PaymentUILabelConfig = PaymentUILabel.create(text: "N.º de tarjeta", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelExpiredDate: PaymentUILabelConfig = PaymentUILabel.create(text: "Caducidad", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelCVC: PaymentUILabelConfig = PaymentUILabel.create(text: "Cód. seguridad", textColor: .black,
textFont: .systemFont(ofSize: 16, weight: .semibold))

let infoPayment: PaymentUILabelConfig = PaymentUILabel.create(text: "Por favor, compruebe que el
número de tarjeta y el resto de datos son exactamente los mismos que aparecen en la tarjeta.",
textColor: .black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let uiConfig = TPVInAppUIConfig()
	.setCancelButtonText("Cancelar")
	.setContinueButtonText("Continuar")
	.setNumberCardLabel(labelCardNumber)
	.setExpireDateLabel(labelExpiredDate)
	.setCVVLabel(labelCVC)
	.setInfoPaymentLabel(infoPayment)
	.setLogo(logo: UIImage(named:"logoEntidad"))
	.setBackgroundImageView(image: UIImage(named:"background"))
	.setBackgorundViewColor(color: .lightGray)
	
let dpView = DirectPaymentViewController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:
TPVVConfiguration.shared.REQUEST_REFERENCE, uiViewConfig: uiConfig)

dpView.delegate = self

present(dpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de pago directo usando referencia:

						
let labelCardNumber: PaymentUILabelConfig = PaymentUILabel.create(text: "N.º de tarjeta", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelExpiredDate: PaymentUILabelConfig = PaymentUILabel.create(text: "Caducidad", textColor:
.black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let labelCVC: PaymentUILabelConfig = PaymentUILabel.create(text: "Cód. seguridad", textColor: .black,
textFont: .systemFont(ofSize: 16, weight: .semibold))

let infoPayment: PaymentUILabelConfig = PaymentUILabel.create(text: "Por favor, compruebe que el
número de tarjeta y el resto de datos son exactamente los mismos que aparecen en la tarjeta.",
textColor: .black, textFont: .systemFont(ofSize: 16, weight: .semibold))

let uiConfig = TPVInAppUIConfig()
	.setCancelButtonText("Cancelar")
	.setContinueButtonText("Continuar")
	.setNumberCardLabel(labelCardNumber)
	.setExpireDateLabel(labelExpiredDate)
	.setCVVLabel(labelCVC)
	.setInfoPaymentLabel(infoPayment)
	.setLogo(logo: UIImage(named:"logoEntidad"))
	.setBackgroundImageView(image: UIImage(named:"background"))
	.setBackgorundViewColor(color: .lightGray)
	
let dpView = DirectPaymentViewController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:
self.reference, uiViewConfig: uiConfig)

dpView.delegate = self

present(dpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de la respuesta del pago directo:

Para poder obtener la respuesta de la operación deberá implementar el siguiente delegado DirectPaymentResponseDelegate.

						
extension DirectPaymentTableViewController: DirectPaymentResponseDelegate {
	func responseDirectPaymentKO(response: (DirectPaymentResponseKO)) {
	}
	func responseDirectPaymentOK(response: (DirectPaymentResponseOK)) {
	}
}
						
					
Pago WebView

Las operaciones de pago WebView, se realizan mediante la propia web del comercio, con la única diferencia de que la vista se encuentra adaptada para dispositivos móviles. Este tipo de pago soporta tanto pagos normales como pagos por referencia.

Configuración

Para realizar un pago a través de WebView es necesario haber configurado previamente los parámetros obligatorios en el objeto TPVVConfiguration

Para cada pago es necesario indicar los siguientes campos:

  • orderNumber: Código alfanumérico identificativo de la operación (debe ser único)

  • amount: Importe de la operación

  • identifier: En caso de no indicar nada realiza un pago normal, de introducir una referencia valida se realiza un pago con referencia, y por último, para realizar un pago con solicitud de referencia hay que utilizar el valor de la constante TPVVConfiguration.shared.REQUEST_REFERENCE

  • productDescription: Descripción del producto

  • transactionType: (Utilizando las constantes definidas en TransactionType)

    • Normal: TransactionType.normal

    • Preautorización: TransactionType.preauthorization

    • Tradicional: TransactionType.traditional

Ejemplos

Ejemplo de implementación de pago WebView:

						
let wpView = WebViewPaymentController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:””)

wpView.delegate = self

present(wpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de pago WebView solicitando referencia:

						
let wpView = WebViewPaymentController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:
TPVVConfiguration.shared.REQUEST_REFERENCE)

wpView.delegate = self

present(wpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de pago WebView usando referencia:

						
let wpView = WebViewPaymentController(orderNumber: order, amount: amount.floatValue,
productDescription: productDescription, transactionType: operationTypeValue, identifier:
self.reference)

wpView.delegate = self

present(wpView, animated: true, completion: nil)
						
					

Ejemplo de implementación de la respuesta del pago WebView:

Para poder obtener la respuesta de la operación deberá implementar el siguiente delegado WebViewPaymentResponseDelegate.

						
extension WebViewPaymentTableViewController: WebViewPaymentResponseDelegate {
	func responsePaymentKO(response: (WebViewPaymentResponseKO)) {
	}
	func responsePaymentOK(response: (WebViewPaymentResponseOK)) {
	}
}
						
					
Configuración adicional

En el caso del WebView además es posible configurar el idioma y las url de resultado en caso de que la operación se haya realizado correctamente o con algún error.

TPVVConfiguration.shared.appURLOK = "XXX"

TPVVConfiguration.shared.appURLKO = "XXX"

TPVVConfiguration.shared.appMerchantConsumerLanguage = "X"

En caso de no indicar una URL de resultado, una vez terminada la operación se vuelve al flujo principal de la aplicación sin hacer ninguna redirección. Por otro lado, para los lenguajes hay que indicar un código de idioma válido, en caso de no indicar nada se configura por defecto en español.

Códigos de respuesta
Respuesta pago directo

Para el pago directo (DirectPaymentViewController) tenemos dos objetos respuesta DirectPaymentResponseOK y DirectPaymentResponseKO que contiene los siguientes parámetros:

DirectPaymentResponseOK

						
public var code: Int
public var desc: String
public var Ds_Card_Country: String
public var Ds_Amount:String
public var Ds_MerchantData:String
public var Ds_Currency:String
public var Ds_Order:String
public var Ds_MerchantCode:String
public var Ds_Card_Type:String
public var Ds_Card_Brand:String
public var Ds_AuthorisationCode:String
public var Ds_Language:String
public var Ds_SecurePayment:String
public var Ds_Response:String
public var Ds_TransactionType:String
public var Ds_Terminal:String
public var Ds_ExpiryDate:String
public var Ds_Merchant_Identifier:String
						
					

DirectPaymentResponseKO

						
public var code:Int
public var desc:String
						
					
Respuesta WebView

Para el pago WebView (WebViewPaymentController) temenos dos objetos respuesta WebViewPaymentResponseOK y WebViewPaymentResponseKO que contiene los siguientes parámetros:

WebViewPaymentResponseOK

						
public var code: Int
public var desc: String
public var Ds_Date:String
public var Ds_Hour:String
public var Ds_SecurePayment:String
public var Ds_Amount:String
public var Ds_Currency:String
public var Ds_Order:String
public var Ds_MerchantCode:String
public var Ds_Terminal:String
public var Ds_Response:String
public var Ds_Signature:String
public var Ds_TransactionType:String
public var Ds_MerchantData:String
public var Ds_AuthorisationCode:String
public var Ds_ExpiryDate:String
public var Ds_Merchant_Identifier:String
public var Ds_ConsumerLanguage:String
public var Ds_Card_Country:String
public var Ds_Card_Brand:String
						
					

WebViewPaymentResponseKO

						
public var code: Int
public var desc: String
public var Ds_Date:String
public var Ds_Hour:String
public var Ds_SecurePayment:String
public var Ds_Amount:String
public var Ds_Currency:String
public var Ds_Order:String
public var Ds_MerchantCode:String
public var Ds_Terminal:String
public var Ds_Response:String
public var Ds_Signature:String
public var Ds_TransactionType:String
public var Ds_MerchantData:String
public var Ds_AuthorisationCode:String
public var Ds_ExpiryDate:String
public var Ds_Merchant_Identifier:String
public var Ds_ConsumerLanguage:String
public var Ds_Card_Country:String
public var Ds_Card_Brand:String