El comercio utilizará la conexión WebService a Phone&Sell sms/e-mail para realizar la solicitud de una operación. Los detalles de los campos a enviar son los habituales para una conexión WebService a Phone&Sell.
Solicite el manual del TPV Virtual Plus en su oficina habitual o directamente a nuestro Servicio Técnico (ver apartado 7 del presente manual).
Las adaptaciones especiales para la operativa de Phone&Sell de Ventas telefónicas son las siguientes:
– DS_MERCHANT_CUSTOMER_MOBILE: número de teléfono del titular para enviar el SMS con el enlace.
– DS_MERCHANT_CUSTOMER_MAIL: dirección de e-mail del titular para enviar el enlace.
Phone&Sell interpretará esta petición y realizará las validaciones necesarias para, a continuación, procesar la operación. Dependiendo del resultado de la operación, se construye un documento XML de respuesta con el resultado de la misma. La petición a Phone&Sell se realiza mediante un envío WebService a la siguiente URL:
https://sis.redsys.es/sis/services/SerClsWSEntrada
WSDL del servicio: https://sis.redsys.es/sis/services/SerClsWSEntrada/wsdl/SerClsWSEntrada.wsdl
A continuación se muestra un ejemplo de mensaje que debería enviar el establecimiento dentro de la conexión WebService:
<REQUEST> <DATOSENTRADA> <DS_MERCHANT_AMOUNT>100</DS_ MERCHANT_AMOUNT> <DS_MERCHANT_ORDER>1500819980</ DS_MERCHANT_ORDER> <DS_MERCHANT_ MERCHANTCODE>223108853</DS_MERCHANT_ MERCHANTCODE> <DS_MERCHANT_CURRENCY>978</DS_ MERCHANT_CURRENCY> <DS_MERCHANT_TRANSACTIONTYPE>F</ DS_MERCHANT_TRANSACTIONTYPE> <DS_MERCHANT_CUSTOMER_ MOBILE>600000000</DS_MERCHANT_ CUSTOMER_MOBILE> <DS_MERCHANT_CUSTOMER_MAIL>titular@e-mail.com</DS_MERCHANT_CUSTOMER_MAIL> <DS_MERCHANT_PAYMETHODS>T</DS_ MERCHANT_PAYMETHODS> <DS_MERCHANT_TERMINAL>1</DS_MERCHANT_ TERMINAL> <DS_MERCHANT_P2F_ EXPIRYDATE>2017-08-06-16.30.10</DS_ MERCHANT_P2F_EXPIRYDATE> </DATOSENTRADA> <DS_SIGNATUREVERSION>HMAC_SHA256_V1</ DS_SIGNATUREVERSION> <DS_SIGNATURE>oekclJDcQNvuXx975oRiDbRyN3 gaA5rqC6xaIGtZXiw=</DS_SIGNATURE> </REQUEST>
Para que el comercio pueda realizar la petición a través del WebService de Banco Sabadell, es necesario intercambiar una serie de datos, tanto en los mensajes de petición como en los mensajes de respuesta.
La estructura del mensaje siempre será la misma, estableciendo como raíz del mismo el elemento <REQUEST>. En su interior siempre deben encontrarse tres elementos que hacen referencia a:
A continuación se muestra un ejemplo de un mensaje de petición de pago:
<REQUEST> <DATOSENTRADA> <DS_MERCHANT_AMOUNT>100</DS_MERCHANT_AMOUNT> <DS_MERCHANT_ORDER>1500890045</DS_MERCHANT_ORDER> <DS_MERCHANT_MERCHANTCODE>327234688</DS_ MERCHANT_MERCHANTCODE> <DS_MERCHANT_CURRENCY>978</DS_MERCHANT_ CURRENCY> <DS_MERCHANT_TRANSACTIONTYPE>F</DS_MERCHANT_ TRANSACTIONTYPE> <DS_MERCHANT_CUSTOMER_MOBILE></DS_MERCHANT_ CUSTOMER_MOBILE> <DS_MERCHANT_CUSTOMER_MAIL>tpvvirtual@bancsabadell. com</DS_MERCHANT_CUSTOMER_MAIL> <DS_MERCHANT_TERMINAL>1</DS_MERCHANT_TERMINAL> <DS_MERCHANT_MERCHANTURL>http://www.urlcomercio. com/notificacion.php</DS_MERCHANT_MERCHANTURL> </DATOSENTRADA> <DS_SIGNATUREVERSION>HMAC_SHA256_V1</DS_ SIGNATUREVERSION> <DS_SIGNATURE>9ZGCSvg0XAOFj93k9G7Id4vKrm0Vmx4uj7/ oEhKbYLA=</DS_SIGNATURE> </REQUEST>
Para facilitar la integración del comercio, a continuación se explican de forma detallada los pasos a seguir para montar el mensaje de petición de pago.
Se debe generar una cadena con todos los datos de la petición en formato XML dando como resultado el elemento <DATOSENTRADA>.
Se debe tener en cuenta que existen varios tipos de peticiones y según el tipo varía la estructura del mensaje y los parámetros que se envían y reciben.
Podemos diferenciar tres tipos de peticiones:
En la petición se debe identificar la versión concreta de algoritmo que se está utilizando para la firma. Actualmente se utiliza el valor HMAC_SHA256_V1 para identificar la versión de todas las peticiones, por lo que este será el valor del elemento <DS_SIGNATUREVERSION>.
Para calcular la firma es necesario utilizar una clave específica para cada terminal. La clave de comercio que debe utilizar es la que recibió a través de SMS desde Banco Sabadell.
NOTA IMPORTANTE: Esta clave debe ser almacenada en el servidor del comercio de la forma más segura posible para evitar un uso fraudulento de la misma. El comercio es responsable de la adecuada custodia y mantenimiento en secreto de dicha clave.
Una vez se ha generado el elemento con los datos de la petición de pago (<DATOSENTRADA>) y la clave específica del terminal, se debe calcular la firma siguiendo los siguientes pasos:
En este apartado se explica cómo se utilizan las librerías disponibles en PHP y JAVA para facilitar los desarrollos y la generación de la firma.
Librería PHP
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería PHP proporcionada por Banco Sabadell:
include ‘../apiRedsysWs.php’;
El comercio debe decidir si la importación desea hacerla con la función “include” o “required”, según los desarrollos realizados.
$miObj = new RedsysAPIWs;
$datoEntrada=’<DATOSENTRADA><DS_MERCHANT_ AMOUNT>’.$importe.’</DS_MERCHANT_AMOUNT><DS_ MERCHANT_ORDER>’.$num_pedido.’</DS_MERCHANT_ ORDER><DS_MERCHANT_MERCHANTCODE>’.$fuc.’</ DS_MERCHANT_MERCHANTCODE><DS_MERCHANT_CURRENCY>’.$moneda.’</DS_MERCHANT_CURRENCY><DS_MERCHANT_TRANS ACTIONTYPE>’.$tipoTransaccion.’</DS_MERCHANT_TRANSACTIONTYPE><DS_MERCHANT_TERMINAL>’.$terminal.’</ DS_MERCHANT_TERMINAL><DS_MERCHANT_ MERCHANTURL>’.$mUrl.’</DS_MERCHANT_MERCHANTURL></DATOSENTRADA>’; $clave = ‘sq7HjrUOBfKmC576ILgskD5srU870gJ7’; $signature = $miObj->createMerchantSignatureHostToHo st($clave, $datoEntrada);
Una vez obtenido el valor del elemento <DS_SIGNATURE>, ya es posible completar el mensaje de petición de pago y realizar la llamada WebService.
Librería JAVA
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería JAVA proporcionada por Banco Sabadell:
<%@page import=”sis.redsys.api.ApiWsMacSha256”%>
El comercio debe incluir en la vía de construcción del proyectotodas las librerías (JARs) que se proporcionan:
lib
apiSha256.jar
bcprov - jdk15on-1.4.7.jar
commons - codec-1.3.jar
org.json.jar
ApiWsMacSha256 apiWsMacSha256 = new ApiWsMacSha256();
String datosEntrada = “<DATOSENTRADA><DS_MERCHANT_AMOUNT>100</DS_MERCHANT_AMOUNT><DS_MERCHANT_ORDER>1500890045</DS_MERCHANT_ORDER><DS_MERCHANT_MERCHANTCODE>327234688</DS_MERCHANT_MERCHANTCODE><DS_MERCHANT_CURRENCY>978</DS_MERCHANT_CURRENCY><DS_MERCHANT_TRANSACTIONTYPE>F</DS_MERCHANT_TRANSACTIONTYPE><DS_MERCHANT_CUSTOMER_MOBILE></DS_MERCHANT_CUSTOMER_MOBILE><DS_MERCHANT_CUSTOMER_MAIL>tpvvirtual@bancsabadell.com</DS_MERCHANT_CUSTOMER_MAIL><DS_MERCHANT_TERMINAL>1</DS_MERCHANT_TERMINAL><DS_MERCHANT_MERCHANTURL>http://www.urlcomercio.com/notificacion.php</DS_MERCHANT_MERCHANTURL></DATOSENTRADA>”;String clave = “sq7HjrUOBfKmC576ILgskD5srU870gJ7”;String firma = apiWsMacSha256.createMerchantSignatureHostToHost(clave, datosEntrada);
Una vez obtenido el valor del elemento <DS_SIGNATURE>, ya se puedo completar el mensaje de petición de pago y realizar la llamada WebService.
Librería .NET
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería .NET proporcionada por Banco Sabadell:
Using RedsysAPIPrj;
WebRedsysApi.WebRedsysWs.SerclsWSEntradaService s = new WebRedsysAPI.WebRedsysWs.SerClsWSEntradaService();
Nota: En el atributo location de la etiqueta <wsdlsoap:address> del fichero SerCls-WSEntrada.wsdl, indicar si se trata del entorno real o pruebas:
https://sis.redsys.es/sis/services/SerClsWSEntrada (Real)
RedsysAPIWs r = new RedsysAPIWs();
Al realizar este paso se inicializan los atributos diccionario clave/valor m_keyvalues y cryp de la clase Cryptogra (Clase auxiliar para realizar las operaciones criptográficas necesarias).
string datoEntrada = r.GenerateDatoEntradaXML(importe, merchantCode, moneda, numTarjeta, cvv2, transactionType, terminal, expiryDate);
string firma = r.createMerchantSignatureHostToHost(cla ve, datoEntrada);
Una vez obtenido el valor del elemento <DS_SIGNATURE>, ya se puede completar el mensaje de petición de pago y realizar la llamada Host to Host.
Se genera el string XML final de petición de pago con DATOSENTRADA, DS_ SIGNATUREVERSION y DS_SIGNATURE calculado en punto 5.
string requestXML = r.GenerateRequestXML(datoEntra da, firma);
Después se llama al método trataPeticion del WebService de Redsys pasándole como parámetro el string XML final calculado con el método GenerateRequestXML.
string result = s.trataPeticion(requestXML);
En el presente apartado se describen los datos que forman parte del mensaje de respuesta de una petición al TPV Virtual WebService. Este mensaje se genera en formato XML y a continuación se muestra un ejemplo del mismo:
<RETORNOXML> <CODIGO>0</CODIGO> <OPERACION> <Ds_Amount>100</Ds_Amount> <Ds_Currency>978</Ds_Currency> <Ds_Order>1500890045</Ds_Order> <Ds_Signature>9KUKWBFQgVY+1lplewUW0AShsdrBs0rwG 1jsztesT4M=</Ds_Signature> <Ds_MerchantCode>327234688</Ds_MerchantCode> <Ds_Terminal>1</Ds_Terminal> <Ds_Response>9998</Ds_Response> <Ds_AuthorisationCode></Ds_AuthorisationCode> <Ds_TransactionType>F</Ds_TransactionType> <Ds_SecurePayment>0</Ds_SecurePayment> <Ds_Language>1</Ds_Language> <Ds_MerchantData></Ds_MerchantData> <Ds_UrlPago2Fases>https://sis.redsys.es/sis/p2f?t=C14A33F19156E1F258B46CE06D45D5D7BD4611A4</Ds_UrlPago2Fases> </OPERACION> </RETORNOXML>
Como se puede observar en el ejemplo anterior, la respuesta está formada por dos elementos principales:
El campo Ds_UrlPago2Fases contiene la URL de pago que se ha enviado por SMS o por e-mail al titular.
Una vez se ha obtenido el mensaje de respuesta y la clave específica del terminal, siempre y cuando la operación se autorice, se debe comprobar la firma de la respuesta siguiendo los siguientes pasos:
Cadena = Ds_Amount + Ds_Order + Ds_MerchantCode + Ds_Currency + Ds_Response + Ds_TransactionType + Ds_SecurePayment
Si tomamos como ejemplo la respuesta que se presenta al inicio de este apartado, la cadena resultante sería:
Cadena = 1451444912789999008881978000000
Si el comercio tiene configurado envío de tarjeta asteriscada en la respuesta, se debe calcular el HMAC SHA256 de la cadena formada por la concatenación del valor de los siguientes campos:
Cadena = Ds_Amount + Ds_Order + Ds_MerchantCode + Ds_Currency + Ds_Response + Ds_CardNumber + Ds_TransactionType + Ds_SecurePayment
Si tomamos como ejemplo la respuesta que se presenta al inicio de este apartado, la cadena resultante sería:
Cadena = 14514498215459990088819780000454881******000400
En este apartado se explica cómo se utilizan las librerías disponibles en PHP y JAVA para facilitar los desarrollos y la generación de la firma de respuesta.
Librería PHP
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería PHP proporcionada por Banco Sabadell:
Include ‘./apiRedsysWs.php’;
El comercio debe decidir si la importación desea hacerla con la función “include” o “required”, según los desarrollos realizados.
$miObj = new RedsysAPIWs;
$cadenaConcatenada = “1451510291422293272346889780000A0”;$numPedido = “151029142229”;$clave = ‘sq7HjrUOBfKmC576ILgskD5srU870gJ7’;$firma = $miObj->createMerchantSignatureResponseHostToHost($clave, $cadenaConcatenada, $numPedido);
El resultado obtenido debe ser el mismo que el valor del parámetro <Ds_Signature> obtenido en la respuesta.
Librería JAVA
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería JAVA proporcionada por Banco Sabadell:
<%@page import=”sis.redsys.api.ApiWsMacSha256”%>
El comercio debe incluir en la vía de construcción del proyecto todas las librerías (JARs) que se proporcionan:
lib
apiSha256.jar
bcprov - jdk15on-1.4.7.jar
commons - codec-1.3.jar
org.json.jar
ApiWsMacSha256 apiWsMacSha256 = new ApiWsMacSha256();
String cadenaConcatenada = “1451510291422293272 346889780000A0”; String numPedido = “151029142229”; String clave = “sq7HjrUOBfKmC576ILgskD5srU870gJ7”; String firma = apiMacSha256.createMerchantSignat ureResponseHostToHost(clave, cadenaConcatenada, numPedido);
El resultado obtenido debe ser el mismo que el valor del parámetro <Ds_Signature> obtenido en la respuesta.
Librería .Net
A continuación se presentan los pasos que debe seguir un comercio para la utilización de la librería .NET proporcionada por Redsys:
r.XMLToDiccionary(result);
string cadena = r.GenerateCadena(result); string numOrder = r.GetDictionary(“Ds_Order”); string firmaCalculada = r.createSignatureResponseHostT oHost(clave, cadena, numOrder);
El resultado obtenido debe ser el mismo que el valor del parámetro <Ds_Signature> obtenido en la respuesta.