REST

¿Qué es la integración REST?

Con la integración REST gestionas directamente el proceso de pago desde tu servidor. El cliente no abandona tu página durante el proceso de pago. Es una comunicación directa entre tu servidor y el TPV Virtual. 

Al ser una integración directa, necesitas manejar datos sensibles y cumplir con los requisitos de seguridad de PCI DSS, pero a cambio obtienes una mayor flexibilidad y control sobre el proceso. Esta modalidad es ideal para comercios que busquen ofrecer una experiencia de pago completamente integrada o que quieran realizar operaciones sin el cliente presente. 

Estas son las características de la integración REST:

  • La pasarela de pago es totalmente personalizable según tus necesidades.
  • Al manejar datos sensibles se debe cumplir la normativa PCI-DSS. Sin embargo, si sólo vas a hacer devoluciones o confirmaciones, no hace falta. Más detalles en el documento de Operativas con Tarjetas).
  • Numerosas operativas y métodos de pago disponibles.
  • Control total de todo el proceso de pago.

Flujo de la integración REST

A continuación tienes los distintos flujos que pueden seguir las operaciones en la integración REST: 

  • Flujo sin 3DS
  • Flujo con 3DS – Frictionless
  • Flujo con 3DS – Challenge

En el documento de operativas con tarjeta REST tienes los detalles de las operaciones de los flujos aquí descritos. 

En las siguientes pestañas tienes el diagrama de flujo y la explicación detallada de los pasos: 

  1. Inicio de la operación: El cliente entra en tu tienda online y pulsa en el botón de pagar para iniciar el proceso. 
  2. Petición de pago (trataPeticion): El comercio monta y envía una petición de pago siguiendo la lógica de la integración y enviando los parámetros necesarios según la operativa. 
  3. Resultado de la operación: El TPV Virtual notifica a tu comercio el resultado de la operación.
  4. Indicar resultado al cliente: Tu comercio le indica al cliente el resultado de la operación. 
  1. Inicio de la operación: El cliente entra en tu tienda online y pulsa en el botón de pagar para iniciar la operación. 
  2. Petición de información (iniciaPeticion):El comercio envía una petición al TPV Virtual con los datos básicos de la operación y la tarjeta. Esta petición sirve para iniciar el flujo 3DS y obtener los datos necesarios para valorar el riesgo de la transacción.
  3. Información 3DS: El TPV Virtual notifica a tu comercio la información 3DS sobre la tarjeta y la operación, incluyendo la URL donde realizar el 3DS Method.
  4. 3DS Method (opcional pero recomendable): Tu comercio ejecuta el 3DS Method, que consiste en recopilar información sobre el cliente para que la transacción sea más segura. 
  5. Intercambio de datos con el ACS: El navegador del cliente establece comunicación directa con el servidor del emisor (ACS) para proporcionar información adicional. Esto ocurre automáticamente y no requiere interacción del cliente.
  6. Resultado 3DS Method: El navegador del cliente comunica a tu comercio el resultado del 3DS Method.
  7. Petición de pago (trataPeticion): Tu comercio envía la petición de pago con datos 3DS (recopilados del iniciaPeticion y del 3DS Method) al TPV Virtual.
  8. Respuesta petición de pago (frictionless): El TPV Virtual valora el riesgo y, si la operación es considerada de bajo riesgo, autoriza la operación directamente sin requerir autenticación adicional del cliente (no hay challenge).
  9. Resultado operación: Tu comercio indica al cliente el resultado de la operación. 
  1. Inicio de la operación: El cliente entra en tu tienda online y pulsa en el botón de pagar para iniciar la operación. 
  2. Petición de información (iniciaPeticion):El comercio envía una petición al TPV Virtual con los datos básicos de la operación y la tarjeta. Esta petición sirve para iniciar el flujo 3DS y obtener los datos necesarios para valorar el riesgo de la transacción.
  3. Información 3DS: El TPV Virtual notifica a tu comercio la información 3DS sobre la tarjeta y la operación, incluyendo la URL donde realizar el 3DS Method.
  4. 3DS Method (opcional pero recomendable): Tu comercio ejecuta el 3DS Method, que consiste en recopilar información sobre el cliente para que la transacción sea más segura. 
  5. Intercambio de datos con el ACS: El navegador del cliente establece comunicación directa con el servidor del emisor (ACS) para proporcionar información adicional. Esto ocurre automáticamente y no requiere interacción del cliente.
  6. Resultado 3DS Method: El navegador del cliente comunica a tu comercio el resultado del 3DS Method.
  7. Petición de pago (trataPeticion): Tu comercio envía la petición de pago con datos 3DS (recopilados del iniciaPeticion y del 3DS Method) al TPV Virtual.
  8. Respuesta petición de pago (challenge): El TPV Virtual valora el riesgo y determina que el cliente se tiene que autenticar mediante challenge.
  9. Cliente realiza challenge: El cliente realiza el challenge. El challenge puede ser una autenticación en su aplicación bancaria, un SMS con un código, etc. 
  10. Resultado del challenge: El Banco emisor (ACS) le comunica a tu comercio el resultado del challenge.
  11. Petición de autenticación (trataPeticion): Tu comercio envía al TPV Virtual una petición con los parámetros que indican el resultado del challenge, entre otros.
  12. Resultado autenticación: El TPV Virtual le comunica a tu comercio el resultado de la operación de autenticación. 
  13. Resultado operación: Tu comercio indica al cliente el resultado de la operación. 

Integración REST: paso a paso

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

Librerías de Redsys

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

El primer paso de la integración REST es:

  • Crear un formulario en formato JSON con los datos de la petición de pago.
  • Enviar el formulario al TPV Virtual.  El formulario se envía como una petición POST.

El formulario de la petición REST sigue la misma estructura y lógica sea cuál sea la operativa, lo que cambia es el endpoint al que lo envías y los valores dentro del campo Ds_MerchantParameters.

El formulario se envía mediante una petición POST a la URL indicada, según: entorno (PRUEBAS o  PRODUCCIÓN) o tipo de petición (IniciaPeticion o trataPeticion):

  • iniciaPeticion: Este endpoint se utiliza para iniciar operaciones que requieren autenticación 3DS (por ejemplo, autorizaciones o preautorizaciones con 3DS v2). Devuelve la información necesaria para redirigir al cliente al proceso de autenticación.
  • trataPeticion: Endpoint principal para gestionar operaciones REST. Se utiliza para procesar pagos, confirmar preautorizaciones, realizar devoluciones, anular operaciones, entre otras acciones.
Tipo de peticiónEntornoURL
iniciaPeticionPruebas https://sis-t.redsys.es:25443/sis/rest/iniciaPeticionREST
Producciónhttps://sis.redsys.es/sis/rest/iniciaPeticionREST
trataPeticionPruebashttps://sis-t.redsys.es:25443/sis/rest/trataPeticionREST
Producciónhttps://sis.redsys.es/sis/rest/trataPeticionREST

Independientemente del tipo de operación o del entorno, 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 de tu terminal.

Importante: Antes de integrar, ten en cuenta estas consideraciones:

  • En las peticiones REST, tienes que enviar la siguiente cabecera con el siguiente valor: Content-Type: application/json.
  • El formulario de la petición REST sigue la misma estructura y lógica sea cuál sea la operativa, lo que cambia es el endpoint al que lo envías y los valores dentro del campo Ds_MerchantParameters.
  • La conexión requiere una firma HMAC SHA-256/512 para autenticar al servidor del comercio y al TPV Virtual. El comercio puede implementarla por su cuenta usando funciones estándar de su entorno de desarrollo, aunque se ofrecen librerías en PHP, Java y .NET para facilitar la integración

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_SHA512_V2

Nota: Si firmas con el algoritmo SHA 256, tendrás que 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_Terminal. NO se pueden combinar ambas formas, elige en mayúsculas O en CamelCase.

¿Cómo se obtiene?

Recopila los parámetros para una operación. Este es un ejemplo para una operativa de devolución vía REST recopilados en un JSON:

				
					{
    "DS_MERCHANT_MERCHANTCODE": "999008881",
    "DS_MERCHANT_TERMINAL": "99",
    "DS_MERCHANT_TRANSACTIONTYPE": "3",
    "DS_MERCHANT_AMOUNT": "100",
    "DS_MERCHANT_CURRENCY": "978",
    "DS_MERCHANT_ORDER": "79430110"
}

Importante: Recuerda que en las operaciones con flujo 3DS, tendrás que mandar varias peticiones.

  • La creación y el envío del formulario que explicamos en este documento es igual en todas las operativas, lo que cambia son los parámetros que se envían dentro de Ds_MerchantParameters.
  • Tienes todo el flujo explicado en la sección de Operativas con tarjetas en REST.

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: 

				
					ewogICAgIkRTX01FUkNIQU5UX01FUkNIQU5UQ09ERSI6ICIyMjMxMDg4NTMiLAogICAgIkRTX01FUkNIQU5UX1RFUk1JTkFMIjogIjk5IiwKICAgICJEU19NRVJDSEFOVF9UUkFOU0FDVElPTlRZUEUiOiAiMyIsCiAgICAiRFNfTUVSQ0hBTlRfQU1PVU5UIjogIjEwMCIsCiAgICAiRFNfTUVSQ0hBTlRfQ1VSUkVOQ1kiOiAiOTc4IiwKICAgICJEU19NRVJDSEFOVF9PUkRFUiI6ICI3OTQzMDExMCIKfQ==
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

A continuación se explica el proceso de cálculo de firma SHA-512 V2.

Para nuevas integraciones recomendamos usar esta firma, aunque ambas son válidas. Si tu comercio ya está integrado, revisa cómo se calcula la firma SHA-256 en el anexo.

¿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 específica de tu terminal. Esta clave cambia del entorno de pruebas y el de producción. Tipado: Texto plano.
    • La clave del terminal para producción se obtiene desde Canales, y la de pruebas se envía en el Welcome Pack. Consulta la documentación para más detalles.
    • Guarda la clave de producción en un lugar seguro para evitar su uso fraudulento.

¿Cómo se obtiene?

  1. Pre-procesa la clave de tu terminal: La clave tiene que tener exactamente 16 caracteres.
    • Si tiene MÁS de 16 caracteres: Utiliza únicamente los 16 primeros caracteres de la clave.
    • Si tiene MENOS de 16 caracteres: Rellena por la derecha con ceros (0) hasta llegar a 16 caracteres.
  2. Genera la clave diversificada: Esto se hace mediante un cifrado AES CBC, usando como vector de inicialización IV un vector de ceros. Este cifrado AES CBC se hace entre:
    • La clave de tu terminal pre-procesada en el paso anterior.
    • El número de pedido de la operación Ds_Merchant_Order (sin codificar en BASE64).
    • Realiza un cifrado AES CBC entre estos 2 valores.
  3. Codifica en BASE64: Codifica en BASE64 el resultado obtenido en el paso anterior. Este valor se llama clave diversificada, y lo utilizarás más adelante.
  4. Calcula el HMAC-SHA512: Aplica el algoritmo HMAC-SHA512 sobre el Ds_MerchantParameters codificado en BASE64, utilizando la clave diversificada obtenida en el paso anterior.
  5. Codifica en BASE64URL: Se codifica el resultado del HMAC-SHA512 en BASE64URL.
    • Este es el valor que tienes que enviar en Ds_Signature.

A continuación tienes un ejemplo en PHP del proceso de generación de firma:

				
					<?php
// Este es un fragmento de código para realizar la firma. Añádelo al resto de librerías para que el proceso se complete correctamente.
class Signature {
	/******  AES Function  ******/
	static function encrypt_AES($data, $key) {
		$fixedKey = str_pad(substr($key, 0, 16), 16, "0");
		$firma = base64_encode(openssl_encrypt($data, "aes-128-cbc", $fixedKey, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"));

		return $firma;
	}

	static function mac512($data, $key) {
		$sha = hash_hmac('sha512', $data, $key, true);
		return $sha;
	}

	static function createMerchantSignature($key, $data, $diversifyingFactor) {
		// Se diversifica la clave con el Número de Pedido
		$key = self::encrypt_AES($diversifyingFactor, $key);

		// MAC512 del parámetro Ds_Parameters que envía Redsys
		$res = self::mac512($data, $key);

		// Se codifican los datos Base64
		return Utils::base64_url_encode_safe($res);
	}
    // Función para comparar firmas. Utilizado en la verificación de la notificación.
	static function checkSignatures($sig1, $sig2) {
		if (strcasecmp($sig1, $sig2) !== 0) {
			throw new Exception("Integrity failure. The received signature does not match the calculated one.");
		}
	}
}

?>

Consulta las librerías de Redsys para ver el código completo, recomendamos utilizar la última versión de las librerías:

Librerías de Redsys
  • Campo: Ds_Signature
  • Valor a enviar: Valor resultante del paso 5. 

¿Qué hago cuando tenga el formulario montado?

Envía el formulario con los campos obtenidos: Ds_SignatureVersion, Ds_MerchantParameters y Ds_Signature.

¿Y si tengo que lanzar más peticiones en un mismo flujo de operación?

En los flujos con 3DS, tendrás que lanzar peticiones de iniciaPeticion y trataPeticion para completar una misma operación.

Lo explicado en esta sección aplica a cualquier formulario de cualquier petición que envíes, lo que cambian son los valores enviados en Ds_MerchantParameters.

Paso 2 (condicional): Proceso de autenticación 3DS

3D Secure (3DS) es un protocolo de autenticación que tiene el objetivo de autenticar al titular de la tarjeta en los pagos online para reducir el fraude. Esto es posible gracias a la implementación de parámetros extra en las peticiones y de la Autenticación Reforzada del Cliente (SCA).

En la integración REST, el proceso de autenticación 3DS es condicional, ya que tendrás que implementarlo o no dependiendo de las operativas que integres.

A continuación tienes el proceso explicado en la sección «Operativas con autenticación 3DS» del documento de operativas REST. El proceso de autenticación 3DS lo tendrás que implementar en las operativas REST con tarjeta que se indican en esta sección. 

Operativas con autenticación 3DS

Por tanto, las operaciones que NO requieren 3DS son las que se indican en la sección «Operativas con una sola petición».

MPI / 3DS Server Externo

Si el PSP o el integrador cuenta con su propia certificación para gestionar la autenticación de manera externa a la pasarela de pago, podrá enviar la información de la autenticación en la transacción. Para habilitar esta funcionalidad, será necesario solicitar su activación al equipo de Soporte.

En las peticiones que se envíen a la pasarela de pago, deberá incluirse el campo DS_MERCHANT_MPIEXTERNAL con la información correspondiente a la autenticación.

Paso 3: Recepción y gestión de la notificación

¿Qué es?

La notificación informa al comercio del resultado de la operación. La notificación se envía desde el TPV Virtual al servidor del comercio una vez finaliza la operación. 

Configuración

La propia función de la librería te devuelve la respuesta del TPV Virtual. Consulta las librerías de Redsys para ver cómo.

La respuesta se recibe tras hacer la petición. 

¿Qué recibo en la notificación?

Puedes recibir 2 tipos de notificaciones:

  1. Notificación indicando que no se ha procesado la operación correctamente.
  2. Notificación indicando que sí se ha procesado la operación correctamente: Esto no implica que la operación se haya autorizado, simplemente que la operación ha sido procesada adecuadamente. 
¿Qué se recibe en la notificación que NO se ha procesado correctamente?

Si la petición NO se ha procesado correctamente, recibirás un JSON con el código de error que corresponda. Consulta los códigos de error.

				
					{
    "errorCode":"SISXXXX"
}

La notificación es un JSON 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 de tu terminal. En la notificación, el comercio debe validar que esta firma coincida con la de la petición.

¿Cómo veo el resultado de la operación?

Los parámetros que se reciben en Ds_MerchantParameters son los que indican el resultado de la operación. Estos parámetros vienen codificados en BASE64, para ver el resultado de la operación:

  • Decodifica el campo Ds_MerchantParameters. (este proceso lo puedes implementar en la validación).
  • Recupera el parámetro Ds_Response. Este campo indica el código de respuesta. (Este proceso lo puedes implementar en la validación).
    • El valor 0000 indica que ha sido autorizada. Para el resto de valores consulta la tabla de códigos de respuesta. 

¿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 información de la operación

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. Pre-procesa la clave de tu terminal: La clave tiene que tener exactamente 16 caracteres.
    • Si tiene MÁS de 16 caracteres: Utiliza únicamente los 16 primeros caracteres de la clave.
    • Si tiene MENOS de 16 caracteres: Rellena por la derecha con ceros (0) hasta llegar a 16 caracteres.
  2. Genera la clave diversificada: Esto se hace mediante un cifrado AES CBC, usando como vector de inicialización IV un vector de ceros. Este cifrado AES CBC se hace entre:
    • La clave de tu terminal pre-procesada en el paso anterior.
    • El número de pedido de la operación que has recuperado de la notificación Ds_Order (sin codificar en BASE64).
    • Realiza un cifrado AES CBC entre estos 2 valores.
  3. Codifica en BASE64: Codifica en BASE64 el resultado obtenido en el paso anterior. Este valor se llama clave diversificada, y lo utilizarás más adelante.
  4. Calcula el HMAC-SHA512: Aplica el algoritmo HMAC-SHA512 sobre el Ds_MerchantParameters codificado en BASE64, utilizando la clave diversificada obtenida en el paso anterior.
  5. Codifica en BASE64URL: Se codifica el resultado del HMAC-SHA512 en BASE64URL.
  6. Compara el valor obtenido: El valor que has obtenido es el Ds_Signature calculado a partir de la notificación. Compáralo con el Ds_Signature que has enviado en la petición.
    • Si coinciden, el flujo no ha sido alterado y puedes seguir con el proceso.

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

				
					<?php
// Este es un fragmento de código para realizar la firma y la verificación de notificación.
// Añade este código al resto de librerías de Redsys, para tener el proceso completo.
class Signature {
	/******  AES Function  ******/
	static function encrypt_AES($data, $key) {
		$fixedKey = str_pad(substr($key, 0, 16), 16, "0");
		$firma = base64_encode(openssl_encrypt($data, "aes-128-cbc", $fixedKey, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"));

		return $firma;
	}

	static function mac512($data, $key) {
		$sha = hash_hmac('sha512', $data, $key, true);
		return $sha;
	}

	static function createMerchantSignature($key, $data, $diversifyingFactor) {
		// Se diversifica la clave con el Número de Pedido
		$key = self::encrypt_AES($diversifyingFactor, $key);

		// MAC512 del parámetro Ds_Parameters que envía Redsys
		$res = self::mac512($data, $key);

		// Se codifican los datos Base64
		return Utils::base64_url_encode_safe($res);
	}
    // Función para comparar firmas. Utilizado en la verificación de la notificación.
	static function checkSignatures($sig1, $sig2) {
		if (strcasecmp($sig1, $sig2) !== 0) {
			throw new Exception("Integrity failure. The received signature does not match the calculated one.");
		}
	}
}

?>

Consulta las librerías de Redsys para ver el código completo, recomendamos utilizar la última versión de las librerías:

Librerías de Redsys

Paso 4: Timeout

Es posible que el TPV Virtual no responda a una petición REST. Esto se conoce como Timeout.

Se puede deber a dos causas:

  1. No se ha recibido la petición, con lo que TPV Virtual no responderá al mensaje de petición.
  2. El TPV Virtual ha recibido el mensaje de petición, pero no puede contactar con el Centro Autorizador. En este caso está definido un timeout de 30 segundos, por lo que si transcurrido ese tiempo, no se recibe respuesta del Centro Autorizador, se devolverá un mensaje de respuesta con código 9912/912 “Emisor no disponible”. La aplicación cliente deberá por tanto establecer un timeout mayor (unos 40 o 50 segundos), para asegurar que TPV Virtual siempre le va a responder.

¿Qué hacer en caso de timeout?

  • Peticiones de pago, preautorización o confirmación: se deberá enviar su operación de anulación correspondiente.
  • Devoluciones o anulaciones: se podrá volver a realizar la petición.

 

Integración para PSPs, MPI Externo, PUCE

Si usas un PSP (Proveedor de Servicios de Pago), hay algunas configuraciones extras que se deben hacer para integrar por REST, usar un MPI Externo u operar por PUCE. Habla con tu PSP y sigue sus indicaciones.

Próximos pasos

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

Operativas con tarjetas - REST
Métodos de pago

Anexo: Firma de la petición SHA-256

A continuación se explica el proceso de cálculo de la firma SHA-256.

Esta firma es utilizada en los siguientes pasos de la integración:

  • En el envío de la petición. Es el valor que se envía en Ds_Signature.
  • En la validación de la notificación. Se tiene que validar la firma recibida en la notificación para comprobar que coinciden.

Para nuevas integraciones recomendamos usar la firma SHA-512, aunque ambas son válidas.

¿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_Signature. Tipado: Texto plano.

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

				
					<?php
function createMerchantSignature($key){
    $key = $this->decodeBase64($key); // 1. Decodifica la clave SHA-256 en base64
    $ent = $this->createMerchantParameters(); // Crea el JSON con los datos y lo codifica en base64 (utilizado en el paso 3)
    $key = $this->encrypt_3DES($this->getOrder(), $key); // 2. Aplica 3DES con el número de pedido y la clave decodificada la función para encriptar es 3DES Function
    $res = $this->mac256($ent, $key); // 3. Calcula el HMAC-SHA256. Lo hace en la función
    return $this->encodeBase64($res); // 4. Codifica el HMAC resultante en base64. Será el valor enviado en Ds_Signature
}

/******  3DES Function  ******/
	function encrypt_3DES($message, $key){
		// Se cifra
		$l = ceil(strlen($message) / 8) * 8;
		return substr(openssl_encrypt($message . str_repeat("\0", $l - strlen($message)), 'des-ede3-cbc', $key, OPENSSL_RAW_DATA, "\0\0\0\0\0\0\0\0"), 0, $l);

	}

/******  MAC Function ******/
	function mac256($ent,$key){
		$res = hash_hmac('sha256', $ent, $key, true);//(PHP 5 >= 5.1.2)
		return $res;
	}
?>

Descarga las librerías de Redsys para implementar la firma SHA-256 en tu integración.

Librerías de Redsys

Firma SHA-256 para validar 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:
    • Esto implica utilizar el número de pedido Ds_Order recibido en la notificación (este parámetro lo recuperas al decodificar el parámetro Ds_MerchantParameters de la notificación.
    • Realiza el cálculo de la firma y compara el valor obtenido con el Ds_Signature recibido en la notificación.

Artículos

Comparte este documento
Tabla de Contenidos

Cyberpac

Consulta la documentación de Cyberpac. Aquí tienes las distintas secciones:

Canales

Módulos de integración

Integraciones a medida

Consulta la documentación de las distintas secciones de integraciones:

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Pagos integrados en TPV

Crea una solución que te ayudará a automatizar procesos. Incluso, podrás agregar procesos de pago en terminales físicos.

Pago integrado con TPV Android

Pago integrado con Smartphone TPV

Fichas Técnicas TPVs

Addon Payments

Comercia Global Payments has several integration options so you can choose the most efficient one for you.

Integrations

Frequently Asked Questions

BackOffice Portal

Consult the documentation of the different integrations sections:​

Start integration

undraw_add_to_cart_re_wrdo 1 (1) (1)

CMS Plugins

Complement your integration

SDKs

Payment Methods

Tools