Realizar un pago

Es la operación de venta común. La transacción es iniciada por el titular, que está conectado a través de Internet a la página web del comercio durante el proceso de compra, por lo que puede requerir la autenticación del mismo si el comercio está configurado para ello. La transacción es capturada automáticamente por el TPV Virtual y enviada a la entidad emisora, produciendo un cargo inmediato en la cuenta del titular asociado a la tarjeta (crédito o débito). Tras la autorización o denegación al titular de la tarjeta se informará al comercio con el resultado obtenido.

Pero para poder realizar esta operativa, debes preparar una serie de datos y enviarlo a la URL del TPV Virtual para iniciar su procesamiento. En esta página te indicaremos qué pasos debes seguir para poder realizar una autorización. Estos datos deben enviarse codificados en UTF-8 a través de un formulario utilizando el navegador del titular.

Para todas las operaciones se deben enviar tres campos:

CampoTipoDescripción
Ds_MerchantParametersCadenaSon los parámetros de la operación, donde se incorporan los datos básicos de la misma, como el importe, el número de pedido, etcétera… Esta cadena se trata de un JSON con los parámetros que se desea enviar, codificada en base64.
Ds_SignatureCadenaEs la firma de los parámetros enviados. Esta firma permite tener la certeza de que los datos no han sido alterados «en vuelo» y que la operación y sus atributos mantiene su integridad. Tienes más información sobre cómo se calcula aquí.
Ds_SignatureVersionCadenaEs una constante que indica la versión de firma que se está utilizando, en este caso HMAC_SHA512_V1.

Dentro del campo Ds_MerchantParameters, se encuentran todos los parámetros necesarios para procesar la operación. Algunos de ellos son obligatorios, y la operación no podrá continuar si no se envían correctamente, por ello vamos a ver un ejemplo de todos los necesarios para procesar una operación. Tienes más información sobre todos los parámetros que se pueden adjuntar en una operación en la sección del glosario de parámetros.

ParámetroTipo y longitud máximaDescripción
Ds_Merchant_AmountNumérico.
12 posiciones.		Es el importe de la operación, expresado en la unidad fraccionaria más baja que tenga la moneda (por ejemplo en el Euro, en céntimos). Es decir, en el importe no se enviarán decimales, y la moneda enviada determinará el valor real (de nuevo, en Euro: en una operación de 12,49€ se enviaría 1249).
Ds_Merchant_CurrencyNumérico.
3 posiciones.		Es el valor numérico del código ISO-4217 de la moneda que se utilizará en la operación. En el caso del Euro, sería el 978. Tienes la tabla de monedas completa en este enlace.
Ds_Merchant_MerchantCodeNumérico.
9 posiciones.		Es el código FUC asignado a tu comercio y que te debió facilitar BBVA por correo cuando diste de alta tu TPV Virtual.
Ds_Merchant_OrderAlfanumérico.
12 posiciones.		Es el número de pedido que identificará a la orden dentro del Portal de Administración del TPV Virtual y en los informes que puedas obtener en dicho portal. Te recomendamos que tenga más de 4 posiciones para evitar posibles problemas en el proceso de totalización.
Ds_Merchant_TerminalNumérico
3 posiciones.		Es el número de terminal de tu comercio sobre el que vas a operar. Debe estar junto al número de comercio que te envió BBVA y, en la mayoría de casos, es el 001.
Ds_Merchant_TransactionTypeNumérico.
1 posición.		Es el tipo de operación que se va a efectuar. Tienes más información sobre los tipos de operación disponibles en la sección del glosario de parámetros.
Para este tipo de operativa, el valor del parámetro Ds_Merchant_TransactionType deberá ser 0.
Sobre los fragmentos de código

Debes tener en cuenta que los fragmentos de código que vas a ver aquí, son sólo ejemplos de llamadas y respuestas al TPV Virtual, y que no constituyen una guía de cómo realizar las operaciones; ya que, debido a la arquitectura de nuestro sistema, los ejemplos con un número de pedido, una firma, etcétera, no son válidos para poder ser usados más de una vez.
Para cada tipo de integración, tendrás a tu disposición un archivo comprimido con ejemplos para que puedas probar las distintas integraciones con tus propios datos.

Realización de un pago usando una integración vía Redirección

¿Debes cumplir con PCI DSS?
Con este tipo de integración, no tendrás que preocuparte de cumplir con la directiva europea PCI-DSS, ya que el tratamiento de datos de la tarjeta se realiza dentro de nuestros servidores, y ningún dato real de la tarjeta del cliente es procesado por tu sitio web.

En la modalidad de redirección, deberás tener en cuenta que tienes que capturar todos los datos relevantes de la transacción para enviarla al TPV Virtual mediante una petición POST a nuestros servidores. La petición se deberá realizar a una de las siguientes URLs según el entorno donde te encuentres trabajando, ya sea haciendo pruebas en nuestro entorno de Test, o ya en producción en nuestro entorno de Real.

EntornoURL de Conexión
Pruebashttps://sis-t.redsys.es:25443/sis/realizarPago
Realhttps://sis.redsys.es/sis/realizarPago

Envío de la petición al TPV Virtual

Sabiendo los datos que se deben enviar, a continuación se muestra un ejemplo del proceso de envío de datos al TPV Virtual. En nuestro caso vamos a realizar una operación de autenticación por importe de 2,49€, al comercio 999008881 y terminal 001, usando la clave de firma de pruebas. Los datos para realizar pruebas los tienes disponibles en la sección de entornos y datos de pruebas.

En primer lugar, el campo Ds_MerchantParameters se compondría de un JSON con la siguiente información:

Nótese que se incluye un campo llamado Ds_Merchant_MerchantURL. En este campo se indica la URL a la cual se enviará la notificación con el resultado de la operación, que se enviará una vez se haya procesado la misma.

{
    "DS_MERCHANT_ORDER": "00014338z744",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "001",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_AMOUNT": "249",
    "DS_MERCHANT_MERCHANTURL": "http://www.prueba.com/urlNotificacion.php",
    "DS_MERCHANT_URLOK": "http://www.prueba.com/urlOK.php",
    "DS_MERCHANT_URLKO": "http://www.prueba.com/urlKO.php"
}

Los parámetros Ds_Merchant_URLOK y Ds_Merchant_URLKO son la distintas URLs hacia donde se enviará al cliente cuando finalice la operación en nuestro sistema. Puedes configurar desde el Portal de Administración del TPV Virtual, que en estas URLs se envíe también el resultado de la operación, para que así puedas mostrarle al cliente, el importe, número de pedido, etc… en la pantalla de información. Recuerda que siempre se enviará la notificación a la URL que hayas configurado en Ds_Merchant_MerchantURL independientemente de que indiques o no URLs de OK y de KO.

El objeto JSON resultante, deberás codificarlo en base64, tal cual lo tienes. Consiguiendo un resultado parecido al siguiente:

ew0KCSJEU19NRVJDSEFOVF9PUkRFUiI6ICIxNTUyNTY1ODcwIiwNCgkiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjogIjk5OTAwODg4MSIsDQoJIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5OSIsDQoJIkRTX01FUkNIQU5UX0NVUlJFTkNZIjogIjk3OCIsDQoJIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6ICIwIiwNCgkiRFNfTUVSQ0hBTlRfQU1PVU5UIjogIjEwMDAiLA0KCSJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsTm90aWZpY2FjaW9uLnBocCIsDQoJIkRTX01FUkNIQU5UX1VSTE9LIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxPSy5waHAiLA0KCSJEU19NRVJDSEFOVF9VUkxLTyI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsS08ucGhwIg0KfQ==

Posteriormente, deberás firmar esta cadena siguiendo los pasos de creación de firma, usando la clave de firma del comercio. La cadena resultante será el campo Ds_Signature. Por último, se adjuntará a la petición la versión del algoritmo de firma a usar en el campo Ds_SignatureVersion, en este caso HMAC_SHA512_V1. Como resultado, obtendremos finalmente un formulario HTML como el que se muestra, y que se deberá enviar vía HTTP POST a la URL del TPV Virtual tal y como se indica en la línea resaltada.

<form name="from" action="https://sis-t.redsys.es:25443/sis/realizarPago" method="POST">
    <input type="hidden" name="Ds_SignatureVersion" 
        value="HMAC_SHA512_V1" />
    <input type="hidden" name="Ds_MerchantParameters"
        value="ew0KCSJEU19NRVJDSEFOVF9PUkRFUiI6ICIxNTUyNTY1ODcwIiwNCgkiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjogIjk5OTAwODg4MSIsDQoJIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5OSIsDQoJIkRTX01FUkNIQU5UX0NVUlJFTkNZIjogIjk3OCIsDQoJIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6ICIwIiwNCgkiRFNfTUVSQ0hBTlRfQU1PVU5UIjogIjEwMDAiLA0KCSJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsTm90aWZpY2FjaW9uLnBocCIsDQoJIkRTX01FUkNIQU5UX1VSTE9LIjogImh0dHA6Ly93d3cucHJ1ZWJhLmNvbS91cmxPSy5waHAiLA0KCSJEU19NRVJDSEFOVF9VUkxLTyI6ICJodHRwOi8vd3d3LnBydWViYS5jb20vdXJsS08ucGhwIg0KfQ==" />
    <input type="hidden" name="Ds_Signature"
        value="jjOJG1r+p97D3J3rohfgAkJDLDXqnILQwxn+YlEGjEUTRaLqUgeQrnmAxhZHwlSo/xpy/hplNWSOcrnrlPnFrQ==" />
</form>

Respuesta del TPV Virtual

Una vez realizada la petición utilizando el navegador del cliente que está comprando en tu sitio Web, nuestro servidor tomará el control de la navegación del cliente, mostrando una serie de pantallas para poder introducir los datos de su tarjeta y autenticarse, así como los datos de la operación para que pueda saber, por ejemplo, por valor de cuánto importe está realmente comprando.

Cuando este proceso haya terminado, ocurrirán dos cosas: primero de todo, se enviará una notificación HTTP POST a la URL que el comercio especificó en el parámetro Ds_Merchant_MerchantURL que contendrá los detalles de la operación y el resultado de la misma. Posteriormente, el cliente será devuelto automáticamente o cuando pulse «continuar», según sea la configuración de tu TPV Virtual, a tu página web y, con esta redirección a tu Web, se acompañará si así lo has solicitado a BBVA, los datos de la operación por vía HTTP GET para que puedas presentar en tu front el resultado de la operación a tu cliente si tienes personalizada la página de vuelta o los valores de URLOK y URLKO.

Tratamiento de la notificación HTTP POST

Nuestro servidor no enviará una notificación en caso de que se produzca un error con los parámetros de entrada, o lo que es lo mismo, en caso de que los parámetros básicos de una operación que debes envíar a nuestro servidor (número de pedido, firma, importe, moneda,…) esté mal formado o se produzca un error (número de pedido repetido, error de firma,…) no recibirás respuesta alguna de la petición. Por ello, te recomendamos que pruebes todos los casos de uso de tu sistema para cerciorarte de que no se producen este tipo de errores ya que, una vez en producción, no tendrás forma de saber que se están produciendo salvo que te notifiquen tus clientes, que sí estarán viendo una pantalla de error parecida a esta:

En caso de que todo vaya correctamente, nuestro servidor responderá con un formulario exactamente igual que el que enviaste, que contiene Ds_MerchantParameters, Ds_Signature y Ds_SigantureVersion. Te recomendamos que, antes de realizar cualquier acción, firmes los parámetros recibidos siguiendo nuestra guía de firma y compruebes que la firma que has calculado y la que has recibido de nuestro servidor coinciden, para así estar seguro que los datos no han sido interceptados y modificados en el camino.

Una vez hecho, procede a descodificar el campo Ds_MerchantParameters que has recibido en base64, para encontrar dentro de estos los parámetros de la operación, con algún campo más. El más importante, el campo Ds_Response, que indica el resultado de la operación de manera numérica: si en él se recibe 0000, significa que la operación ha ido correctamente, en cualquier otro caso, indicará el código de error.

Deberás utilizar la información incluida en la notificación HTTP POST para validar el pedido y realizar los procedimientos que creas oportunos en tu web ya que, a partir de este punto, el control de la gestión del pedido es todo tuyo.

{
	"Ds_Date": "10%2F12%2F2019",
	"Ds_Hour": "09%3A41",
	"Ds_SecurePayment": "0",
	"Ds_Card_Type": "D",
	"Ds_Card_Country": "724",
	"Ds_Amount": "1000",
	"Ds_Currency": "978",
	"Ds_Order": "1575967259",
	"Ds_MerchantCode": "999008881",
	"Ds_Terminal": "1",
	"Ds_Response": "0000",
	"Ds_MerchantData": "",
	"Ds_TransactionType": "0",
	"Ds_ConsumerLanguage": "1",
	"Ds_AuthorisationCode": "372663",
	"Ds_Card_Brand": "2"
}

Tratamiento del retorno de navegación y datos recibidos vía HTTP GET

¡Tenlo en cuenta!
Te recomendamos que nunca utilices los datos enviados vía HTTP GET para validar tu pedido, y que utilices sólo los enviados en la notificación HTTP POST tal y como se ha explicado anteriormente; ya que el cliente podría cerrar la pantalla de pago una vez vea que la operación se ha realizado correctamente y nunca sabrías el resultado de la operación.

Cuando la operación se complete en nuestro servidor, el cliente podrá ver un cuadro de confirmación de la operación, denominado «Recibo Redsys», y que será muy parecido a este:

Una vez que el cliente ha realizado el proceso de pago, al pulsar sobre «Continuar», se le redirigirá de nuevo a tu tienda usando la URL comunicada como parámetro en la llamada inicial al TPV Virtual o, en su defecto, se obtendrá la configuración del Módulo de Administración del TPV Virtual.

Recuerda que si lo deseas puedes solicitar a BBVA eliminar esta pantalla de recibo y redirigir directamente a tu tienda.

  • Ten en cuenta que, si no estableces una URLOK y URLKO, ya sea enviándolas en la petición o directamente en el Portal de Administración del TPV Virtual, cuando tu cliente pulse sobre continuar en el recibo de la operación, se cerrará la ventana donde se encuentra ya que no hay ningún punto a donde redirigir.
  • Si usas URLOK y URLKO, en cada una de ellas deberás decidir como se realiza el flujo, por ejemplo mostrando una pantalla de información con los datos del pedido en URLOK y una pantalla de error y un botón de volver al carrito en URLKO. Si tuvieras configuradas estas URLs en el Portal de Administración del TPV Virtual, se cogerá la información de este lugar y, si además las envías en la petición al TPV Virtual, serán las que envíes las que tendrán preferencia sobre las configuradas en el Portal de Administración del TPV Virtual.

Realización de un pago usando una integración vía REST

¿Debes cumplir con PCI DSS?
Pues depende. En este caso, en el que vas a realizar un pago (autorización) utilizando una integración REST, sí debes cumplir con la directiva PCI DSS, ya que vas a capturar directamente datos de tarjeta y, por tanto, técnicamente vas a manejar dichos datos. Si por el contrario realizases otro tipo de operativa como una devolución o una confirmación, no tendrías que cumplir con esta directiva, ya que no estarías tratando directamente con datos de las tarjetas de tus clientes.

Este tipo de conexión resulta útil para aquellos comercios que quieren que la experiencia de navegación de sus compradores sea continua y no abandonen en ningún momento la web, ni siquiera a la hora de realizar el pago. Además, este tipo de integración permite tomar un control total del flujo de pago, a costa de ser algo más complicada de integrar.

Si quieres utilizar este modo de conexión, deberás ser autorizado por BBVA; además, deberás tener validado el cuestionario PCI-DSS, ya que vas a tratar los datos de tarjeta del titular. Tanto en el envío de datos para la petición, como la respuesta del TPV, serán parecidos a la integración por redirección.

El siguiente esquema te ayudará a comprender el proceso de una operación REST. En este esquema, «SIS» se refiere a tu TPV Virtual y «ACS» al servidor de autenticación, que es el encargado de dibujar todos los elementos de la autenticación y de confirmar si esta es correcta.

Solicitud de información de la tarjeta · iniciaPeticion

El primer paso durante una autorización vía REST, es la solicitud de datos de tarjeta. Internamente, a este proceso se le llama iniciaPetición, y deberás realizar una solicitud REST a la URL de conexión que corresponda según el entorno en el que te encuentres trabajando.

EntornoURL de Conexión
Pruebashttps://sis-t.redsys.es:25443/sis/rest/iniciaPeticionREST
Realhttps://sis.redsys.es/sis/rest/iniciaPeticionREST

En esta transacción, estás solicitando al TPV Virtual información sobre la capacidad de la tarjeta en cuanto a autenticación (versión del protocolo 3D Secure), posibilidad de aplicación de exenciones, poder realizar operativas especiales, como por ejemplo DCC; etcétera. Esta información indicará como deben gestionarse los siguientes pasos para realizar la operación.

Para iniciar la transacción, enviarás a la URL que corresponda según el entorno en el que estás trabajando, los datos de la operación codificados en base64 dentro del objeto Ds_Merchant_MerchantParameters, junto a la firma y a la versión de firma. El objeto que enviarás debería tener un aspecto parecido al que sigue.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6MTY3NTg2MTcyMSwiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjoiOTk5MDA4ODgxIiwiRFNfTUVSQ0hBTlRfVEVSTUlOQUwiOiIxIiwiRFNfTUVSQ0hBTlRfVFJBTlNBQ1RJT05UWVBFIjoiMCIsIkRTX01FUkNIQU5UX1BBTiI6IjQ1NDg4MTAwMDAwMDAwMDMiLCJEU19NRVJDSEFOVF9FWFBJUllEQVRFIjoiNDkxMiIsIkRTX01FUkNIQU5UX0NWVjIiOiIxMjMiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX0FNT1VOVCI6IjAwMDAwMDIwMDAiLCJEU19NRVJDSEFOVF9FTVYzRFMiOiJ7XCJ0aHJlZURTSW5mb1wiOlwiQ2FyZERhdGFcIn0iLCJEU19NRVJDSEFOVF9FWENFUF9TQ0EiOiJZIn0=",
    "Ds_Merchant_Signature": "b0ZLxasugdPfKg09di+ucrPWre1FVmGXle+BebNylS7/vkJGioMP907kpFwgOniMHS6mOMmuqR2beB2i5oIeyw==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_PAN": "4548810000000003",
    "DS_MERCHANT_EXPIRYDATE": "4912",
    "DS_MERCHANT_CVV2": "123",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_AMOUNT": "0000002000",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "CardData"
    },
    "DS_MERCHANT_EXCEP_SCA": "Y"
}

Como puedes comprobar, la estructura de la petición es parecida a la que has visto hasta ahora, pero se añaden varios campos de interés que aparecen resaltados:

  • Ds_Merchant_EMV3DS: Y más concretamente threeDSInfo. En este campo, estás especificando al TPV Virtual que solicitas información de la tarjeta que has enviado en la petición.
  • DS_Merchant_EXCEP_SCA: Aquí estás solicitando que también se te envíe las exenciones que soporta la tarjeta, en caso de que necesitases utilizar una.
Sobre las exenciones de SCA
Puedes consultar todas las exenciones disponibles en la página de información de PSD2 y Autenticación reforzada (SCA).

Enviada la petición, nuestro servidor (en adelante, el SIS), responderá con los datos solicitados si todo ha ido correctamente. En caso de que se produjera un error, la respuesta sería un objeto con un campo errorCode que contendría el código de error que se ha producido y que puedes consultar en la tabla de errores.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19UcmFuc2FjdGlvblR5cGUiOiIwIiwiRHNfRU1WM0RTIjp7InByb3RvY29sVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJkNzQzM2MyZC1mNDRkLTQ4ZGEtYTNhMy1lODgzZjZhODJmZTkiLCJ0aHJlZURTSW5mbyI6IkNhcmRDb25maWd1cmF0aW9uIn0sIkRzX0V4Y2VwX1NDQSI6IkxXVjtUUkFbMzAuMF07Q09SO01JVDtBVEQiLCJEc19DYXJkX1BTRDIiOiJZIn0=",
    "Ds_Signature": "4thE_dbWXdKIapGQVO2NbGhVHCOixzKT9pz42LGKPqrc5c6Le7UhVvGdGgQyfeHoXpvoCFsl_aGyUTQj_cgRvQ=="
}
{
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_TransactionType": "0",
    "Ds_EMV3DS": {
        "protocolVersion": "2.2.0",
        "threeDSServerTransID": "d7433c2d-f44d-48da-a3a3-e883f6a82fe9",
        "threeDSMethodURL": "https://sis-d.redsys.es:25443/sis-simulador-web/threeDsMethod.jsp",
        "threeDSInfo": "CardConfiguration"
    },
    "Ds_Excep_SCA": "LWV;TRA[30.0];COR;MIT;ATD",
    "Ds_Card_PSD2": "Y"
}

En la petición, puedes ver unos parámetros algo más raros en los MerchantParameters descodificados. En cuanto a EMV3DS, encontramos:

  • protocolVersion: Esta es la versión de 3DSecure que soporta la tarjeta. En este caso, deberás emplear un flujo para 3DSecure V2.
  • threeDSServerTransID: Es el identificador de la transacción 3DSecure, y lo necesitarás más adelante. Es único para la operación.
  • threeDSMethodURL: URL para la ejecución del 3DSMethod.
  • threeDSInfo: Esto indica que la respuesta contiene los datos de la tarjeta, es decir, lo que has solicitado.

Y respecto a las exenciones y enrolamiento de la tarjeta:

  • DS_Excep_SCA: Son todas las exenciones que soporta la tarjeta.
  • Ds_Card_PSD2: Informa sin la tarjeta está enrolada en PSD2, y con una «Y» como respuesta, quiere decir que sí.

Ejecución del 3DSMethod para evaluación avanzada del riesgo

El 3DSMethod es un proceso que permite a la entidad emisora capturar la información del dispositivo que está utilizando el titular, al fin de aportar más información para evaluar el riesgo de la transacción. Este proceso es opcional, pero altamente recomendable pues su realización puede mejorar la tasa de conversión al aumentar significativamente el porcentaje de autenticaciones frictionless en tu comercio.

La captura de datos del dispositivo se realiza mediante un iframe oculto que tendrás que ejecutar durante el proceso de pago, que establecerá conexión directamente con la entidad emisora de forma transparente para el usuario. Haber recibido en la respuesta del iniciaPeticion el parámetro threeDSMethodURL es requisito indispensable para realizar este procedimiento, por lo que tendrás que evaluar esta casuística al evaluar la respuesta del iniciaPeticion.

Se ha estructurado la manera en la que se presenta este proceso en tarjetas para facilitar su comprensión pues, aunque es un proceso relativamente sencillo, su ejecución y entendimiento puede ser algo lioso.

1. Prerrequisitos

Para realizar el 3DSMethod, necesitas dos parámetros que tienen que llegar en la respuesta al realizar el procedimiento de iniciaPeticion. Estos parámetros son:

  • threeDSServerTransID: Es el identificador de la transacción EMV3DS.
  • threeDSMethodURL: Es la URL para realizar el 3DSMethod.

Si en la respuesta no llegase el parámetro threeDSMethodURL, el proceso puede finalizar. En el envío de la operación, adjunta el parámetro theeDSCompInd con el valor «N».

2. Construcción del objeto JSON con los parámetros necesarios
3. Creación del iframe oculto en el navegador del cliente
4. Evaluación del resultado del 3DSMethod

Envío de la petición al TPV Virtual · Primer trataPeticion

Una vez se han obtenido los datos de la tarjeta con la que el titular va a realizar la compra, es el momento de enviar la operación al TPV Virtual para iniciar el proceso de autenticación. Tal y como respondió el TPV Virtual en este ejemplo (y como van a ser la gran mayoría de las veces), vas a tener que realizar un proceso de autenticación EMV3DS V2.

Para ello, tienes que preparar la operación de nuevo. Es muy importante que todos los datos básicos de la operación y, sobre todo, el número de pedido sea el mismo, de lo contrario la operación no podrá continuar. Además, se adjuntará dentro del parámetro Ds_Merchant_EMV3DS, un objeto JSON con los parámetros del navegador junto a los parámetros threeDSInfo y protocolVersion. Estos parámetros puedes obtenerlos manualmente o usando nuestras librerías de integración.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6IjE2NzU4NjE3MjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiIwIiwiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiI5NzgiLCJEU19NRVJDSEFOVF9QQU4iOiI0NTQ4ODEwMDAwMDAwMDAzIiwiRFNfTUVSQ0hBTlRfRVhQSVJZREFURSI6IjQ5MTIiLCJEU19NRVJDSEFOVF9BTU9VTlQiOiIyMDAwIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyIsIkRTX01FUkNIQU5UX0VNVjNEUyI6IntcInRocmVlRFNJbmZvXCI6XCJBdXRoZW50aWNhdGlvbkRhdGFcIixcInByb3RvY29sVmVyc2lvblwiOlwiMi4yLjBcIixcImJyb3dzZXJKYXZhc2NyaXB0RW5hYmxlZFwiOlwidHJ1ZVwiLFwiYnJvd3NlckFjY2VwdEhlYWRlclwiOlwidGV4dFwvaHRtbCxhcHBsaWNhdGlvblwveGh0bWwreG1sLGFwcGxpY2F0aW9uXC94bWw7cT0wLjksKlwvKjtxPTAuOCxhcHBsaWNhdGlvblwvanNvblwiLFwiYnJvd3NlclVzZXJBZ2VudFwiOlwiTW96aWxsYVwvNS4wIChXaW5kb3dzIE5UIDEwLjA7IFdpbjY0OyB4NjQpIEFwcGxlV2ViS2l0XC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWVcLzcxLjAuMzU3OC45OCBTYWZhcmlcLzUzNy4zNlwiLFxyXG5cdFx0XHRcdFx0XHRcdFwidGhyZWVEU1NlcnZlclRyYW5zSURcIjpcImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOVwiLFwiYnJvd3NlckphdmFFbmFibGVkXCI6XCJmYWxzZVwiLFwiYnJvd3Nlckxhbmd1YWdlXCI6XCJFUy1lc1wiLFwiYnJvd3NlckNvbG9yRGVwdGhcIjpcIjI0XCIsXCJicm93c2VyU2NyZWVuSGVpZ2h0XCI6XCIxMjUwXCIsIFwiYnJvd3NlclNjcmVlbldpZHRoXCI6XCIxMzIwXCIsXCJicm93c2VyVFpcIjpcIjUyXCIsXCJub3RpZmljYXRpb25VUkxcIjpcImh0dHBzOlwvXC9zaXMtZC5yZWRzeXMuZXNcL3Npcy1zaW11bGFkb3Itd2ViXC9TaXNSRVNUQ3JlcUNyZXNfM0RTZWN1cmVWMi5qc3BcIn0ifQ==",
    "Ds_Merchant_Signature": "EbCFBgZNK9GGO+mCjMCXVT+KYOj1DOO8RB9Y9cnw+daYZoFZLYU34UxEqo8QNpIA6tKKPnUJ4HzDwzyfKEvlvQ==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_PAN": "4548810000000003",
    "DS_MERCHANT_EXPIRYDATE": "4912",
    "DS_MERCHANT_AMOUNT": "2000",
    "DS_MERCHANT_CVV2": "123",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "AuthenticationData",
        "protocolVersion": "2.2.0",
        "browserJavascriptEnabled": "true",
        "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8,application/json",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
        "threeDSServerTransID": "d7433c2d-f44d-48da-a3a3-e883f6a82fe9",
        "browserJavaEnabled": "false",
        "browserLanguage": "ES-es",
        "browserColorDepth": "24",
        "browserScreenHeight": "1250",
        "browserScreenWidth": "1320",
        "browserTZ": "52",
        "threeDSCompInd": "Y",
        "notificationURL": "https://sis-d.redsys.es/sis-simulador-web/SisRESTCreqCres_3DSecureV2.jsp"
    }
}

Tal y como puedes comprobar en los parámetros descodificados, el campo Ds_Merchant_EMV3DS tiene en este caso un JSON con muchos más campos de lo habitual. Los importantes son los dos primeros y el último, ya que el resto de los campos, son los datos extraídos del navegador del cliente.

  • threeDSInfo: En este caso estamos solicitando datos para la autenticación del titular de la tarjeta que enviamos.
  • protocolVersion: La versión del protocolo EMV3DS de la tarjeta, que se nos notificó en el paso anterior.
  • threeDSCompInd: Resultado obtenido del 3DSMethod.
  • notificationURL: Una vez finalizado el challenge, la entidad emisora enviará el resultado al comercio, haciendo un HTTP POST a esta URL.

Una vez enviemos estos datos, el SIS nos devolverá una respuesta parecida a la que sigue.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19BbW91bnQiOiIyMDAwIiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19UcmFuc2FjdGlvblR5cGUiOiIwIiwiRHNfRU1WM0RTIjp7InRocmVlRFNJbmZvIjoiQ2hhbGxlbmdlUmVxdWVzdCIsInByb3RvY29sVmVyc2lvbiI6IjIuMi4wIiwiYWNzVVJMIjoiaHR0cHM6Ly9zaXMtZC5yZWRzeXMuZXMvc2lzLXNpbXVsYWRvci13ZWIvYXV0aGVudGljYXRpb25SZXF1ZXN0LmpzcCIsImNyZXEiOiJleUowYUhKbFpVUlRVMlZ5ZG1WeVZISmhibk5KUkNJNkltUTNORE16WXpKa0xXWTBOR1F0TkRoa1lTMWhNMkV6TFdVNE9ETm1ObUU0TW1abE9TSXNJbUZqYzFSeVlXNXpTVVFpT2lKbVlqTm1NMk5qTUMwNVpEUXpMVFJtWVRFdE9HVXdNaTFqWkdKa05HTmxZVFpoTXpRaUxDSnRaWE56WVdkbFZIbHdaU0k2SWtOU1pYRWlMQ0p0WlhOellXZGxWbVZ5YzJsdmJpSTZJakl1TWk0d0lpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBMUluMCJ9fQ==",
    "Ds_Signature": "c1GTYUGmwJEY3HJ-ePjRUAU6uqHuf-a03MPvt_ChJ-s_OBHCK_aMeAaGiFvlKnh3Kx_YUkYHQ6730lrgb4krIA=="
}
{
    "Ds_Amount": "2000",
    "Ds_Currency": "978",
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_TransactionType": "0",
    "Ds_EMV3DS": {
        "threeDSInfo": "ChallengeRequest",
        "protocolVersion": "2.2.0",
        "acsURL": "https://sis-d.redsys.es/sis-simulador-web/authenticationRequest.jsp", //URL QUE TE HA ENVIADO EL SIS DONDE DEBES ENVIAR EL CREQ
        "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
    }
}

En la respuesta del TPV Virtual, se debe analizar el contenido del parámetro Ds_EMV3DS:

  • threeDSInfo: En este caso nos informa de que la operación requiere autenticación de titular, conocido como Challenge.
  • acsURL: Es la URL donde deberás enviar la petición de autenticación del titular, el CREQ.
  • creq: De ChallengeRequest, es el valor que debes enviar a la URL del ACS (servidor de autenticación).

Resultados alternativos: frictionless y KO

Es posible que en la respuesta, no se te envíe challengeRequest, ni acsURL ni CREQ, sino que directamente se te muestre el resultado de la operación con un código de autorización y Ds_Response con valor 0000 (OK). En este caso, se ha producido lo que se denomina una autenticación frictionless, es decir, el servidor de autenticación ha considerado tener datos suficientes para identificar al titular y autorizar la operación. La respuesta, en ese caso, sería parecida a la que sigue.

Cuando se produce una autorización frictionless, el diagrama de flujo de la operación es similar al que se muestra a continuación.

{
    "Ds_MerchantParameters": "eyJEc19EYXRlIjoiMDklMkYwMiUyRjIwMjMiLCJEc19Ib3VyIjoiMTclM0EwOSIsIkRzX1NlY3VyZVBheW1lbnQiOiIxIiwiRHNfQW1vdW50IjoiMTQ1IiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjExMTIiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjAwMSIsIkRzX1Jlc3BvbnNlIjoiMDAwMCIsIkRzX1RyYW5zYWN0aW9uVHlwZSI6IjAiLCJEc19NZXJjaGFudERhdGEiOiIlMjZWaWFqZXMlMEElMDklMDklMDklMDklMDklMDklMDlNYWwlMEElMDklMDklMDklMDklMDklMDklMDlkaXZhcyIsIkRzX0F1dGhvcmlzYXRpb25Db2RlIjoiMjkxODU2IiwiRHNfQ2FyZF9OdW1iZXIiOiI0OTE4MDEqKioqKio0NjAyIiwiRHNfQ29uc3VtZXJMYW5ndWFnZSI6IjEiLCJEc19DYXJkX0NvdW50cnkiOiI3MjQiLCJEc19DYXJkX0JyYW5kIjoiMSIsIkRzX1Byb2Nlc3NlZFBheU1ldGhvZCI6IjgwIiwiRHNfQ29udHJvbF8xNjc1OTU4OTk1MzcxIjoiMTY3NTk1ODk5NTM3MSJ9",
    "Ds_Merchant_Signature": "KYp3cC6-6I7o3T_S2uhOasbmIajgpAsjIUlH2yiAQKUEhh_zu89ARRHCmHA6NvuSOeAoJcnFBtYpTdVf8Q_kNQ==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "Ds_Date": "09%2F02%2F2023",
    "Ds_Hour": "17%3A09",
    "Ds_SecurePayment": "1",
    "Ds_Amount": "145",
    "Ds_Currency": "978",
    "Ds_Order": "1112",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "001",
    "Ds_Response": "0000",
    "Ds_TransactionType": "0",
    "Ds_AuthorisationCode": "291856",
    "Ds_Card_Number": "491801******4602",
    "Ds_ConsumerLanguage": "1",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_ProcessedPayMethod": "80",
    "Ds_Control_1675958995371": "1675958995371"
}

En este caso puedes analizar el Ds_Response, y comprobar que, si su valor es 0000, la operación ha finalizado correctamente.

Por el contrario, si el Ds_Response que recibes es distinto a 0000, por ejemplo 0190; quiere decir que no se ha realizado la autenticación y se ha producido algún error durante la operación. Deberás consultar la tabla de errores para averiguar qué error se ha producido.

Proceso de autenticación

Para realizar la autenticación, tienes que usar el parámetro CREQ que te envió el SIS, y remitirlo a la URL del servidor de autenticación que te llegó en el parámetro acsURL. Esto deberás hacerlo, por ejemplo, vía HTTP POST a la URL especificada.

<form name="frm" action="https://sis-d.redsys.es/sis-simulador-web/authenticationRequest.jsp" method="POST"
    target="_blank">

    <input type="text" name="creq"
        value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0" />
    <input type="submit" 
        value="Realizar Pago" />
        
</form>

Cabe destacar en este punto, que debes estar preparado para mostrar una pantalla al titular que muestra el estado del servidor de autenticación y los pasos que debe seguir. En esa pantalla se muestran las instrucciones para realizar la autenticación, como poner el código que le ha llegado por SMS, aceptar la operación en su aplicación del banco, etcétera. La pantalla del ACS se parece a la siguiente en nuestro entorno de TEST, pero puede tener diversos aspectos una vez en producción en función de la marca y del tipo de challenge.

Para mostrar la pantalla, te mostramos un ejemplo de cómo hacerlo en PHP, pero puedes extrapolar esta muestra a cualquier lenguaje ya que, como puedes observar, sólo se está cargando un iframe enviando los elementos pedidos para mostrar la pantalla y se usa un fragmento en JavaScript para auto-enviar el formulario.

<? php

function redirect_to_acs() {

	$form='<iframe name="redsys_iframe_acs" name="redsys_iframe_acs" src=""
	id="redsys_iframe_acs" target="_parent" referrerpolicy="origin"
	sandbox="allow-same-origin allow-scripts allow-top-navigation allow-forms"
	height="95%" width="100%" style="border: none; display: none;"></iframe>

	<form name="redsysAcsForm" id="redsysAcsForm"
		action="'. $urlACS .'" method="POST"
		target="redsys_iframe_acs" style="border: none;">
		<table name="dataTable" border="0" cellpadding="0">
			<input type="hidden" name="creq"
				value="'. $creq .'">
			<br>
			<p style="font-family: Arial; font-size: 16; font-weight: bold; color: black; align: center;">
				Conectando con el emisor...
			</p>
		</table>
	</form>
			
	<script>
		window.onload = function () {
			document.getElementById("redsys_iframe_acs").onload = function() {
				document.getElementById("redsysAcsForm").style.display="none";
				document.getElementById("redsys_iframe_acs").style.display="inline";
			}
			document.redsysAcsForm.submit();
		}
	</script>';

	die($form);
}

Cuando el proceso de autenticación finalice, el ACS enviará el parámetro CRES a la URL que especificaste en notificationURL en el primer trataPeticion. Lo notificará utilizando un HTTP POST y tendrás que recogerlo para enviarlo en el siguiente paso de nuevo al TPV Virtual. Ten en cuenta que este parámetro puede tardar en llegar, en función de lo que tarde el titular en autenticarse, por lo que te recomendamos que si vas a configurar un timeout, seas generoso con el tiempo que pones (normalmente el ACS suele tener un timeout de 7 minutos).

Envío del resultado de la autenticación · Segundo trataPeticion

Cuando has recibido el parámetro CRES de parte del ACS, deberás iniciar un segundo trataPeticion a la URL que corresponda, que son las mismas que en el primer trataPeticion. De nuevo, debes cuidar de que los parámetros principales de la operación sean idénticos y no hayan cambiado, de lo contrario, la operación se cancelará. En esta nueva petición deberás adjuntar en el Ds_Merchant_EMV3DS el CRES que has recibido.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6IjE2NzU4NjE3MjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiIwIiwiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiI5NzgiLCJEU19NRVJDSEFOVF9QQU4iOiI0NTQ4ODEwMDAwMDAwMDAzIiwiRFNfTUVSQ0hBTlRfRVhQSVJZREFURSI6IjQ5MTIiLCJEU19NRVJDSEFOVF9BTU9VTlQiOiIyMDAwIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyIsIkRTX01FUkNIQU5UX0VNVjNEUyI6IntcInRocmVlRFNJbmZvXCI6XCJDaGFsbGVuZ2VSZXNwb25zZVwiLFwicHJvdG9jb2xWZXJzaW9uXCI6XCIyLjIuMFwiLFxyXG5cdFwiY3Jlc1wiOlwiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJbVEzTkRNell6SmtMV1kwTkdRdE5EaGtZUzFoTTJFekxXVTRPRE5tTm1FNE1tWmxPU0lzSW1GamMxUnlZVzV6U1VRaU9pSm1Zak5tTTJOak1DMDVaRFF6TFRSbVlURXRPR1V3TWkxalpHSmtOR05sWVRaaE16UWlMQ0p0WlhOellXZGxWSGx3WlNJNklrTlNaWE1pTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEhKaGJuTlRkR0YwZFhNaU9pSlpJbjA9XCJ9In0=",
    "Ds_Merchant_Signature": "TC8y92FhwU7HAK905XOUV/aJC5aBK94h2azzeurPViEy5EFc0XNYUTD2Nj+jGMdiItYa4eaxIIW42dyI6kB1yw==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_PAN": "4548810000000003",
    "DS_MERCHANT_EXPIRYDATE": "4912",
    "DS_MERCHANT_AMOUNT": "2000",
    "DS_MERCHANT_CVV2": "123",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "ChallengeResponse",
        "protocolVersion": "2.2.0",
        "cres": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidHJhbnNTdGF0dXMiOiJZIn0="
    }
}

De nuevo, los cambios más importantes en esta petición vuelven a encontrarse en el campo Ds_Merchant_EMV3DS.

  • threeDSInfo: En este caso indicas que estás enviando la respuesta del proceso de autenticación.
  • cres: Es el parámetro que te devolvió el ACS al finalizar la autenticación.

Cuando envíes estos parámetros, el TPV Virtual te responderá con el resultado de la operación. En este punto, deberás analizar el parámetro Ds_Response para comprobar cómo ha ido el proceso. Una respuesta con 0000, indica que ha ido correctamente y se ha producido la autorización, es decir, se ha cobrado al titular. Cualquier otra respuesta, deberás consultar la tabla de errores del SIS.

Tal y como se ha dicho anteriormente, no te olvides de firmar todas las respuestas que recibas del TPV Virtual y comprobar la firma con la que se envía desde el SIS, para así confirmar que la respuesta no ha sido alterada en el proceso.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19BbW91bnQiOiIyMDAwIiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19SZXNwb25zZSI6IjAwMDAiLCJEc19BdXRob3Jpc2F0aW9uQ29kZSI6IjM0MzI1MiIsIkRzX1RyYW5zYWN0aW9uVHlwZSI6IjAiLCJEc19TZWN1cmVQYXltZW50IjoiMiIsIkRzX0xhbmd1YWdlIjoiMSIsIkRzX0NhcmROdW1iZXIiOiI0NTQ4ODEqKioqKiowMDAzIiwiRHNfTWVyY2hhbnREYXRhIjoiIiwiRHNfQ2FyZF9Db3VudHJ5IjoiNzI0IiwiRHNfQ2FyZF9CcmFuZCI6IjEiLCJEc19Qcm9jZXNzZWRQYXlNZXRob2QiOiI3OCIsIkRzX0NvbnRyb2xfMTY3NTg2NDA4OTQ5MyI6IjE2NzU4NjQwODk0OTMifQ==",
    "Ds_Signature": "DAuxeL0u7GdK02GD2Vgu-kuJBS4J9xNrfzm-jnoB8hXPA3fErd-n1BiCQxPaP0rfHS8-POYE1fIB1QZzZPrpxQ=="
}
{
    "Ds_Amount": "2000",
    "Ds_Currency": "978",
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_Response": "0000",
    "Ds_AuthorisationCode": "343252",
    "Ds_TransactionType": "0",
    "Ds_SecurePayment": "2",
    "Ds_Language": "1",
    "Ds_CardNumber": "454881******0003",
    "Ds_MerchantData": "",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_ProcessedPayMethod": "78",
    "Ds_Control_1675864089493": "1675864089493"
}

En este punto, se habría completado el proceso de autorización y el proceso de compra habría finalizado. Ahora, en tu backoffice deberías actuar en función del resultado de la operación (actualizar el estado del pedido en tu aplicación, iniciar el proceso de preparación del pedido, notificar vía e-mail a tu cliente, etcétera. Puedes revisar la tabla de parámetros para saber qué significa cada uno de los parámetros que ha enviado el SIS con más detalle.

Realización de un pago usando una integración inSite

La realización de una integración inSite es muy parecida a la integración vía REST, ya que una vez se ha obtenido el idOper, elemento del que hablaremos más adelante, todo el flujo es igual ya que se realiza usando REST.

Proceso de generación del idOper

El ID de operación, llamado idOper, es un identificador con el que podrás operar durante todo el proceso de pago. Para generarlo, deberás crear el iframe que va a contener el formulario inSite y que vas a mostrar al cliente para la introducción de datos de tarjeta. Tal y cómo se ha podido ver en la página de documentación de la integración inSite, las dos formas de integrar el formulario es con la integración unificada y con la integración por elementos independientes. En esta sección, verás como realizar la conexión usando la integración unificada; para más detalles sobre cómo realizar la conexión utilizando la integración inSite por elementos independientes, consulta la guía completa de integración inSite.

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, incorporando la siguiente línea de código en función del entorno en el que vayas a operar:

EntornoScript de Conexión
Pruebas<script src="https://sis-t.redsys.es:25443/sis/NC/sandbox/redsysV3.js"></script>
Real<script src="https://sis.redsys.es/sis/NC/redsysV3.js"></script>

El formulario inSite, en este caso, 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. El aspecto del formulario tendrá un aspecto parecido al siguiente cuando acabes la integración:

Una vez importado el fichero JS, 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 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-example"></div>

Se debe incluir una función de escucha de mensajes (listener) para recibir el ID de operación cuando éste se genere. Se debe utilizar la función storeIdOper con la siguiente definición:

storeIdOper(event, idToken, idErrorMsg, validationFunction);

En esta función, se deberá indicar el evento recogido por el listener (event), el ID del elemento del DOM se debe almacenar el ID de operación una vez sea generado (idToken), el identificador del elemento en el que se almacenarán los códigos de error en caso de que existan errores de validación de los datos (idErrorMsg). En el ejemplo posterior ambos se almacenan en un input de tipo “hidden”.

De manera adicional, como último parámetro se puede adjuntar una función de validación previa. Únicamente se continuará con la generación del ID de operación si la función de validación ejecutada por el comercio retorna un valor true.

Una vez preparado el listener para la recepción de los datos, se llamará a la función proporcionada para generar los elementos de introducción de datos de tarjeta.

getInSiteForm('card-form', estiloBoton, estiloBody, estiloCaja, estiloInputs, ’Pagar con Redsys’, fuc, terminal, merchantOrder, ‘ES’, true);

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 del botón de pago.
  • Cuerpo del formulario: Se recomienda utilizarlo 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.
  • Campos de texto 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 el texto a incluir en el botón y, por último, se deberá informar del valor del FUC del terminal (número de comercio) y el número de pedido (una cadena alfanumérica de 4 a 12 posiciones) en la petición de carga del iframe del formulario de pago.

Se incluyen dos parámetros opcionales en la carga del iframe.

  • El primer parámetro establece el idioma de los textos. La relación de códigos se puede encontrar en el apartado de catálogo de idiomas, que se acoge a los códigos mostrados en el estándar ISO 639-1 del idioma.
    En caso de no establecerse ningún idioma o informar un código erróneo, se mostrará por defecto el idioma castellano.
  • El segundo parámetro establece si se quiere mostrar el logo de la entidad, indicando true si se desea mostrar el logo de la entidad y false en caso contrario.

Es importante tener en cuanta que el merchantOrder utilizado en la carga de iframe y generación del idOper, deberá reutilizarse en la posterior petición de autorización. Nótese que el proceso de autenticación que se explica a continuación, tiene el mismo formato que una autorización usando REST, simplemente sustituyendo los datos de la tarjeta por el idOper. Es posible que las firmas de los ejemplos que tienes a continuación no coincidan, utilícese sólo a título informativo del procedimiento que ha de realizar.

Solicitud de información de la tarjeta · iniciaPeticion

El primer paso durante una autorización vía REST, es la solicitud de datos de tarjeta. Internamente, a este proceso se le llama iniciaPetición, y deberás realizar una solicitud REST a la URL de conexión que corresponda según el entorno en el que te encuentres trabajando.

EntornoURL de Conexión
Pruebashttps://sis-t.redsys.es:25443/sis/rest/iniciaPeticionREST
Realhttps://sis.redsys.es/sis/rest/iniciaPeticionREST

En esta transacción, estás solicitando al TPV Virtual información sobre la capacidad de la tarjeta en cuanto a autenticación (versión del protocolo 3D Secure), posibilidad de aplicación de exenciones, poder realizar operativas especiales, como por ejemplo DCC; etcétera. Esta información indicará como deben gestionarse los siguientes pasos para realizar la operación.

Para iniciar la transacción, enviarás a la URL que corresponda según el entorno en el que estás trabajando, los datos de la operación codificados en base64 dentro del objeto Ds_Merchant_MerchantParameters, junto a la firma y a la versión de firma. El objeto que enviarás debería tener un aspecto parecido al que sigue.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6MTY3NTg2MTcyMSwiRFNfTUVSQ0hBTlRfTUVSQ0hBTlRDT0RFIjoiOTk5MDA4ODgxIiwiRFNfTUVSQ0hBTlRfVEVSTUlOQUwiOiIxIiwiRFNfTUVSQ0hBTlRfVFJBTlNBQ1RJT05UWVBFIjoiMCIsIkRTX01FUkNIQU5UX1BBTiI6IjQ1NDg4MTAwMDAwMDAwMDMiLCJEU19NRVJDSEFOVF9FWFBJUllEQVRFIjoiNDkxMiIsIkRTX01FUkNIQU5UX0NWVjIiOiIxMjMiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX0FNT1VOVCI6IjAwMDAwMDIwMDAiLCJEU19NRVJDSEFOVF9FTVYzRFMiOiJ7XCJ0aHJlZURTSW5mb1wiOlwiQ2FyZERhdGFcIn0iLCJEU19NRVJDSEFOVF9FWENFUF9TQ0EiOiJZIn0=",
    "Ds_Merchant_Signature": "b0ZLxasugdPfKg09di+ucrPWre1FVmGXle+BebNylS7/vkJGioMP907kpFwgOniMHS6mOMmuqR2beB2i5oIeyw==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_IDOPER": "9c75f357629acb672e0f5444401d138f02e834ad",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_AMOUNT": "0000002000",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "CardData"
    },
    "DS_MERCHANT_EXCEP_SCA": "Y"
}

Como puedes comprobar, la estructura de la petición es parecida a la que has visto hasta ahora, pero se añaden varios campos de interés que aparecen resaltados:

  • Ds_Merchant_EMV3DS: Y más concretamente threeDSInfo. En este campo, estás especificando al TPV Virtual que solicitas información de la tarjeta que has enviado en la petición.
  • DS_Merchant_EXCEP_SCA: Aquí estás solicitando que también se te envíe las exenciones que soporta la tarjeta, en caso de que necesitases utilizar una.
Sobre las exenciones de SCA
Puedes consultar todas las exenciones disponibles en la página de información de PSD2 y Autenticación reforzada (SCA).

Enviada la petición, nuestro servidor (en adelante, el SIS), responderá con los datos solicitados si todo ha ido correctamente. En caso de que se produjera un error, la respuesta sería un objeto con un campo errorCode que contendría el código de error que se ha producido y que puedes consultar en la tabla de errores.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19UcmFuc2FjdGlvblR5cGUiOiIwIiwiRHNfRU1WM0RTIjp7InByb3RvY29sVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJkNzQzM2MyZC1mNDRkLTQ4ZGEtYTNhMy1lODgzZjZhODJmZTkiLCJ0aHJlZURTSW5mbyI6IkNhcmRDb25maWd1cmF0aW9uIn0sIkRzX0V4Y2VwX1NDQSI6IkxXVjtUUkFbMzAuMF07Q09SO01JVDtBVEQiLCJEc19DYXJkX1BTRDIiOiJZIn0=",
    "Ds_Signature": "4thE_dbWXdKIapGQVO2NbGhVHCOixzKT9pz42LGKPqrc5c6Le7UhVvGdGgQyfeHoXpvoCFsl_aGyUTQj_cgRvQ=="
}
{
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_TransactionType": "0",
    "Ds_EMV3DS": {
        "protocolVersion": "2.2.0",
        "threeDSServerTransID": "d7433c2d-f44d-48da-a3a3-e883f6a82fe9",
        "threeDSInfo": "CardConfiguration"
    },
    "Ds_Excep_SCA": "LWV;TRA[30.0];COR;MIT;ATD",
    "Ds_Card_PSD2": "Y"
}

En la petición, puedes ver unos parámetros algo más raros en los MerchantParameters descodificados. En cuanto a EMV3DS, encontramos:

  • protocolVersion: Esta es la versión de 3DSecure que soporta la tarjeta. En este caso, deberás emplear un flujo para 3DSecure V2.
  • threeDSServerTransID: Es el identificador de la transacción 3DSecure, y lo necesitarás más adelante. Es único para la operación.
  • threeDSInfo: Esto indica que la respuesta contiene los datos de la tarjeta, es decir, lo que has solicitado.

Y respecto a las exenciones y enrolamiento de la tarjeta:

  • DS_Excep_SCA: Son todas las exenciones que soporta la tarjeta. Para más información, visita el apartado de exenciones de la documentación.
  • Ds_Card_PSD2: Informa sin la tarjeta está enrolada en PSD2, y con una «Y» como respuesta, quiere decir que sí.

Envío de la petición al TPV Virtual · Primer trataPeticion

Una vez se han obtenido los datos de la tarjeta con la que el titular va a realizar la compra, es el momento de enviar la operación al TPV Virtual para iniciar el proceso de autenticación. Tal y como respondió el TPV Virtual en este ejemplo (y como van a ser la gran mayoría de las veces), vas a tener que realizar un proceso de autenticación EMV3DS V2.

Para ello, tienes que preparar la operación de nuevo. Es muy importante que todos los datos básicos de la operación y, sobre todo, el número de pedido sea el mismo, de lo contrario la operación no podrá continuar. Además, se adjuntará dentro del parámetro Ds_Merchant_EMV3DS, un objeto JSON con los parámetros del navegador junto a los parámetros threeDSInfo y protocolVersion. Estos parámetros puedes obtenerlos manualmente o usando nuestras librerías de integración.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6IjE2NzU4NjE3MjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiIwIiwiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiI5NzgiLCJEU19NRVJDSEFOVF9QQU4iOiI0NTQ4ODEwMDAwMDAwMDAzIiwiRFNfTUVSQ0hBTlRfRVhQSVJZREFURSI6IjQ5MTIiLCJEU19NRVJDSEFOVF9BTU9VTlQiOiIyMDAwIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyIsIkRTX01FUkNIQU5UX0VNVjNEUyI6IntcInRocmVlRFNJbmZvXCI6XCJBdXRoZW50aWNhdGlvbkRhdGFcIixcInByb3RvY29sVmVyc2lvblwiOlwiMi4yLjBcIixcImJyb3dzZXJKYXZhc2NyaXB0RW5hYmxlZFwiOlwidHJ1ZVwiLFwiYnJvd3NlckFjY2VwdEhlYWRlclwiOlwidGV4dFwvaHRtbCxhcHBsaWNhdGlvblwveGh0bWwreG1sLGFwcGxpY2F0aW9uXC94bWw7cT0wLjksKlwvKjtxPTAuOCxhcHBsaWNhdGlvblwvanNvblwiLFwiYnJvd3NlclVzZXJBZ2VudFwiOlwiTW96aWxsYVwvNS4wIChXaW5kb3dzIE5UIDEwLjA7IFdpbjY0OyB4NjQpIEFwcGxlV2ViS2l0XC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWVcLzcxLjAuMzU3OC45OCBTYWZhcmlcLzUzNy4zNlwiLFxyXG5cdFx0XHRcdFx0XHRcdFwidGhyZWVEU1NlcnZlclRyYW5zSURcIjpcImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOVwiLFwiYnJvd3NlckphdmFFbmFibGVkXCI6XCJmYWxzZVwiLFwiYnJvd3Nlckxhbmd1YWdlXCI6XCJFUy1lc1wiLFwiYnJvd3NlckNvbG9yRGVwdGhcIjpcIjI0XCIsXCJicm93c2VyU2NyZWVuSGVpZ2h0XCI6XCIxMjUwXCIsIFwiYnJvd3NlclNjcmVlbldpZHRoXCI6XCIxMzIwXCIsXCJicm93c2VyVFpcIjpcIjUyXCIsXCJub3RpZmljYXRpb25VUkxcIjpcImh0dHBzOlwvXC9zaXMtZC5yZWRzeXMuZXNcL3Npcy1zaW11bGFkb3Itd2ViXC9TaXNSRVNUQ3JlcUNyZXNfM0RTZWN1cmVWMi5qc3BcIn0ifQ==",
    "Ds_Merchant_Signature": "EbCFBgZNK9GGO+mCjMCXVT+KYOj1DOO8RB9Y9cnw+daYZoFZLYU34UxEqo8QNpIA6tKKPnUJ4HzDwzyfKEvlvQ==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_IDOPER": "9c75f357629acb672e0f5444401d138f02e834ad",
    "DS_MERCHANT_AMOUNT": "2000",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "AuthenticationData",
        "protocolVersion": "2.2.0",
        "browserJavascriptEnabled": "true",
        "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8,application/json",
        "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
        "threeDSServerTransID": "d7433c2d-f44d-48da-a3a3-e883f6a82fe9",
        "browserJavaEnabled": "false",
        "browserLanguage": "ES-es",
        "browserColorDepth": "24",
        "browserScreenHeight": "1250",
        "browserScreenWidth": "1320",
        "browserTZ": "52",
        "notificationURL": "https://sis-d.redsys.es/sis-simulador-web/SisRESTCreqCres_3DSecureV2.jsp"
    }
}

Tal y como puedes comprobar en los parámetros descodificados, el campo Ds_Merchant_EMV3DS tiene en este caso un JSON con muchos más campos de lo habitual. Los importantes son los dos primeros y el último, ya que el resto de los campos, son los datos extraídos del navegador del cliente.

  • threeDSInfo: En este caso estamos solicitando datos para la autenticación del titular de la tarjeta que enviamos.
  • protocolVersion: La versión del protocolo EMV3DS de la tarjeta, que se nos notificó en el paso anterior.
  • notificationURL: Una vez finalizado el challenge, la entidad emisora enviará el resultado al comercio, haciendo un HTTP POST a esta URL.

Una vez enviemos estos datos, el SIS nos devolverá una respuesta parecida a la que sigue.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19BbW91bnQiOiIyMDAwIiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19UcmFuc2FjdGlvblR5cGUiOiIwIiwiRHNfRU1WM0RTIjp7InRocmVlRFNJbmZvIjoiQ2hhbGxlbmdlUmVxdWVzdCIsInByb3RvY29sVmVyc2lvbiI6IjIuMi4wIiwiYWNzVVJMIjoiaHR0cHM6Ly9zaXMtZC5yZWRzeXMuZXMvc2lzLXNpbXVsYWRvci13ZWIvYXV0aGVudGljYXRpb25SZXF1ZXN0LmpzcCIsImNyZXEiOiJleUowYUhKbFpVUlRVMlZ5ZG1WeVZISmhibk5KUkNJNkltUTNORE16WXpKa0xXWTBOR1F0TkRoa1lTMWhNMkV6TFdVNE9ETm1ObUU0TW1abE9TSXNJbUZqYzFSeVlXNXpTVVFpT2lKbVlqTm1NMk5qTUMwNVpEUXpMVFJtWVRFdE9HVXdNaTFqWkdKa05HTmxZVFpoTXpRaUxDSnRaWE56WVdkbFZIbHdaU0k2SWtOU1pYRWlMQ0p0WlhOellXZGxWbVZ5YzJsdmJpSTZJakl1TWk0d0lpd2lZMmhoYkd4bGJtZGxWMmx1Wkc5M1UybDZaU0k2SWpBMUluMCJ9fQ==",
    "Ds_Signature": "c1GTYUGmwJEY3HJ-ePjRUAU6uqHuf-a03MPvt_ChJ-s_OBHCK_aMeAaGiFvlKnh3Kx_YUkYHQ6730lrgb4krIA=="
}
{
    "Ds_Amount": "2000",
    "Ds_Currency": "978",
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_TransactionType": "0",
    "Ds_EMV3DS": {
        "threeDSInfo": "ChallengeRequest",
        "protocolVersion": "2.2.0",
        "acsURL": "https://sis-d.redsys.es/sis-simulador-web/authenticationRequest.jsp", //URL QUE TE HA ENVIADO EL SIS DONDE DEBES ENVIAR EL CREQ
        "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
    }
}

En la respuesta del TPV Virtual, se debe analizar el contenido del parámetro Ds_EMV3DS:

  • threeDSInfo: En este caso nos informa de que la operación requiere autenticación de titular, conocido como Challenge.
  • acsURL: Es la URL donde deberás enviar la petición de autenticación del titular, el CREQ.
  • creq: De ChallengeRequest, es el valor que debes enviar a la URL del ACS (servidor de autenticación).

Resultados alternativos: frictionless y KO

Es posible que en la respuesta, no se te envíe challengeRequest, ni acsURL ni CREQ, sino que directamente se te muestre el resultado de la operación con un código de autorización y Ds_Response con valor 0000 (OK). En este caso, se ha producido lo que se denomina una autenticación frictionless, es decir, el servidor de autenticación ha considerado tener datos suficientes para identificar al titular y autorizar la operación. La respuesta, en ese caso, sería parecida a la que sigue.

{
    "Ds_MerchantParameters": "eyJEc19EYXRlIjoiMDklMkYwMiUyRjIwMjMiLCJEc19Ib3VyIjoiMTclM0EwOSIsIkRzX1NlY3VyZVBheW1lbnQiOiIxIiwiRHNfQW1vdW50IjoiMTQ1IiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjExMTIiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjAwMSIsIkRzX1Jlc3BvbnNlIjoiMDAwMCIsIkRzX1RyYW5zYWN0aW9uVHlwZSI6IjAiLCJEc19NZXJjaGFudERhdGEiOiIlMjZWaWFqZXMlMEElMDklMDklMDklMDklMDklMDklMDlNYWwlMEElMDklMDklMDklMDklMDklMDklMDlkaXZhcyIsIkRzX0F1dGhvcmlzYXRpb25Db2RlIjoiMjkxODU2IiwiRHNfQ2FyZF9OdW1iZXIiOiI0OTE4MDEqKioqKio0NjAyIiwiRHNfQ29uc3VtZXJMYW5ndWFnZSI6IjEiLCJEc19DYXJkX0NvdW50cnkiOiI3MjQiLCJEc19DYXJkX0JyYW5kIjoiMSIsIkRzX1Byb2Nlc3NlZFBheU1ldGhvZCI6IjgwIiwiRHNfQ29udHJvbF8xNjc1OTU4OTk1MzcxIjoiMTY3NTk1ODk5NTM3MSJ9",
    "Ds_Merchant_Signature": "KYp3cC6-6I7o3T_S2uhOasbmIajgpAsjIUlH2yiAQKUEhh_zu89ARRHCmHA6NvuSOeAoJcnFBtYpTdVf8Q_kNQ==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "Ds_Date": "09%2F02%2F2023",
    "Ds_Hour": "17%3A09",
    "Ds_SecurePayment": "1",
    "Ds_Amount": "145",
    "Ds_Currency": "978",
    "Ds_Order": "1112",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "001",
    "Ds_Response": "0000",
    "Ds_TransactionType": "0",
    "Ds_AuthorisationCode": "291856",
    "Ds_Card_Number": "491801******4602",
    "Ds_ConsumerLanguage": "1",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_ProcessedPayMethod": "80",
    "Ds_Control_1675958995371": "1675958995371"
}

En este caso puedes analizar el Ds_Response, y comprobar que, si su valor es 0000, la operación ha finalizado correctamente.

Por el contrario, si el Ds_Response que recibes es distinto a 0000, por ejemplo 0190; quiere decir que no se ha realizado la autenticación y se ha producido algún error durante la operación. Deberás consultar la tabla de errores para averiguar qué error se ha producido.

Proceso de autenticación

Para realizar la autenticación, tienes que usar el parámetro CREQ que te envió el SIS, y remitirlo a la URL del servidor de autenticación que te llegó en el parámetro acsURL. Esto deberás hacerlo, por ejemplo, vía HTTP POST a la URL especificada.

<form name="frm" action="https://sis-d.redsys.es/sis-simulador-web/authenticationRequest.jsp" method="POST"
    target="_blank">

    <input type="text" name="creq"
        value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0" />
    <input type="submit" 
        value="Realizar Pago" />
        
</form>

Cabe destacar en este punto, que debes estar preparado para mostrar una pantalla al titular que muestra el estado del servidor de autenticación y los pasos que debe seguir. En esa pantalla se muestran las instrucciones para realizar la autenticación, como poner el código que le ha llegado por SMS, aceptar la operación en su aplicación del banco, etcétera. La pantalla del ACS se parece a la siguiente en nuestro entorno de TEST, pero puede tener diversos aspectos una vez en producción en función de la marca y del tipo de challenge.

Para mostrar la pantalla, te mostramos un ejemplo de cómo hacerlo en PHP, pero puedes extrapolar esta muestra a cualquier lenguaje ya que, como puedes observar, sólo se está cargando un iframe enviando los elementos pedidos para mostrar la pantalla y se usa un fragmento en JavaScript para auto-enviar el formulario.

<? php

function redirect_to_acs() {

	$form='<iframe name="redsys_iframe_acs" name="redsys_iframe_acs" src=""
	id="redsys_iframe_acs" target="_parent" referrerpolicy="origin"
	sandbox="allow-same-origin allow-scripts allow-top-navigation allow-forms"
	height="95%" width="100%" style="border: none; display: none;"></iframe>

	<form name="redsysAcsForm" id="redsysAcsForm"
		action="'. $urlACS .'" method="POST"
		target="redsys_iframe_acs" style="border: none;">
		<table name="dataTable" border="0" cellpadding="0">
			<input type="hidden" name="creq"
				value="'. $creq .'">
			<br>
			<p style="font-family: Arial; font-size: 16; font-weight: bold; color: black; align: center;">
				Conectando con el emisor...
			</p>
		</table>
	</form>
			
	<script>
		window.onload = function () {
			document.getElementById("redsys_iframe_acs").onload = function() {
				document.getElementById("redsysAcsForm").style.display="none";
				document.getElementById("redsys_iframe_acs").style.display="inline";
			}
			document.redsysAcsForm.submit();
		}
	</script>';

	die($form);
}

Cuando el proceso de autenticación finalice, el ACS enviará el parámetro CRES a la URL que especificaste en notificationURL en el primer trataPeticion. Lo notificará utilizando un HTTP POST y tendrás que recogerlo para enviarlo en el siguiente paso de nuevo al TPV Virtual. Ten en cuenta que este parámetro puede tardar en llegar, en función de lo que tarde el titular en autenticarse, por lo que te recomendamos que si vas a configurar un timeout, seas generoso con el tiempo que pones (normalmente el ACS suele tener un timeout de 7 minutos).

Envío del resultado de la autenticación · Segundo trataPeticion

Cuando has recibido el parámetro CRES de parte del ACS, deberás iniciar un segundo trataPeticion a la URL que corresponda, que son las mismas que en el primer trataPeticion. De nuevo, debes cuidar de que los parámetros principales de la operación sean idénticos y no hayan cambiado, de lo contrario, la operación se cancelará. En esta nueva petición deberás adjuntar en el Ds_Merchant_EMV3DS el CRES que has recibido.

{
    "Ds_Merchant_MerchantParameters": "eyJEU19NRVJDSEFOVF9PUkRFUiI6IjE2NzU4NjE3MjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiIwIiwiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiI5NzgiLCJEU19NRVJDSEFOVF9QQU4iOiI0NTQ4ODEwMDAwMDAwMDAzIiwiRFNfTUVSQ0hBTlRfRVhQSVJZREFURSI6IjQ5MTIiLCJEU19NRVJDSEFOVF9BTU9VTlQiOiIyMDAwIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyIsIkRTX01FUkNIQU5UX0VNVjNEUyI6IntcInRocmVlRFNJbmZvXCI6XCJDaGFsbGVuZ2VSZXNwb25zZVwiLFwicHJvdG9jb2xWZXJzaW9uXCI6XCIyLjIuMFwiLFxyXG5cdFwiY3Jlc1wiOlwiZXlKMGFISmxaVVJUVTJWeWRtVnlWSEpoYm5OSlJDSTZJbVEzTkRNell6SmtMV1kwTkdRdE5EaGtZUzFoTTJFekxXVTRPRE5tTm1FNE1tWmxPU0lzSW1GamMxUnlZVzV6U1VRaU9pSm1Zak5tTTJOak1DMDVaRFF6TFRSbVlURXRPR1V3TWkxalpHSmtOR05sWVRaaE16UWlMQ0p0WlhOellXZGxWSGx3WlNJNklrTlNaWE1pTENKdFpYTnpZV2RsVm1WeWMybHZiaUk2SWpJdU1pNHdJaXdpZEhKaGJuTlRkR0YwZFhNaU9pSlpJbjA9XCJ9In0=",
    "Ds_Merchant_Signature": "TC8y92FhwU7HAK905XOUV/aJC5aBK94h2azzeurPViEy5EFc0XNYUTD2Nj+jGMdiItYa4eaxIIW42dyI6kB1yw==",
    "Ds_SignatureVersion": "HMAC_SHA512_V1"
}
{
    "DS_MERCHANT_ORDER": "1675861721",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "1",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_IDOPER": "9c75f357629acb672e0f5444401d138f02e834ad",
    "DS_MERCHANT_AMOUNT": "2000",
    "DS_MERCHANT_EMV3DS": {
        "threeDSInfo": "ChallengeResponse",
        "protocolVersion": "2.2.0",
        "cres": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImQ3NDMzYzJkLWY0NGQtNDhkYS1hM2EzLWU4ODNmNmE4MmZlOSIsImFjc1RyYW5zSUQiOiJmYjNmM2NjMC05ZDQzLTRmYTEtOGUwMi1jZGJkNGNlYTZhMzQiLCJtZXNzYWdlVHlwZSI6IkNSZXMiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidHJhbnNTdGF0dXMiOiJZIn0="
    }
}

De nuevo, los cambios más importantes en esta petición vuelven a encontrarse en el campo Ds_Merchant_EMV3DS.

  • threeDSInfo: En este caso indicas que estás enviando la respuesta del proceso de autenticación.
  • cres: Es el parámetro que te devolvió el ACS al finalizar la autenticación.

Cuando envíes estos parámetros, el TPV Virtual te responderá con el resultado de la operación. En este punto, deberás analizar el parámetro Ds_Response para comprobar cómo ha ido el proceso. Una respuesta con 0000, indica que ha ido correctamente y se ha producido la autorización, es decir, se ha cobrado al titular. Cualquier otra respuesta, deberás consultar la tabla de errores del SIS.

Tal y como se ha dicho anteriormente, no te olvides de firmar todas las respuestas que recibas del TPV Virtual y comprobar la firma con la que se envía desde el SIS, para así confirmar que la respuesta no ha sido alterada en el proceso.

{
    "Ds_SignatureVersion": "HMAC_SHA512_V1",
    "Ds_MerchantParameters": "eyJEc19BbW91bnQiOiIyMDAwIiwiRHNfQ3VycmVuY3kiOiI5NzgiLCJEc19PcmRlciI6IjE2NzU4NjE3MjEiLCJEc19NZXJjaGFudENvZGUiOiI5OTkwMDg4ODEiLCJEc19UZXJtaW5hbCI6IjEiLCJEc19SZXNwb25zZSI6IjAwMDAiLCJEc19BdXRob3Jpc2F0aW9uQ29kZSI6IjM0MzI1MiIsIkRzX1RyYW5zYWN0aW9uVHlwZSI6IjAiLCJEc19TZWN1cmVQYXltZW50IjoiMiIsIkRzX0xhbmd1YWdlIjoiMSIsIkRzX0NhcmROdW1iZXIiOiI0NTQ4ODEqKioqKiowMDAzIiwiRHNfTWVyY2hhbnREYXRhIjoiIiwiRHNfQ2FyZF9Db3VudHJ5IjoiNzI0IiwiRHNfQ2FyZF9CcmFuZCI6IjEiLCJEc19Qcm9jZXNzZWRQYXlNZXRob2QiOiI3OCIsIkRzX0NvbnRyb2xfMTY3NTg2NDA4OTQ5MyI6IjE2NzU4NjQwODk0OTMifQ==",
    "Ds_Signature": "DAuxeL0u7GdK02GD2Vgu-kuJBS4J9xNrfzm-jnoB8hXPA3fErd-n1BiCQxPaP0rfHS8-POYE1fIB1QZzZPrpxQ=="
}
{
    "Ds_Amount": "2000",
    "Ds_Currency": "978",
    "Ds_Order": "1675861721",
    "Ds_MerchantCode": "999008881",
    "Ds_Terminal": "1",
    "Ds_Response": "0000",
    "Ds_AuthorisationCode": "343252",
    "Ds_TransactionType": "0",
    "Ds_SecurePayment": "2",
    "Ds_Language": "1",
    "Ds_CardNumber": "454881******0003",
    "Ds_MerchantData": "",
    "Ds_Card_Country": "724",
    "Ds_Card_Brand": "1",
    "Ds_ProcessedPayMethod": "78",
    "Ds_Control_1675864089493": "1675864089493"
}

En este punto, se habría completado el proceso de autorización y el proceso de compra habría finalizado. Ahora, en tu backoffice deberías actuar en función del resultado de la operación (actualizar el estado del pedido en tu aplicación, iniciar el proceso de preparación del pedido, notificar vía e-mail a tu cliente, etcétera. Puedes revisar la tabla de parámetros para saber qué significa cada uno de los parámetros que ha enviado el SIS con más detalle.

¡No evalúes el número de parámetros que llegan en la respuesta!
Te recomendamos que nunca evalúes el número total de parámetros que recibes como respuestas a las peticiones del TPV Virtual, ya que es muy probable que por actualizaciones de la normativa, se introduzcan más parámetros o se alteren la posición de estos. Tu sistema debe estar preparado para recibir más parámetros de los que inicialmente ves aquí (por ejemplo, un nuevo campo con la IP del comprador).

Envío de la petición al TPV Virtual para una operación MIT

Las operaciones MIT (Merchant-Initiated Transactions) son aquellas que son inicializadas por el comercio sin estar el titular presente, y son utilizadas comunmente para, por ejemplo, las suscripciones, pero sólo aquellas que ha iniciado el comercio, como la suscripción a un gimnasio. Debes tener en cuenta que, tal y como indica su nombre, esta operación está iniciada por el comercio y no precisa autenticación; es decir, la operación es ‘no segura’, por lo que te recomendamos que la utilices sólo en los casos que sea necesario y para la casuística para la que está diseñada.

Sabiendo los datos que se deben enviar, a continuación se muestra un ejemplo del proceso de envío de datos al TPV Virtual. En nuestro caso vamos a realizar una operación de autenticación por importe de 2,49€, al comercio 999008881 y terminal 001, usando la clave de firma de pruebas. Los datos para realizar pruebas los tienes disponibles en la sección de entornos y datos de pruebas. Las URLs según el entorno en el que vayas a trabajar son las siguientes.

EntornoURL de Conexión
Pruebashttps://sis-t.redsys.es:25443/sis/rest/trataPeticionREST
Realhttps://sis.redsys.es/sis/rest/trataPeticionREST

En primer lugar, el campo Ds_MerchantParameters se compondría de un JSON con la siguiente información:

En las líneas sombreadas, se marcan las principales diferencias con el objeto que normalmente se enviaría. En este caso ya no hay MerchantURL, ya que en REST no es necesario autenticar. El campo Ds_Merchant_Identifier es el token de la tarjeta del cliente, o también puedes enviar los datos de tarjeta, caducidad y CVV por separado. 

{
    "DS_MERCHANT_ORDER": "00014338z744",
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "001",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_TRANSACTIONTYPE": "0",
    "DS_MERCHANT_AMOUNT": "249",
    "DS_MERCHANT_IDENTIFIER":"d20712480feef6b4ec3480fa091af91d1b45ba90",
    "DS_MERCHANT_COF_INI":"N",
    "DS_MERCHANT_DIRECTPAYMENT":"true",
    "DS_MERCHANT_EXCEP_SCA":"MIT"
}

En caso de tener una referencia de la tarjeta, debes adjunter el campo Ds_Merchant_Cof_Ini con el valor «N». Debes marcar que quieres que la transacción sea no segura con Ds_Merchant_DirectPayment con valor true, y enviar la exención MIT en Ds_Merchant_Excep_SCA poniendo el valor MIT.

Los parámetros Ds_Merchant_URLOK y Ds_Merchant_URLKO son la distintas URLs hacia donde se enviará al cliente cuando finalice la operación en nuestro sistema. Puedes configurar desde el Portal de Administración del TPV Virtual, que en estas URLs se envíe también el resultado de la operación, para que así puedas mostrarle al cliente, el importe, número de pedido, etc… en la pantalla de información. Recuerda que siempre se enviará la notificación a la URL que hayas configurado en Ds_Merchant_MerchantURL independientemente de que indiques o no URLs de OK y de KO.

El objeto JSON resultante, deberás codificarlo en base64, tal cual lo tienes. Consiguiendo un resultado parecido al siguiente:

ew0KCSJEU19NRVJDSEFOVF9PUkRFUiI6ICIwMDAxNDMzOHo3NDQiLA0KCSJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiAiOTk5MDA4ODgxIiwNCgkiRFNfTUVSQ0hBTlRfVEVSTUlOQUwiOiAiMDAxIiwNCgkiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiAiOTc4IiwNCgkiRFNfTUVSQ0hBTlRfVFJBTlNBQ1RJT05UWVBFIjogIjAiLA0KCSJEU19NRVJDSEFOVF9BTU9VTlQiOiAiMjQ5IiwNCgkiRFNfTUVSQ0hBTlRfSURFTlRJRklFUiI6ImQyMDcxMjQ4MGZlZWY2YjRlYzM0ODBmYTA5MWFmOTFkMWI0NWJhOTAiLA0KCSJEU19NRVJDSEFOVF9ESVJFQ1RQQVlNRU5UIjoidHJ1ZSIsDQoJIkRTX01FUkNIQU5UX0VYQ0VQX1NDQSI6Ik1JVCINCn0=

Posteriormente, deberás firmar esta cadena siguiendo los pasos de creación de firma, usando la clave de firma del comercio. La cadena resultante será el campo Ds_Signature. Por último, se adjuntará a la petición la versión del algoritmo de firma a usar en el campo Ds_SignatureVersion, en este caso HMAC_SHA512_V1.

El resultado de todo este proceso, será un objeto JSON que deberás enviar pediante una petición HTTP POST usando la interfaz REST al TPV Virtual. Recuerda que para realizar la petición REST, debes enviar la cabecera Content-Type con el valor «application/json«.

{
    "Ds_SignatureVersion":"HMAC_SHA512_V1",
    "Ds_MerchantParameters":"ew0KCSJEU19NRVJDSEFOVF9PUkRFUiI6ICIwMDAxNDMzOHo3NDQiLA0KCSJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiAiOTk5MDA4ODgxIiwNCgkiRFNfTUVSQ0hBTlRfVEVSTUlOQUwiOiAiMDAxIiwNCgkiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiAiOTc4IiwNCgkiRFNfTUVSQ0hBTlRfVFJBTlNBQ1RJT05UWVBFIjogIjAiLA0KCSJEU19NRVJDSEFOVF9BTU9VTlQiOiAiMjQ5IiwNCgkiRFNfTUVSQ0hBTlRfSURFTlRJRklFUiI6ImQyMDcxMjQ4MGZlZWY2YjRlYzM0ODBmYTA5MWFmOTFkMWI0NWJhOTAiLA0KCSJEU19NRVJDSEFOVF9ESVJFQ1RQQVlNRU5UIjoidHJ1ZSIsDQoJIkRTX01FUkNIQU5UX0VYQ0VQX1NDQSI6Ik1JVCINCn0=",
    "Ds_Signature":"VST1950haOxHPm76/NwZhRYwDl2/ayT1DbMqS77hNCJQYFNEKxHBrj/oenwJVFVP/6QBhd3XKltMTDic14kVxQ=="
}