Integración REST
![](img/flujo-rest.png)
Parámetros de envío
Para realizar una integración vía REST, el comercio debe enviar una petición al TPV Get Checkout ES con los datos del pago en formato JSON con los siguientes parámetros:
- Ds_MerchantParameters: Datos de la petición de pago codificados en Base64.
- Ds_SignatureVersion: Versión del algoritmo de firma.
- Ds_Signature: Firma generada con los datos de pago.
En función del entorno en el que se desee operar, se enviará la petición al endpoint correspondiente:
Entorno | URL conexión |
---|---|
Pruebas | https://sis-t.redsys.es:25443/sis/rest/trataPeticionREST |
Real | https://sis.redsys.es/sis/rest/trataPeticionREST |
A continuación se detalla la formación de cada parámetro de la petición de pago:
Ds_MerchantParameters.
Se debe montar una cadena en formato JSON con todos los datos de la petición. El nombre de cada parámetro debe indicarse en mayúsculas o con estructura “CamelCase” (Por ejemplo: DS_MERCHANT_AMOUNT o Ds_Merchant_Amount). La lista de parámetros que se pueden incluir en la petición se puede ver aquí.
Para todas las peticiones se deben enviar los parámetros obligatorios. Los parámetros adicionales deben usarse si el comercio desea utilizar operativas especiales, como por ejemplo el “Pago por referencia” o "Pago 1-Click". En este caso, se deberán incluir los parámetros específicos de este tipo de operativa en el parámetro "Ds_MerchantParameters".
A continuación, se muestran un ejemplo de la cadena en formato JSON:
{
"DS_MERCHANT_AMOUNT": "145",
"DS_MERCHANT_CURRENCY": "978",
"DS_MERCHANT_CVV2": "123",
"DS_MERCHANT_EXPIRYDATE": "1512",
"DS_MERCHANT_MERCHANTCODE": "999008881",
"DS_MERCHANT_ORDER": "1446068581",
"DS_MERCHANT_PAN": "454881********04",
"DS_MERCHANT_TERMINAL": "49",
"DS_MERCHANT_TRANSACTIONTYPE": "0"
}
Tras montar la cadena, es necesario codificarla en BASE64 sin espacios en blanco. La cadena resultante de la codificación en BASE64 será el valor del parámetro "Ds_MerchantParameters":
eyJEU19NRVJDSEFOVF9BTU9VTlQiOiIxNDUiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjE0NDYwNjg1ODEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfUEFOIjoiNDU0ODgxMjA0OTQwMDAwNCIsIkRTX01FUkNIQU5UX0VYUElSWURBVEUiOiIxNTEyIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyJ9
Ds_SignatureVersion
En la petición se debe identificar la versión concreta de algoritmo que se está utilizando para la firma. Actualmente se utiliza el valor HMAC_SHA256_V1 para identificar la versión de todas las peticiones, por lo que este será el valor de éste parámetro.
Ds_Signature.
La firma de la operación ("Ds_Signature") se calculará utilizando el parámetro "Ds_MerchantParameters" (ya codificado en BASE64), y la clave específica del terminal (clave del comercio). Ésta clave se puede obtener accediendo al Módulo de Administración, opción Consulta datos de Comercio, en el apartado “Ver clave”, tal y como se muestra en la siguiente imagen:
![descripcion general del flujo](img/claveFirmaWS.png)
- Una vez obtenida la clave del comercio debe decodificarse en BASE64.
- Diversificar la clave de firma realizando un cifrado 3DES entre esta clave codificada y el valor del número de pedido de la operación (Ds_Merchant_Order).
- Se realiza el cálculo del HMAC-256 con el parámentro "Ds_MerchantParameters" y la clave de firma diversificada.
- El valor del HMAC SHA256 debe codificarse en BASE64,
siendo su resultado el valor de la firma.
NOTA: Si la petición se hace mediante cURL o mediante el navegador Safari, puede que se conviertan los símbolos “+” en espacio en blanco. Para que esto no ocurra se deben sustituir los símbolos “+” de la firma por “%2B” (Valor URL encoded)
Mensaje de petición
Ejemplo de mensaje en formato JSON enviado en la petición REST:
{"Ds_MerchantParameters":"eyJEU19NRVJDSEFOVF9BTU9VTlQiOiIxNDUiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjE0NDYwNjg1ODEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfUEFOIjoiNDU0ODgxMjA0OTQwMDAwNCIsIkRTX01FUkNIQU5UX0VYUElSWURBVEUiOiIxNTEyIiwiRFNfTUVSQ0hBTlRfQ1ZWMiI6IjEyMyJ9","Ds_Signature":"Da5q+leqj4ytBKC3T0y/ThshxSe+8Wkh0wnn8Fx1wug=","Ds_SignatureVersion":"HMAC_SHA256_V1"}
Mensaje de respuesta
Tras el envío de la petición al TPV Get Checkout ES, el comercio recibe una respuesta que debe capturar. Se puede recibir dos tipos de respuesta:
Operación rechazada.
Si se ha obtenido algún error en el procesamiento de la petición, el mensaj e de respuesta contendrá un único parámetro (errorCode).
{ "errorCode":"SISXXXX"}
Operación procesada correctamente.
En el caso que se haya procesado la operación, se recibirán los "parámetros de salida" con el resultado de la operación dentro del parámetro "Ds_MerchantParameters", el cuál deberá decodificarse en BASE64
{"Ds_SignatureVersion":"HMAC_SHA256_V1","Ds_MerchantParameters":"eyJEc19BbW91bnQiOiIxNDUiLCJEc19DdXJyZW5jeSI6Ijk3OCIsIkRzX09yZGVyIjoiMTQ0NjA2ODU4MSIsIkRzX01lcmNoYW50Q29kZSI6Ijk5OTAwODg4MSIsIkRzX1Rlcm1pbmFsIjoiMSIsIkRzX1Jlc3BvbnNlIjoiMDAwMCIsIkRzX0F1dGhvcmlzYXRpb25Db2RlIjoiNTAxNjAyIiwiRHNfVHJhbnNhY3Rpb25UeXBlIjoiMCIsIkRzX1NlY3VyZVBheW1lbnQiOiIwIiwiRHNfTGFuZ3VhZ2UiOiIxIiwiRHNfQ2FyZE51bWJlciI6IjQ1NDg4MSoqKioqKioqMDQiLCJEc19NZXJjaGFudERhdGEiOiIiLCJEc19DYXJkX0NvdW50cnkiOiI3MjQiLCJEc19DYXJkX0JyYW5kIjoiMSJ9","Ds_Signature":"QVxoXwwp919v7XYjyBjhr1VXozESRosHPb3PDW-rcME="}
Por ejemplo, para una autorización, debemos comprobar si el pago se ha autorizado o denegado. Para ello, se debe decodificar el parámetro "Ds_MerchantParameters" devuelto en la respuesta. El resultado de la misma se informa en el parámetro "Ds_Response."
{
"Ds_Amount": "145",
"Ds_AuthorisationCode": "501602",
"Ds_CardNumber": "454881********04",
"Ds_Card_Brand": "1",
"Ds_Card_Country": "724",
"Ds_Currency": "978",
"Ds_Language": "1",
"Ds_MerchantCode": "999008881",
"Ds_MerchantData": "",
"Ds_Order": "1446068581",
"Ds_Response": "0000",
"Ds_SecurePayment": "0",
"Ds_Terminal": "1",
"Ds_TransactionType": "0"
}
Se recomienda a los comercios que una vez se obtenga la respuesta, se valide la firma recibida en la petición para prevenir el fraude. Para ello, se debe calcular la firma con los parámetros recibidos y validar que su valor sea igual al recibido en la respuesta.
API Rest y librerías de ayuda
De forma opcional, Redsys pone a su disposición una API de conexión Rest para facilitar este tipo de integración, por otra parte, si no desea utilizarse, también se suministran librerias (disponibles en PHP, JAVA y .NET) que simplifican la generación de la firma por parte del comercio. En este apartado se explica cómo se utilizan estas librerias.
Envío de petición.
/* Importar el fichero principal de la librería, tal y como se muestra a
continuación: */
include_once 'redsysHMAC256_API_PHP_4.0.2/apiRedsys.php';
//El comercio debe decidir si la importación desea hacerla con la función
“include” o “required”, según los desarrollos realizados.
/* Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación: */
$miObj = new RedsysAPI;
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el cálculo
de este parámetro, inicialmente se deben añadir todos los parámetros de la
petición de pago que se desea enviar, tal y como se muestra a continuación: */
$miObj->setParameter("DS_MERCHANT_AMOUNT", $amount);
$miObj->setParameter("DS_MERCHANT_ORDER", $id);
$miObj->setParameter("DS_MERCHANT_MERCHANTCODE", $fuc);
$miObj->setParameter("DS_MERCHANT_CURRENCY", $moneda);
$miObj->setParameter("DS_MERCHANT_TRANSACTIONTYPE", $trans);
$miObj->setParameter("DS_MERCHANT_TERMINAL", $terminal);
$miObj->setParameter("DS_MERCHANT_MERCHANTURL", $url);
$miObj->setParameter("DS_MERCHANT_URLOK", $urlOK);
$miObj->setParameter("DS_MERCHANT_URLKO", $urlKO);
/*Por último, para calcular el parámetro Ds_MerchantParameters, se debe
llamar a la función de la librería “createMerchantParameters()”, tal y como
se muestra a continuación: */
$params = $miObj->createMerchantParameters();
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio (obteniendola
en el panel del módulo de administración), tal y como se muestra a
continuación: */
$claveSHA256 = 'sq7HjrUOBfKmC576ILgskD5srU870gJ7';
$firma = $miObj->createMerchantSignature($claveSHA256);
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters y
Ds_Signature , se debe rellenar la petición REST con dichos valores y el parámetro Ds_SignatureVersion */
/* Importar la librería, tal y como se muestra a continuación */
<%@page import = "sis.redsys.api.ApiMacSha256" %>
/* Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación */
ApiMacSha256 apiMacSha256 = new ApiMacSha256();
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el
cálculo de este parámetro, inicialmente se deben añadir todos los
parámetros de la petición de pago que se desea enviar, tal y como se
muestra a continuación: */
apiMacSha256.setParameter("DS_MERCHANT_AMOUNT", amount)
apiMacSha256.setParameter("DS_MERCHANT_ORDER", id)
apiMacSha256.setParameter("DS_MERCHANT_MERCHANTCODE", fuc)
apiMacSha256.setParameter("DS_MERCHANT_CURRENCY", moneda)
apiMacSha256.setParameter("DS_MERCHANT_TRANSACTIONTYPE", trans)
apiMacSha256.setParameter("DS_MERCHANT_TERMINAL", terminal)
apiMacSha256.setParameter("DS_MERCHANT_MERCHANTURL", url)
apiMacSha256.setParameter("DS_MERCHANT_URLOK", urlOK)
apiMacSha256.setParameter("DS_MERCHANT_URLKO", urlKO)
/* Por último se debe llamar a la función de la librería
“createMerchantParameters()”, tal y como se muestra a continuación: */
String params = apiMacSha256.createMerchantParameters()
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de
este parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio
(obteniendola en el panel del módulo de administración), tal y como se
muestra a continuación: */
String claveModuloAdmin = "sq7HjrUOBfKmC576ILgskD5srU870gJ7v";
String firma = apiMacSha256.createMerchantSignature(claveSHA256);
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters y
Ds_Signature , se debe rellenar la petición REST con dichos valores y el parámetro Ds_SignatureVersion */
/* Importar la librería RedsysAPI y Newronsoft.Json en su proyecto */
<%@ Import namepace="sis.redsys.api.ApiMacSha256" %>
/* Calcular el parámetro Ds_MerchantParameters. Para llevar a cabo el cálculo
de este parámetro, inicialmente se deben añadir todos los parámetros de la
petición de pago que se desea enviar, tal y como se muestra a continuación: */
RedsysAPI r = new RedsysAPI()
r.setParameter ("DS_MERCHANT_AMOUNT", amount);
r.setParameter("DS_MERCHANT_ORDER", id);
r.setParameter("DS_MERCHANT_MERCHANTCODE", fuc);
r.setParameter("DS_MERCHANT_CURRENCY", moneda);
r.setParameter("DS_MERCHANT_TRANSACTIONTYPE", trans);
r.setParameter("DS_MERCHANT_TERMINAL", terminal);
r.setParameter("DS_MERCHANT_MERCHANTURL", url);
r.setParameter("DS_MERCHANT_URLOK", urlOK);
r.setParameter("DS_MERCHANT_URLKO", urlKO);
/* Por último se debe llamar a la función de la librería
“createMerchantParameters()” para crear los parámetros y asignar dicho valor a
la etiqueta Ds_MerchantrParameters, tal y como se muestra a continuación: */
string params = r.createMerchantParameters();
Ds_MerchantParameters.value = params;
/* Calcular el parámetro Ds_Signature. Para llevar a cabo el cálculo de este
parámetro, se debe llamar a la función de la librería
“createMerchantSignature()” con la clave SHA-256 del comercio (obteniendola en
el panel del módulo de administración), tal y como se muestra a continuación:
*/
string firma = r.createMerchantSignature(kcSHA256);
Ds_Signature.value = firma;
/* Una vez obtenidos los valores de los parámetros Ds_MerchantParameters y
Ds_Signature , se debe rellenar la petición REST con dichos valores y el parámetro Ds_SignatureVersion */
Respuesta de petición.
/*Importar el fichero principal de la librería, tal y como se muestra
a continuación. El comercio debe decidir si la importación desea hacerla con la
función “include” o “required”, según los desarrollos realizados.*/
include_once 'redsysHMAC256_API_PHP_4.0.2/apiRedsys.php';
/*Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
$miObj = new RedsysAPI;
/*Capturar los parámetros de la notificación on-line:*/
$version = $_GET["Ds_SignatureVersion"];
$params = $_GET["Ds_MerchantParameters"];
$signatureRecibida = $_GET["Ds_Signature"];
/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
$decodec = $miObj->decodeMerchantParameters($params);
/*Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
notificación on-line. Para llevar a cabo la obtención del valor de un
parámetro se debe llamar a la función “getParameter()” de la
librería con el nombre de parámetro, tal y como se muestra a
continuación para obtener el código de respuesta:*/
$codigoRespuesta = $miObj->getParameters("Ds_Response");
/** NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/
/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
$claveModuloAdmin = 'sq7HjrUOBfKmC576ILgskD5srU870gJ7';
$signatureCalculada = $miObj->createMerchantSignatureNotif($claveModuloAdmin, $params);
/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
if ($signatureCalculada === $signatureRecibida) {
echo "FIRMA OK. Realizar tareas en el servidor";
} else {
echo "FIRMA KO. Error, firma inválida";
}
/* Importar libreria, tal y como se muestra a continuación: */
<%@page import="sis.redsys.api.ApiMacSha256" %>
/*El comercio debe incluir en la vía de construcción del proyecto
todas las librerías(JARs) que se proporcionan:*/
/*Definir un objeto de la clase principal de la librería, tal y como se
muestra a continuación:*/
ApiMacSha256 apiMacSha256 = new ApiMacSha256();
/*Capturar los parámetros del retorno de control de navegación:*/
String version = request.getParameter("Ds_SignatureVersion");
String params = request.getParameter("Ds_MerchantParameters");
String signatureRecibida = request.getParameters("Ds_Signature");
/*Decodificar el parámetro Ds_MerchantParameters. Para llevar
a cabo la decodificación de este parámetro, se debe llamar a la
función de la librería “decodeMerchantParameters()”, tal y como
se muestra a continuación:*/
String decodec = apiMacSha256.decodeMerchantParameters(params);
/*Una vez se ha realizado la llamada a la función
“decodeMerchantParameters()”, se puede obtener el valor de
cualquier parámetro que sea susceptible de incluirse en la
retorno de control de navegación. Para llevar a cabo la obtención del
valor de un parámetro se debe llamar a la función
“getParameter()” de la librería con el nombre de parámetro, tal y
como se muestra a continuación para obtener el código de
respuesta:*/
String codigoRespuesta = apiMacSha256.getParameter("Ds_Response");
/**NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/
/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
String claveModuloAdmin = "sq7HjrUOBfKmC576ILgskD5srU870gJ7";
String signatureCalculada = apiMacSha256.createMerchantSignatureNotif(claveModuloAdmin, params);
/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
if (signatureCalculada.equals(signatureRecibida)) {
System.out.println("FIRMA OK. Realizar tareas en el servidor");
} else {
System.out.println("FIRMA KO. Error, firma inválida");
}
/*Importar la librería, tal y como se muestra a continuación:*/
using RedsysAPIPrj;
/*Definir un objeto de la clase principal de la librería, tal y como se muestra a
continuación:*/
RedsysAPI r = new RedsysAPI()
/*Capturar los parámetros del retorno de control de navegación:*/
string version = Request.QueryString["Ds_SignatureVersion"];
string params = Request.QueryString["Ds_MerchantParameters"];
string signatureRecibida = Request.QueryString["Ds_Signature"];
/** NOTA IMPORTANTE: Es importante llevar a cabo la
validación de todos los parámetros que se envían en la
comunicación. Para actualizar el estado del pedido de
forma on-line NO debe usarse esta comunicación, sino la
notificación on-line descrita en los otros apartados, ya que
el retorno de la navegación depende de las acciones del
cliente en su navegador.*/
/*Validar el parámetro Ds_Signature. Para llevar a cabo la
validación de este parámetro se debe calcular la firma y
compararla con el parámetro Ds_Signature capturado. Para ello
se debe llamar a la función de la librería
“createMerchantSignatureNotif()” con la clave obtenida del
módulo de administración y el parámetro
Ds_MerchantParameters capturado, tal y como se muestra a
continuación:*/
string kc = "Mk9m98IfEblmPfrpsawt7BmxObt98Jev";
string signatureCalculada = r.createMerchantSignatureNotif(kc, params);
/*Una vez hecho esto, ya se puede validar si el valor de la firma
enviada coincide con el valor de la firma calculada, tal y como se
muestra a continuación:*/
if(signatureRecibida == signatureCalculada) {
result.InnerHTML = "FIRMA OK. Realizar tareas en el servidor."
} else {
result.InnerHTML = "FIRMA KO. Error, firma inválida."
}