My Blog

My Blog

Did You Know?

We design Docy for the readers, optimizing not for page views or engagement

Redirección

Estimated reading: 15 minutes 41 views

¿Qué es la integración por Redirección?

Con la integración por redirección, tus clientes son enviados a nuestra pasarela de pago para completar la compra.

Como el cajero no se encuentra en tu sitio web, no necesitas almacenar datos sensibles. Solo tienes que redirigir al cliente al cajero de pago y enviar la información necesaria para identificar la transacción. Cuando finalice el pago, te enviamos una notificación con el resultado. 

Estas son las ventajas de la integración por redirección: 

  • La pasarela de pago es totalmente segura y fácil de usar.
  • No tienes que preocuparte del cumplimiento de la normativa PCI-DSS.
  • Numerosas operativas y métodos de pago disponibles.
  • Opciones de personalización disponibles.

Este es un ejemplo del cajero de pago al que se redirige a los clientes:

En este caso, el cliente ha optado por guardar su tarjeta para futuras compras. Por eso, aparece su tarjeta como «Método de pago guardado». 

Flujo de la integración por redirección

Este es un diagrama del flujo que siguen las operaciones por redirección. En este caso, se utiliza como ejemplo una autorización: 

  1. Inicio de la operación: El cliente accede a tu tienda online y pulsa el botón de compra para iniciar el proceso de pago.
  2. Petición de pago al TPV Virtual (realizarPago): Tu comercio redirige al cliente al TPV Virtual (Cyberpac), enviando los datos necesarios de la operación. En esta pantalla, el cliente introduce los datos de su tarjeta.
  3. Petición al ACS (3DS): El TPV Virtual contacta con el ACS (Access Control Server) del banco emisor de la tarjeta para iniciar el proceso de autenticación 3D Secure, si aplica.
  4. Autenticación del cliente (3DS): El ACS muestra al cliente una pantalla de autenticación (challenge) o realiza una verificación automática (frictionless), según el nivel de riesgo. Este paso puede ser transparente y no siempre ocurre.
  5. Resultado de autenticación (3DS): El ACS devuelve al TPV Virtual el resultado del proceso de autenticación: éxito, fallo o exención.
  6. Solicitud de resultado autorización: El TPV Virtual solicita a la entidad emisora el resultado de la autorización de la operación.
  7. Resultado de autorización: El emisor responde al TPV Virtual indicando si la operación ha sido autorizada (OK) o rechazada (KO).
  8. Notificación al comercio: El TPV Virtual notifica al comercio el resultado de la autorización mediante una llamada HTTP (notificación online) y/o redirección con parámetros de resultado.
  9. Resultado mostrado al cliente: El comercio muestra al cliente el resultado final del pago (éxito o error) y lo redirige según corresponda (por ejemplo, a la página de confirmación o de error que se envía en la petición).

Integración por redirección: paso a paso

A continuación tienes los pasos para integrar por redirección junto a ejemplos de código. Recuerda: Adapta los ejemplos de código a tus necesidades.

Los bloques de código son un ejemplo para entender más fácilmente el proceso. Adapta tu código a tus necesidades. Consulta las librerías de Redsys para ver más ejemplos:

Librerías de Redsys

Paso 1: Crea y envía un formulario con los datos del pago

El primer paso de la integración por redirección es:

  • Crear un formulario con los datos de la petición de pago.
  • Enviar el formulario al TPV Virtual.  El formulario se envía a través del navegador del cliente durante la redirección. 

El formulario se envía mediante una petición POST a la URL indicada, según estés operando en un entorno de PRUEBAS o de PRODUCCIÓN.

EntornoURL
Pruebashttps://sis-t.redsys.es:25443/sis/realizarPago
Producciónhttps://sis.redsys.es/sis/realizarPago

Los campos que se envían en el formulario son: 

CampoDescripción
Ds_SignatureVersionVersión del algoritmo que se usa para la firma de la petición.
Ds_MerchantParametersDatos de la petición de pago. Se recopilan los datos en un JSON y se codifican en BASE64. Sin retornos de carro. El resultado codificado en BASE64 es lo que se envía en este campo.
Ds_SignatureFirma de la petición. Se obtiene a partir del valor codificado en BASE64 del Ds_MerchantParameters y la clave SHA-256 de tu terminal.

A continuación tienes un ejemplo del formulario final que se envía al TPV Virtual:

A continuación tienes la explicación de los valores que se envían en los campos del formulario de ejemplo:

Ds_SignatureVersion

El campo Ds_SignatureVersion indica la versión del algoritmo que se utiliza para la firma. Se utiliza la misma versión para todas las peticiones.

  • Campo: Ds_SignatureVersion
  • Valor a enviar: HMAC_SHA256_V1

Ds_MerchantParameters

¿Qué es?

Datos de la petición de pago recopilados en un JSON y codificados en BASE64.

  • Esta es la tabla con los parámetros que se pueden mandar en el JSON. Los parámetros se pueden enviar en mayúsculas DS_MERCHANT_TERMINAL o como CamelCase Ds_Merchant_TerminalNO se pueden combinar ambas formas, elige en mayúsculas O en CamelCase.

Según la operativa que quieras realizar, se deben mandar más o menos parámetros. Más detalles en la sección de Operativas Tarjetas

¿Cómo se obtiene?

Recopila los parámetros para una petición de pago. Este es un ejemplo para una operativa normal de autorización recopilados en un JSON:

El JSON con los parámetros debe estar correctamente formado. Esto implica:

  • Sin espacios en blanco en los parámetros.
  • Todos los parámetros son tipo cadena string. Da igual que sean números o alfanuméricos.
  • El importe se debe indicar en céntimos. No se pueden enviar decimales. Por ejemplo, para un importe de 9,50€ se envía 950. 

Una vez creado el JSON, se codifica en BASE64. El JSON anterior codificado en BASE64 da como resultado esta cadena: 

Esta es la cadena que se debe enviar en el campo Ds_MerchantParameters.

  • Campo: Ds_MerchantParameters
  • Valor a enviar: Cadena resultante de codificar el JSON con los datos de la petición de pago en BASE64.

Ds_Signature

¿Qué es?

Firma de la petición. Para calcular la firma, debes tener estos valores:

  1. El valor codificado en BASE64 que se envía en Ds_MerchantParameters.
  2. El número de pedido de la operación. Es el valor de Ds_Merchant_Order (sin codificar en BASE64). 
  3. La clave SHA-256 de tu terminal. Esta clave cambia del entorno de pruebas y el de producción. Tipado: Texto plano.

¿Cómo se obtiene?

  1. Decodifica la clave SHA-256 de tu terminal en BASE64. Tipado: Binario.
  2. Realiza un cifrado 3DES entre:
    • La clave SHA-256 que has decodificado en el paso anterior.
    • El número de pedido Ds_Merchant_Order.
    • Importante: El cifrado utilizado es 3DES (DESede) en modo CBC sin padding automático. Además, se deben añadir los 0s (ceros) necesarios en bytes hasta que sea múltiplo de 8.
    • El resultado es la clave de firma diversificada. Tipado: Binario.
  3. Calcula el HMAC-256 de:
    • El valor que se envía en Ds_MerchantParameters.
    • La clave de firma diversificada (la clave obtenida en el paso 2).
    • Tipado: Binario.
  4. Codifica el HMAC-256 obtenido en el paso anterior en BASE64. El valor resultante es el que se debe enviar en Ds_SignatureTipado: Texto plano.

Este es un ejemplo en PHP de cómo generar la firma de Ds_Signature siguiendo los pasos anteriores:

Este código es un ejemplo para entender más fácilmente el proceso. Adapta el código a las necesidades de tu integración. Consulta las librerías de Redsys para ver más ejemplos:

Librerías de Redsys

  • Campo: Ds_Signature
  • Valor a enviar: Valor resultante del paso 4. 

Envía el formulario con los campos obtenidos: Ds_SignatureVersionDs_MerchantParameters y Ds_Signature.

Paso 2: Recepción y gestión de la notificación online

Recomendamos no validar el número de parámetros que recibes en una notificación. El nº de parámetros recibidos puede variar entre operativas o por nuevas normativas.

¿Qué es?

La notificación online informa al comercio del resultado de la transacción que ha completado el cliente. Aunque el comercio no procese correctamente esta notificación, el resultado de la operación se mantiene.

Configuración

Por defecto se configura que el comercio reciba la notificación en una URL (POST) y en un correo. La URL y el correo donde se recibe la notificación se puede indicar en:

  1. Petición: En la petición de pago, en el campo Ds_Merchant_MerchantURL. (Sólo la URL)
  2. Canales: Se puede configurar una URL y un correo en Canales, en Configuración de Comercio. 

La notificación se puede recibir de 2 maneras, esto también lo puedes configurar en Canales:

  • Síncrona: Primero se envía la notificación al comercio y luego se muestra al cliente.
  • Asíncrona: Se envía la notificación al comercio y, a la vez, se muestra el resultado de la operación al cliente.

¿Qué se recibe en la notificación?

La notificación es un POST HTTP con los datos de la operación y su resultado. Los campos que se reciben en la notificación son iguales a los del formulario de la petición, pero con significados distintos:

CampoDescripción
Ds_SignatureVersionVersión del algoritmo que se usa para la firma.
Ds_MerchantParametersDatos de la respuesta. Están codificados en BASE64 y sin retornos de carro. Lo componen los parámetros indicados en la tabla con los parámetros de salida.
Ds_SignatureFirma de la petición. Se obtiene a partir del valor codificado en BASE64 del Ds_MerchantParameters y la clave SHA-256 de tu terminal. En la notificación, el comercio debe validar que esta firma coincida con la de la petición.

Los parámetros que se reciben en Ds_MerchantParameters son los que indican el resultado de la operación. Los tienes recopilados en la siguiente tabla.

¿Qué debo validar en la notificación?

Una vez se recibe la notificación, es necesario capturar y validar los campos de la misma antes de realizar acciones en el servidor del comercio. Estos son los pasos a seguir en la validación de la notificación:

  1. Recupera los parámetros recibidos en la notificación online: Ds_SignatureVersion , Ds_MerchantParameters y Ds_Signature.
  2. Decodifica el parámetro Ds_MerchantParameters. Este parámetro decodificado contiene los parámetros que indican el resultado de la operación.
  3. Una vez decodificado el parámetro Ds_MerchantParameters, recupera los parámetros que necesites. Esta es la tabla con los parámetros de salida.
  4. Importante: Antes de realizar ninguna acción en tu servidor, valida la firma Ds_Signature recibida. Son los mismos pasos que en la creación de la firma para la petición, pero con los parámetros de la notificación:
    1. Decodifica la clave SHA-256 de tu terminal en BASE64.
    2. Realiza un cifrado 3DES entre:
      • La clave SHA-256 que has decodificado en el paso anterior.
      • El número de pedido Ds_Merchant_Order recibido en la notificación (este parámetro lo recuperas al decodificar el parámetro Ds_MerchantParameters de la notificación).
      • Importante: El cifrado utilizado es 3DES (DESede) en modo CBC sin padding automático. Además, se deben añadir los 0s (ceros) necesarios en bytes hasta que sea múltiplo de 8.
      • El resultado es la clave de firma diversificada.
    3. Calcula el HMAC-256 de:
      • El valor que se recibe en el Ds_MerchantParameters de la notificación.
      • La clave de firma diversificada (la clave obtenida en el paso 2).
    4. Codifica el HMAC-256 obtenido en el paso anterior en BASE64. El valor resultante debe coincidir con el Ds_Signature recibido en la notificación.

A continuación tienes un ejemplo de código en PHP del proceso de captura y validación de la notificación:

Este código es un ejemplo para entender más fácilmente el proceso. Adapta el código a las necesidades de tu integración. Consulta las librerías de Redsys para ver más ejemplos:

Librerías de Redsys

Notificación en la URL OK o KO (GET)

En el paso 2 se explicó cómo recibir la notificación mediante una petición POST a la URL indicada en el campo Ds_Merchant_MerchantURL. Sin embargo, también es posible recibir esta notificación a través de las URLs OK o KO mediante el método GET, con las siguientes consideraciones:

  • Redirección del cliente: El cliente es redirigido a la URL OK o KO según el resultado de la operación.
  • Envío de parámetros en la URL: Activar en Canales la opción «Enviar parámetros en las URLs = Sí» en la sección de Configuración de Comercio. Redsys incluirá los parámetros de la notificación en la propia URL.
  • Estructura de los parámetros: Los parámetros enviados en estas URLs son los mismos que se reciben en la notificación por POST (Ds_SignatureVersionDs_MerchantParameters y Ds_Signature), y deben validarse de la misma forma.
No mostrar el recibo de la operación

Puedes elegir NO mostrar el recibo de la operación que prepara el TPV Virtual por defecto (captura de la derecha), conocido como recibo Redsys.

Para no mostrar este recibo por defecto tienes que:

  1.  Avisar a Soporte para que activen la opción en Canales «Enviar parámetros en las URLs = Sí, sin mostrar recibo Redsys». 
  2. Tu comercio tendrá que preparar una pantalla con el recibo. Soporte enviará más detalles por correo, pero la página del recibo deberá incluir:
    • FUC del comercio
    • Nombre del comercio
    • URL del comercio
    • Importe de la operación
    • Código de autorización de Redsys
    • Fecha / hora de la operación
    • Descripción del producto

Paso 3: Reintento de operación y/o retorno a la navegación

Cuando el cliente intenta completar una operación en el TPV Virtual, puede haber 2 escenarios:

  1. La operación es denegada y el cliente puede reintentar.
  2. La operación es autorizada (OK) o rechazada (KO), lo que redirige al cliente a una página o a otra una vez pulse «Continuar» en el recibo que aparece al completar la operación.

A continuación, vamos a ver los dos escenarios.

1. Reintento de operación.

La opción de reintentar la operación está activada por defecto en tu TPV Virtual. Sin embargo, la opción de reintentar operación sólo se ofrecerá en entorno de producción y cumpliendo estos supuestos:

  • La operación ha sido denegada por el emisor de la tarjeta.
  • La autenticación del titular ha fallado durante la operación. 
  • El reintento de operación se realiza sólo con el formulario de pago con tarjeta. Si el cliente ha intentado pagar con otro método de pago y ha fallado, el reintento será con tarjeta. 

No se permite reintentar operación si se deniega por reglas de fraude, errores técnicos o cualquier otro tipo de error. 

Importante: Tu integración debe estar preparada para recibir varias notificaciones asociadas al mismo número de pedido. De esta forma «ignora» las notificaciones que indican que la operación está denegada y «tiene en cuenta» la notifcación que indica que la operación se ha autorizado.

2. Retorno a la navegación.

Una vez finalice la operación, se muestra al cliente un recibo con los detalles de la operación. Este recibo lo genera el TPV Virtual, no tienes que hacer nada en tu integración:

Nota: Si no quieres mostrar este recibo por defecto, consulta esta sección.

Cuando el cliente pulsa «Continuar» se redirige al cliente a una URL u otra dependiendo del resultado de la operación. La URL se puede indicar en la petición de pago:

  • DS_MERCHANT_URLOK, para la URL a la que redirigir si el resultado de la operación es correcto.
  • DS_MERCHANT_URLKO, para la URL a la que redirigir si el resultado es incorrecto.

La redirección a una URL OK o KO indica si la operación está autorizada o denegada, pero NO notifica al comercio. Este proceso es paralelo a la gestión y validación de la notificación. 

Personalización

Puedes personalizar la pasarela de pago de dos maneras:

  1. Cambiar el idioma: Se modifica enviando el parámetro Ds_Merchant_ConsumerLanguage en la petición. 
  2. Desde Canales: Puedes modificar colores, botones, etc. Es más complejo y tienes que pedir los permisos necesarios a Soporte. 

Personalización pasarela Redirección

Integración para PSPs

Si eres o usas un PSP (Proveedor de Servicios de Pago), hay algunas configuraciones extras que se deben hacer para integrar por Redirección. Habla con tu PSP y sigue sus indicaciones. 

Próximos pasos

Una vez has completado la integración por redirección, puedes configurar o probar distintas operativas de pago con tarjeta o métodos de pago:

Operativas con tarjetas – Redirección

Métodos de pago

Leave a Comment

Share this Doc

Redirección

Or copy link

CONTENTS