Anexo: Integración WebService

Instrucciones de conexión

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:

• Nuevo tipo de operación para indicar que el pago se realizará en dos fases. El nuevo tipo de operación utilizado para esta operativa será la “F”: pago en dos fases.
• Incorporación de nuevos campos para informar del teléfono o e-mail del titular. El establecimiento deberá enviar al menos uno de los siguientes parámetros si desea que Phone&Sell envíe el enlace al usuario:

– DS_MERCHANT_CUSTOMER_MOBILE: número de teléfono del titular para en­viar 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. De­pendiendo 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/SerCl­sWSEntrada

WSDL del servicio: https://sis.redsys.es/sis/services/SerCl­sWSEntrada/wsdl/SerClsWSEntrada.wsdl

Ejemplos de peticiones

A continuación se muestra un ejemplo de mensaje que debería enviar el estableci­miento dentro de la conexión WebService:

• HTML

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

Mensaje de petición de pago WebService

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:

• Datos de la petición de pago. Elemento iden­tificado por la etiqueta <DATOSENTRADA>.
• Versión del algoritmo de firma. Elemento identificado por la etiqueta <DS_SIGNATU­REVERSION>.
• Firma de los datos de la petición de pago. Elemento identificado por la etiqueta <DS_SIGNATURE>.

A continuación se muestra un ejemplo de un mensaje de petición de pago:

• HTML

<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.

Montar la cadena de datos de la petición

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:

• Peticiones de pago (con envío de datos de tarjeta). En el Anexo IV del apartado Anexos del presente documento, se presentan los parámetros necesarios para este tipo de petición.
• Peticiones de confirmación/devolución. En el Anexo IV del apartado Anexos del presente documento, se presentan los parámetros necesarios para este tipo de petición.
• Para comercios que utilicen operativas especiales como el “Pago por referencia” (Pago 1-Clic), deberán incluir los campos específicos de este tipo de operativa en el elemento <DATOSENTRADA>. Estos campos se incluyen en el Anexo IV.

Identificar la versión de algoritmo de firma a utilizar

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>.

Identificar la clave a utilizar para la firma

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.

Firmar los datos de la petición

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:

1. Se genera una clave específica por opera­ción. Para obtener la clave derivada a utili­zar en una operación se debe realizar un cifrado 3DES entre la clave del comercio, la cual debe ser previamente decodificada en BASE 64, y el valor del número de pedido de la operación (DS_MERCHANT_ORDER).
2. Se calcula el HMAC SHA256 del elemento <DATOSENTRADA>.
3. El resultado obtenido se codifica en BASE 64, y el resultado de la codificación será el valor del elemento <DS_SIGNATURE>.

Utilización de librerías de ayuda

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:

1. Importar el fichero principal de la librería, tal y como se muestra a continuación:

include ‘../apiRedsysWs.php’;

El comercio debe decidir si la importación desea hacerla con la función “include” o “required”, según los desarrollos rea­lizados.

2. Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación:

$miObj = new RedsysAPIWs;

3. Calcular el elemento <DS_SIGNATURE>. Para llevar a cabo el cálculo de este pa­rámetro, se debe llamar a la función de la librería “createMerchantSignatureHostToH ost()”con la clave de comercio facilitada y el elemento con los datos de la petición de pago (<DATOSENTRADA>), tal y como se muestra a continuación:

$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_MER­CHANT_CURRENCY>’.$moneda.’</DS_MER­CHANT_CURRENCY><DS_MERCHANT_TRANS ACTIONTYPE>’.$tipoTransaccion.’</DS_MER­CHANT_TRANSACTIONTYPE><DS_MER­CHANT_TERMINAL>’.$terminal.’</ DS_MERCHANT_TERMINAL><DS_MERCHANT_ MERCHANTURL>’.$mUrl.’</DS_MERCHANT_MERCHAN­TURL></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:

1. Importar la librería, tal y como se muestra a continuación:

<%@page import=”sis.redsys.api.ApiWsMacSha256”%>

El comercio debe incluir en la vía de cons­trucció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

2. Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación:

ApiWsMacSha256 apiWsMacSha256 = new ApiWs­MacSha256();

3. Calcular el elemento <DS_SIGNATURE>. Para llevar a cabo el cálculo de este pa­rámetro, se debe llamar a la función de la librería “createMerchantSignatureHostTo­Host()” con la clave de comercio facilitada y el elemento con los datos de la petición de pago (<DATOSENTRADA>), tal y como se muestra a continuación:

String datosEntrada = “<DATOSENTRADA><DS_MERCHANT_AMOUNT>100</DS_MERCHANT_AMOUNT><DS_MERCHANT_ORDER>1500890045</DS_MERCHANT_ORDER><DS_MER­CHANT_MERCHANTCODE>327234688</DS_MERCHANT_MERCHANTCODE><DS_MER­CHANT_CURRENCY>978</DS_MERCHANT_CURRENCY><DS_MERCHANT_TRANSACTIONTYPE>F</DS_MERCHANT_TRANSACTIONTYPE><DS_MER­CHANT_CUSTOMER_MOBILE></DS_MERCHANT_CUSTOMER_MOBILE><DS_MERCHANT_CUS­TOMER_MAIL>tpvvirtual@bancsabadell.com</DS_MERCHANT_CUSTOMER_MAIL><DS_MERCHANT_TERMINAL>1</DS_MERCHANT_TERMINAL><DS_MER­CHANT_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:

1. Importar la librería, tal y como se muestra a continuación:

Using RedsysAPIPrj;

2. Crear un objeto de la clase del WebService de Redsys. Para ello es necesario añadir una nueva referencia web con el fichero SerClsWSEntrada.wsdl.

WebRedsysApi.WebRedsysWs.SerclsWSEntradaService s = new WebRedsysAPI.WebRedsysWs.SerClsWSEntra­daService();

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)

3. Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación:

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).

4. Generar parámetros de DATOSENTRADA (modalidad petición de pago con envío de datos de tarjeta) mediante la función:

string datoEntrada = r.GenerateDatoEntradaXML(importe, merchantCode, moneda, numTarjeta, cvv2, transactionType, terminal, expiryDate);

5. Calcular el elemento <DS_SIGNATURE>. Para llevar a cabo el cálculo de este pa­rámetro, se debe llamar a la función de la librería “createMerchantSignatureHostTo­Host()” con la clave obtenida del módulo de administración y el elemento con los datos de la petición de pago (<DATOSENTRADA>), tal y como se muestra a continuación:

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);

Respuesta de petición WebService

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:

• XML

<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:

• Código (<CODIGO>): Indica si la operación ha sido correcta o no (no indica si ha sido autorizada, solo si se ha procesado). Un 0 indica que la operación ha sido correcta. En el caso de que sea distinto de 0, tendrá un código. (Ver códigos de error en Anexo III de este manual.)
• Datos de la operación (<OPERACION>): Recoge toda la información necesaria sobre la operación que se ha realizado. Mediante este elemento se determina si la operación ha sido autorizada o no.

El campo Ds_UrlPago2Fases contiene la URL de pago que se ha enviado por SMS o por e-mail al titular.

Firma del mensaje de respuesta

Una vez se ha obtenido el mensaje de res­puesta 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:

1. Se genera una clave específica por operación. Para obtener la clave derivada a utilizar en una operación, se debe realizar un cifrado 3DES entre la clave del comercio, la cual debe ser previamente decodificada en BASE 64, y el valor del número de pedido de la operación (DS_ORDER).
2. Se calcula 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_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 

3. El resultado obtenido se codifica en BASE 64, y el resultado de la codificación debe ser el mismo que el valor del parámetro <Ds_Signature> obtenido en la respuesta

Utilización de librerías de ayuda

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:

1. Importar el fichero principal de la librería, tal y como se muestra a continuación:

Include ‘./apiRedsysWs.php’;

El comercio debe decidir si la importación desea hacerla con la función “include” o “required”, según los desarrollos rea­lizados.

2. Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación:

$miObj = new RedsysAPIWs;

3. 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 “createSignatureResponseHostToHost()”con la clave de comercio facilitada, la cadena que se desea firmar (concatenación de campos descrita en el punto 2 del apartado 4.1 del presente documento) y el número de pedido.

$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:

1. Importar la librería, tal y como se muestra a continuación:

<%@page import=”sis.redsys.api.ApiWsMacSha256”%>

El comercio debe incluir en la vía de cons­trucció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

2. Definir un objeto de la clase principal de la librería, tal y como se muestra a continuación:

ApiWsMacSha256 apiWsMacSha256 = new ApiWs­MacSha256();

3. 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 “cr eateSignatureResponseHostToHost()”con la clave de comercio facilitada, la cadena que se desea firmar (concatenación de campos descrita en el punto 2 del apartado 4.1 del presente documento) y el número de pedido.

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:

1. Convertir la cadena respuesta XML al atributo diccionario m_keyvalues de la clave RedsysAPIWs:

r.XMLToDiccionary(result);

2. Calcular el parámetro <Ds_Signature>. Para llevar a cabo el cálculo de este pa­rámetro, se debe llamar a la función de la librería “createSignatureResponseHostToH ost()”con la clave obtenida del módulo de administración, la cadena que se desea firmar(concatenación de campos indicada en el apartado anterior) y el número de pedido.

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.