Plataforma de Pago Seguro: Guía de integración La información contenida en este documento es propiedad de ECOTEL PLUS y no puede ser copiado, utilizado o divulgado en su totalidad o en parte, salvo consentimiento previo y por escrito de ECOTEL PLUS.
Historial de versiones Versión Fecha Autor Descripción del cambio 1.05 09/04/2013 PMV - Cambio en la URL de pruebas 1.06 11/04/2013 PMV - Nuevo parámetro de retorno en operación aceptada 1.07 22/05/2013 PMV - Corrección en el ejemplo del parámetro idioma - Cambio en código de ejemplo para evitar confusiones - Recomendación en generación/verificación de firma 1.08 05/06/2013 PMV - Mejoras en las expresiones regulares ECOTEL PLUS. Todos los derechos reservados. Página 2 de 12
1. Índice 1. Índice... 3 2. Introducción... 4 3. Flujo del proceso... 4 4. Forma de uso... 6 4.1. Parámetros de llamada... 7 4.2. Parámetros de retorno... 8 4.2.1 Operación aceptada... 8 4.2.2 Operación denegada... 9 4.2.3 Operación cancelada... 9 5. Firma de las peticiones... 10 5.1. Generación de la firma... 10 5.1.1 Generación de la firma Tienda Virtual -> PPS... 10 5.1.2 Generación de la firma PPS -> Tienda Virtual... 10 5.2. Ejemplos de generación de firma... 11 5.2.1.NET C#... 11 5.2.2 PHP... 11 6. Configuración visual... 12 ECOTEL PLUS. Todos los derechos reservados. Página 3 de 12
2. Introducción La Plataforma de Pago Seguro (en adelante PPS) permite a cualquier comercio vender por Internet con la máxima seguridad. Gracias al certificado de seguridad expedido por Thawte en SSL de 128 bits y el cumplimiento de la normativa en cuanto a seguridad y privacidad de datos para los entornos de medios de pago establecidos por PCI DSS, Ecotelplus garantiza la máxima seguridad en todas sus operaciones realizadas por la PPS. Cuando el cliente de su tienda virtual llegue al final del proceso de compra y quiera realizar el pago por medio de tarjeta electrónica, Ecotelplus mediante la PPS se encargará de pedir los datos de pago a su cliente y de realizar el cobro, todo en un entorno seguro. Su tienda virtual solo tendrá que esperar una respuesta al resultado del pago. Tan simple como eso. 3. Flujo del proceso El proceso que seguiría un cliente de la tienda virtual usando el medio de pago por PPS sería el siguiente: 1. El cliente selecciona los productos necesarios en la tienda virtual. Realiza todo el proceso necesario de registro, identificación y completado de los datos que la tienda virtual necesite. 2. Si la tienda ofrece más de un medio de pago, el cliente elige el medio de pago con tarjeta electrónica y le da al botón de realizar compra. Si la tienda solo tiene el medio de pago mediante la PPS, directamente le da a realizar compra. ECOTEL PLUS. Todos los derechos reservados. Página 4 de 12
3. La tienda virtual genera todos los datos necesarios a pasar a la PPS y le muestra una pantalla intermedia al cliente en la que se informa de que se le está redirigiendo a la PPS. Esa pantalla debería de durar unos 3 segundos para que el cliente sepa que es una redirección autorizada desde la tienda virtual. 4. Una vez está en la PPS, el cliente rellena los datos del pago y le da al botón Realizar Pago ECOTEL PLUS. Todos los derechos reservados. Página 5 de 12
5. La PPS realiza la operación. 6. Cuando la operación se ha realizado, la PPS le traspasa la información del resultado a la tienda virtual. 7. Si el resultado ha sido aceptado, la tienda le informa al cliente de que el pago ha sido correcto y que tendrá su producto sin problemas. O si el pago ha sido denegado, se le informará de que puede volver a realizar el pago de ese mismo pedido volviendo al paso 3 de este mismo flujo. 4. Forma de uso Para poder trabajar con la PPS, Ecotelplus le dará de alta en el sistema y le generará un código de usuario específico para este sistema, junto con una clave que le servirá para generar una firma de seguridad en el envío y recepción de datos. Para llamar a la PPS se establecen dos URL s, una para realizar pruebas y otra para usarla en entorno de producción: Pruebas: https://cert.ecotelplus.com/pps/payment.aspx Producción: https://pps.ecotelplus.com/payment.aspx A estas URL s se les debe pasar por POST una serie de parámetros que se especifican a continuación. Una vez terminado el proceso, estas URL s devuelven otra serie de parámetros hacia las URL s predefinidas en la llamada inicial, en base al resultado de la operación. Si las URL s de vuelta están en entorno no seguro (http) los parámetros se devolverán por GET;; sin embargo, si están en entorno seguro (https) los parámetros se devolverán por POST. ECOTEL PLUS. Todos los derechos reservados. Página 6 de 12
4.1. Parámetros de llamada A continuación se describen los parámetros que se han de enviar en la llamada a la URL de la PPS. Si alguno de los parámetros fuera incorrecto, la PPS informará del error por pantalla. Los campos están escritos según el formato: Nombre_Del_Campo Expresión_Regular_Que_Lo_Valida Descripción_Del_Campo PPS_UserId - ^PPS[0-9]{9}$ Identificador de usuario de la PPS suministrado por Ecotelplus. PPS_Reference - ^[a-za-z0-9_-]{1,128}$ Número de referencia del pedido por parte de la tienda virtual. PPS_Amount - ^[0-9]{1,12}$ Importe en céntimos a cobrar. PPS_Currency - ^[0-9]{3}$ Código numérico de la divisa (ISO 4217) de 3 dígitos. Para Euros es 978. PPS_Beneficiary - ^[\w\w]{1,128}$ Nombre del beneficiario del pago a mostrar en el formulario de pago. PPS_OrderType - ^[V]$ Tipo de Operación. V = Venta. PPS_Language - ^[a-z]{2}-[a-z]{2}$ Idioma en el que se mostrará la página. Español = es-es, Inglés en-us PPS_URLaccept - ^(((http https):\/\/) www\.)[\w\-_]+(\.[\w\-_]+)+([\w\- \.,@?^=%&:/~\+#!]*[\w\-\@?^=%&/~\+#])?$ URL a la que se devolverá el resultado de la operación en el caso de que la operación sea aceptada. PPS_URLdecline - ^(((http https):\/\/) www\.)[\w\-_]+(\.[\w\-_]+)+([\w\- \.,@?^=%&:/~\+#!]*[\w\-\@?^=%&/~\+#])?$ URL a la que se devolverá el resultado de la operación en el caso de que la operación sea denegada. PPS_URLcancel - ^(((http https):\/\/) www\.)[\w\-_]+(\.[\w\-_]+)+([\w\- \.,@?^=%&:/~\+#!]*[\w\-\@?^=%&/~\+#])?$ URL a la que se devolverá el resultado de la operación en el caso de que el cliente cancele el pago. PPS_Timeout - ^[1-9][0-9]*$ Tiempo de espera máximo en segundos para la introducción de los datos de pago en el formulario. PPS_ClientEmail - ^[a-za-z0-9!#$%&'*+/=?^_`{ }~-]+(?:\.[a-za-z0-9!#$%&'*+/=?^_`{ }~-]+)*@(?:[a-za-z0-9](?:[a-za-z0-9-]*[a-za-z0-9])?\.)+[aza-z0-9](?:[a-za-z0-9-]*[a-za-z0-9])?$ Correo electrónico del cliente. ECOTEL PLUS. Todos los derechos reservados. Página 7 de 12
PPS_ClientName - ^[\w\w]{1,128}$ Nombre y apellidos del cliente. PPS_ClientPhone - ^[0-9\+-. ()]{9,32}$ Teléfono del cliente PPS_SHASign Firma que valida la integridad de todos los datos recibidos. Descrita en 5.1.1. 4.2. Parámetros de retorno En base al tipo de resultado que se haya generado, la PPS redirigirá al cliente a tres tipos de URL s especificadas por la tienda virtual en la llamada a la PPS. Dependiendo de a que URL redirija el resultado, se enviarán una serie de parámetros u otros. 4.2.1 Operación aceptada Cuando la operación ha sido aceptada, se redirigirá a la URL que se especificó en los parámetros de entrada como PPS_URLaccept y se devolverán los siguientes parámetros. PPS_UserId Identificador del usuario de la PPS. PPS_Reference Referéncia pasada por la tienda virtual para identificar el pago. PPS_OrderType Tipo de operación PPS_DateTime Fecha y hora de la operación en formato AAAAMMDDHHMMSS PPS_Bank Entidad que ha procesado la operación PPS_FUC Código FUC usado en la operación PPS_Card Tarjeta del cliente truncada por seguridad PPS_CardHash Hash único que identifica a la tarjeta usada PPS_Operation Número de operación bancario PPS_Authorization Número de autorización bancario PPS_SHASign Firma que valida la integridad de todos los datos recibidos. Descrita en 5.1.2 ECOTEL PLUS. Todos los derechos reservados. Página 8 de 12
4.2.2 Operación denegada Plataforma de Pago Seguro Guía de implementación Cuando la operación ha sido denegada por el host bancario, se redirigirá a la URL que se especificó en los parámetros de entrada como PPS_URLdecline y se devolverán los siguientes parámetros. PPS_UserId Identificador del usuario de la PPS. PPS_Reference Referéncia pasada por la tienda virtual para identificar el pago. PPS_OrderType Tipo de operación PPS_ErrorCode Código de error por el que se denegó la operación PPS_ErrorDescription Descripción del error por el que se denegó la operación PPS_SHASign Firma que valida la integridad de todos los datos recibidos. Descrita en 5.1.2 4.2.3 Operación cancelada Cuando la operación ha sido cancelada se redirigirá a la URL que se especificó en los parámetros de entrada como PPS_URLcancel y se devolverán los siguientes parámetros. PPS_UserId Identificador del usuario de la PPS. PPS_Reference Referéncia pasada por la tienda virtual para identificar el pago. PPS_OrderType Tipo de operación PPS_ErrorCode Código del error por el que se canceló la operación PPS_ErrorDescription Descripción del error por el que se canceló la operación PPS_SHASign Firma que valida la integridad de todos los datos recibidos. Descrita en 5.1.2 ECOTEL PLUS. Todos los derechos reservados. Página 9 de 12
5. Firma de las peticiones Mediante este parámetro usado en todas las llamadas y retornos de la PPS, se asegura la integridad de los datos recibidos. Si en algún momento se ha manipulado cualquiera de los datos recibidos por parte de la PPS o la tienda virtual, la firma no sería acorde con los datos recibidos, por lo que estos datos no serían fiables. Esta firma se genera a partir de una composición de la clave que suministra Ecotelplus al darse de alta en el sistema de PPS, junto con los datos enviados, para luego aplicarle el algoritmo de cifrado SHA1. El resultado obtenido se pasa a hexadecimal y se obtiene la firma única para esa petición. Se recomienda generar esta firma de forma dinámica a partir de los parámetros que se envían o reciben. Para hacer esto, obtener el array de parámetros, elegir solo los que empiezan por PPS_ y omitir el parámetro de firma. De esta manera si en un futuro se añaden más parámetros de llamada o retorno, no se verá afectada la comprobación de la firma. 5.1. Generación de la firma La generación de la firma varía dependiendo del sentido de la petición, ya sea desde la tienda virtual a la PPS o al contrario. 5.1.1 Generación de la firma Tienda Virtual -> PPS Para generar la firma de los parámetros de llamada descritos en la sección 4.1 de este documento, se generará una cadena compuesta por la concatenación de la clave de uso seguido de todos y cada uno de los valores enviados a la PPS, excepto el parámetro PPS_SHASign. El orden de concatenación de los datos, debe ser el mismo del que se usa para enviar los datos Clave_De_Uso + PPS_UserId + PPS_Reference + PPS_Amount + A esta cadena de caracteres se le aplica el algoritmo SHA1 y el resultado se pasa a hexadecimal. 5.1.2 Generación de la firma PPS -> Tienda Virtual La firma que se recibe en los parámetros de retorno descritos en la sección 4.2 de este documento, se generan concatenando todos los parámetros devueltos, excepto el PPS_SHASign, seguido de la clave de uso. El orden de concatenación de los datos es el mismo en el que se envían los datos. PPS_UserId + PPS_Reference + PPS_Amount + + Clave_De_Uso A esta cadena de caracteres se le aplica el algoritmo SHA1 y el resultado se pasa a hexadecimal. ECOTEL PLUS. Todos los derechos reservados. Página 10 de 12
5.2. Ejemplos de generación de firma Ejemplos de código para generar la firma. 5.2.1.NET C# using System.Security.Cryptography; string Cadena = Clave_De_Uso + PPS_ UserId + + PPS_ClientPhone; SHA1CryptoServiceProvider sha1 = new SHA1CryptoServiceProvider(); byte[] CadenaBytes = Encoding.GetEncoding("ISO-8859-1").GetBytes(Cadena); byte[] FirmaBytes = sha1.computehash(cadenabytes); string FirmaSHA1 = Encoding.GetEncoding("ISO-8859-1").GetString(FirmaBytes); string FirmaSHA1Hexa = ""; for (int i = 0; i < FirmaSHA1.Length; i++) FirmaSHA1Hexa += ((int)firmasha1[i]).tostring("x").padleft(2, '0'); PPS_SHASign = FirmaSHA1Hexa; 5.2.2 PHP $FirmaSHA1Hexa = sha1($clave_de_uso.$pps_userid.[ ].$PPS_ClientPhone); $PPS_SHASing = $FirmaSHA1Hexa; ECOTEL PLUS. Todos los derechos reservados. Página 11 de 12
6. Configuración visual La PPS le permite configurar algunos aspectos de la interfaz visual para que esté más integrada con su tienda virtual. Estos parámetros son de configuración interna y para cambiarlos se deberá poner en contacto con Ecotelplus, quién validará que la configuración sea correcta y no perjudique al funcionamiento de la PPS. Estos son los elementos que tiene disponibles para cambiar de aspecto: A Color de fondo de la barra de cabecera. B Color de la fuente en el título de la página. C Logotipo de su tienda virtual. D Color de fondo de la página. E Color de la fuente en el texto legal. El formato del parámetro color se dará en RGB hexadecimal. Ejemplo: el rojo sería #FF0000 y un gris #CFCFCF. El logotipo se suministrará a Ecotelplus en formato PNG. El tamaño deberá de ser de 200px de ancho por 65px de alto. La imagen puede tener transparencias. Se recomienda que el conjunto de parámetros visuales a configurar guarden la mejor consonancia posible para no penalizar la usabilidad y por tanto repercutir al usuario final. ECOTEL PLUS. Todos los derechos reservados. Página 12 de 12