documento de integración especificaciones … banco.pdfintegración tpv virtual bancomer v1.2...

Integración TPV Virtual Bancomer V 1.2

Documento de IntegraciónEspecificaciones Técnicas

Introducción

Este documento ofrece los aspectos a tener en cuenta por los comercios que deseenutilizar la plataforma de Comercio Electrónico en Bancomer. Así mismo, expone lasindicaciones técnicas necesarias para realizar la. conexión del servidor del comerciocon la plataforma E-Commerce de Bancomer.

Para poder ofrecer el pago con tarjeta a través del TPV virtual se deberán realizarmodificaciones sencillas en el servidor de su comercio en Internet.

Servidos Electrónicos Globales S.A. de C.V. Octubre 2007 I[

\


Envío de datos a la plataforma de Comercio ElectrónicoBancomer

Una vez que el cliente ha escogido los productos o servicros que adquirirá en lapágina del comercio, está listo para realizar el pago con tarjeta bancaria. En estepunto, el comercio deberá enviar los datos básicos de la transacción (monto, númerode afiliación, descripción, etc.) a la plataforma de comercio electrónico Bancomer.Estos datos serán enviados mediante un formulario de pago que será recibido porBancomer. Cabe señalar que los datos bancarios (número de tarjeta, fechas deexpiración, etc.) no son solicitados por el comercio, son capturados en pantallas queresiden en la plataforma de Bancomer.

El formulario de pago deberá contener los datos' que se muestran en la tabla, dichoformulario se enviará mediante un mensaje POSTa la siguiente dirección (URL).

https://www.bancomer.eglobal.com.mx/sis/entradaPagos

(En el formulario de pago, los datos de la tarjeta de crédito no se envían,estos son requeridos en una segunda pantalla).

El mensaje gestionará la autorización de las operaciones. Los datos imprescindiblespara la gestión de la autorización están marcados como campos obligatorios en latabla siguiente.

DATO NOMBRE DEL DATO tono. / Tipo COMENTARIOSImporte Ds_Merchant_Amount 12/ Núm. Obligatorio. En caso de no llevar punto

decimal las últimas dos posiciones de lacifra se consideran centavos. Ej: 110correspondería a un importe de 1.10

Moneda Ds_Mercha nt_ Currency 4/ Núm. Obligatorio. En el caso de que el comerciosea mexicano el valor por omisión será 484Que son pesos mexicanos.

Número de Pedido DS_MerchanCOrder 12/ A-N. Obligatorio. Los 4 primeros dígitos debenser numéricos, para los dígitos restantessolo utilizar los siguientes caracteres ASCII

Del 30 = O al 39 = 9Del 65 = A al 90 = ZDel 97 = a al 122 = z

Cada transacción deberá tener un númerode pedido diferente, de lo contrario laplataforma la rechazará por duplicidad

Descripción del Ds_MerchanCProductDescription 125/ A-N Obligatorio. 125 caracteres como longitudproducto máxima. Este campo se mostrará al titular

en la pantalla de confirmación de lacompra.

Nombre y apellidos Ds_MerchanCntular 60/ A-N Opcional. Su longitud máxima es de 60del titular caracteres. Este campo se mostrará al

titular en la pantalla de confirmación de lacompra.

Número de afiliación Ds_Merchant_MerchantCode 7/ N. Obligatorio. Código asignado al comerciopor parte de Banco (número de afiliación).

URL del comercio Ds_MerchanCMerchantuRL 250/ A-N. . Obligatorio. URL del comercio donde separa la notificación notificara en tiempo real a través de un"on-line" mensaje post la información de la

transacción.

Servidos Electrónicos Globales S.A. de C.V. Octubre 2007


URLOK Ds_MerchanCUrlOK 250/ A-N. Opcional. Durante el proceso de pago yuna vez que se muestra al cliente lapantalla de la transacción aceptada, esposible direccionar el navegador a lapagina del comercio especificada en estaURL.

URL Cancel Ds_MerchanCUrlKO 250/ A-N. Opcional. Durante el proceso de pago yuna vez que se muestra al cliente lapantalla de la transacción denegada, esposible direccionar el navegador a lapagina del comercio especificada en estaURL.

Identificación de Ds_MerchanCMerchantName 25/ A-N. Opcional. Es el nombre del comerciocomercio (Denominación Social) aparecerá en la

impresión del ticket del cliente.Idioma del titular Ds_Merchant_ConsumerLanguage 3/ Núm. Opcional. Idioma del cliente. Por omisión. es castellano .Firma del comercio Ds Merchant MerchantSianature 40/ A-N ObliGatorio. Ver ANEXO 11.Número de terminal Ds_Merchant_ Terminal 3/ Núm. Obligatorio. Número de terminal que le

asianará su banco. Por omisión será "1".Tipo de transacción Ds_Merchant_ Tra nsactionType 1/ Num Obligatorio. El comercio indicara qué tipo

de transacción es. Los posibles valoresson:

O - Autorización (venta)3 - Devolución Automática4 - Cancelación

Datos del comercio Ds_MerchanCMerchantData 1024/A-N Opcional. Campo libre que el comerciopuede utilizar para recibir informaciónorooia en la notificación on-líne.

Una vez que el comercio envía este formulario con los datos respectivos, el browserdel cliente es redireccionado a pantallas de Bancomer en las que captura sus datosbancarios y se lleva a cabo la autorización con el emisor correspondiente.

Al finalizar la autorización se presenta una pantalla de confirmación con lossiguientes datos:

Resultado de la Comp a

Importe6,789.23

ComercioRegalos.com

Código comercio6905102

Terminal 1

I Imprimir I Cerrar



Se podrá solicitar que en la pantalla de conformación al cliente, al pulsarel botón cerrar el browser sea redireccionado a una ruta especificada porel comercio. Ofrecemos la posibilidad de ir a 2 rutas distintas en funcióndel resultado de la transacción. Estas son las rutas UrlOK y UrlCancel paratransacciones aprobadas y rechazadas, respectivamente.

Las rutas UrlOK y UrlCancel pueden recibir los mismos datos que seenvían mediante la respuesta http on-llne.

Estas rutas pueden ser especificadas de dos maneras:

1. URL's por default: Se dan de alta en las propiedades generales delcomercio, deben ser notificadas a Bancomer para que formen parte delproceso de inscripción a la plataforma.

2. URL's explícitas: Si las rutas son incluidas en el formulario de pago en loscampos Ds_Merchant_UrlOK y Ds_Merchant_UrIKO, éstas son utilizadas enlugar de los URL's por default de la opción 1.

Servidos Electrónicos Globales S.A. de c.v. Octubre 2007


Anexo IFirma del comercio

Se asignará al comercio una clave que se utilizará para firmar los datos enviados porel mismo, pudiendo verificarse no sólo la identidad del comercio, sino también quelos datos no han sido alterados en ningún momento. Se utilizará como algoritmo deseguridad un código Hash SHA-1, que garantiza los requisitos de seguridad encuanto a la autenticación del origen. La clave secreta se proporcionará como partedel trámite de inscripción a la plataforma.

Este mismo algoritmo se utilizará para asegurar al comercio la autenticidad de losdatos de la respuesta, en caso de que se proporcione una URL de notificación on-linepor parte del comercio. •

La firma electrónica del comercio se deberá calcular de la forma siguiente:

Digest = SHA-1(Ds_Merchant_Amount + Ds_Merchant_Order+ Ds_Merchant_MerchantCode + Ds_Merchant_Currency+ Ds_Merchant_ TransactionType + CLAVESECRETA)

Ejemplo:

IMPORTE=1235NÚMERODE PEDIDO=29292929CODIGO COMERCIO=1920191MONEDA=484TIPO DE OPERACIÓN = OCLAVE SECRETA=h2u282kMks01923kmqpo

Cadena datos: 12352929292919201914840h2u282kMks01923kmqpo

Resultado SHA-1: 332de724ddeOedge71d2d07cc5aaf3c49a526b58

Notar que el algoritmo SHA-1 genera un valor binario de 160 bits (20 bytes), la cualse debe convertir a su representación hexadecimal con 40 caracteres ASCII (2 porcada byte, del 00 al FF).

El cálculo de la firma del comercio no debe hacerse en el browser deltarjetahabiente, de lo contrario, la clave secreta estaría comprometida.

Dependiendo del software utilizado en el servidor del comercio, deberán usarse laslibrerías criptográficas que correspondan. Por ejemplo:

Java, JSP:ASP.NET:

java.security.MessageDigestSystem .Security .Cryptography .SHA1

Una vez que se ha generado la firma no se deben modificar los datos de ningúnmodo ya que el sistema los utiliza para validar la ñrma y si lo que se recibe no esexactamente lo que se utilizó para generar la firma, la transacción será invalidada.



1.ldentificación de anomalías durante el proceso de compra

La TPV Virtual de Bancomer incluye fuertes validaciones y controles para detectarposibles errores en la entrada de datos o situaciones anómalas del sistema.

Ante cualquier entrada a la TPV Virtual Bancomer, se realizan las validacionespertinentes de los datos de entrada. Si los datos de entrada no son correctos, segenera un código de error y no se permite continuar con la operación. Normalmenteestas situaciones se producen durante el tiempo que duran las pruebas deintegración de un nuevo comercio.

Dependiendo del error producido, el mensaje mostrado al titular será diferente. Losposibles códigos de error que pueden darse se muestran en este documento.

La inclusión del código de error en la página mostrada al cliente esta oculto a lavista. La situación puede ser diferente dependiendo de la personalización utilizada.Lo normal es que se encuentre en forma de comentario junto al mensaje mostrado altitular. Para localizar el valor se deben seguir los siguientes pasos:

1. Abrir con el bloc de notas (por ejemplo) el código fuente de la paginadonde se ha producido el error. En la barra de tareas de la pagina delnavegador: VeÑ Código fuente.

2. Una vez que tenemos el código fuente abierto buscar el error que seha producido. En la barra de tareas del bloc de notas: Edición ~Buscar.

3. Introducir en la caja de texto 'buscar' el siguiente literal: SISO.

4. Aparecerá un literal del tipo: <1--SIS0051:-->.De este modo tendremos identificado el error que se ha producido.



Anexo 11

TABLA DE CODIGOS DE ERROR DEL TPV VIRTUAL

ERROR DESCRIPCION MENSAJE(ANEXO VII)

5150008 Error falta Ds Merchant MerchantCode M5GOO085150009 Error de formato en Ds Merchant MerchantCode M5GOO085150010 Error falta Ds Merchant Terminal M5GOO085150011 Error de formato en Ds Merchant Terminal M5GOO085150014 Error de formato en Ds Merchant Order M5GOO085150015 Error falta Ds Merchant Currency M5GOO085150016 Error de formato en Ds Merchant Currencv. M5GOO085150017 Error falta Ds Merchant ProductDescription M5GOO085150018 Error falta Ds Merchant Amount M5GOO085150019 Error de formato en Ds Merchant Amount M5GOO085150020 Error falta Ds Merchant Merchant5iQnature M5GOO085150021 Error la Ds Merchant Merchant5ignature viene vacía M5GOO085150022 Error de formato en Ds Merchant 'rransactlonrvoe M5GOO085150023 Error Ds Merchant Transactlon'Tvpe desconocido M5GOO085150024 Error Ds_MerchanCConsumerLanguage tiene mas de M5GOO08

3 posiciones5150025 Error de formato en M5GOO08

Ds Merchant ConsumerLanauaae5150026 Error No existe el comercio / terminal enviado M5GOO085150027 Error Moneda enviada por el comercio es diferente a M5GOO08

la Que tiene asiqnada para ese terminal5150028 Error Comercio / terminal está dado de baia M5GOO085150030 Error en un pago con tarjeta ha llegado un tipo de M5GOOOO

operación no válido5150040 Error el comercio / terminal no tiene ningún método M5GOO08

de oaco asia nado5150042 La firma enviada no es correcta M5GOO085150051 Error número de pedido repetido M5GOO015150054 Error no existe operación sobre la que realizar la M5GOO08

devolución5150055 Error existe más de un pago con el mismo número de M5GOO08

pedido5150056 La operación sobre la que se desea devolver no está M5GOO08

autorizada5150057 El importe a devolver supera el permitido M5GOO085150058 Inconsistencia de datos, en la validación de una M5GOO08

confirmación5150059 Error no existe operación sobre la que realizar la M5GOO08

confirmación5150060 Ya existe una confirmación asociada a la M5GOO08

preautenticación5150061 La operación sobre la que se desea confirmar no está M5GOO08

autorizada5150063 Error. Número de tarieta no disponible M5GOO085150064 Error. El número de tarjeta no puede tener más de 19 M5GOO08

posiciones5150065 Error. El número de tarjeta no es numérico M5GOO085150066 Error. Mes de caducidad no disponible M5GOO085150067 Error. El mes de la caducidad no es numérico M5GOO085150068 Error. El mes de la caducidad no es válido M5GOO085150069 Error. Año de caducidad no disponible , M5GOO085150070 Error. El Año de la caducidad no es numérico M5GOO085150071 Tarjeta caducada M5GOOOO5150074 Error falta Ds Merchant Order M5GOO08

Servidos Electrónicos Globales S.A. de C.V. Octubre 2007 (


5150075 Error el Ds_MerchanCOrder tiene menos de 4 M5GOO08•posiciones o más de 12

5150076 Error el Ds_Merchant_Order no tiene las cuatro M5GOO08primeras posiciones numéricas

5150077 Error el Ds_Merchant_Order no tiene las cuatro M5GOOOOprimeras posiciones numéricas. No se utiliza

5150078 Método de caco no disoonible M5GOO055150089 El valor de Ds_Merchant_ExpiryDate no ocupa 4 M5GOO08

posiciones5150092 El valor de Ds Merchant ExpirvDate es nulo M5GOO085150093 Tarieta no encontrada en la tabla de ranaos M5GOO065150094 La tarieta no fue autenticada como 3D 5ecure M5GOO045150112 Error El tipo de transacción especificado en M5GOO08

Ds Merchant TransectlonIvne no esta permitido5150114 Error, se ha llamado con un GET en IUQar de un P05T M5GOOOO5150115 Error no existe operación sobre la que realizar el pago M5GOO08

de la cuota .5150116 La operación sobre la que se desea pagar una cuota M5GOO08

no es una ooeración válida5150117 La operación sobre la que se desea pagar una cuota M5GOO08

no está autorizada5150118 5e ha excedido el importe total de las cuotas M5GOO085150119 Valor del campo Ds_Merchant_DateFrecuency no M5GOO08

válido5150120 Valor del campo Ds_MerchanCChargeExpiryDate no M5GOO08

válido5150121 Valor del campo Ds Merchant 5umTotaI no válido M5GOO085150122 Valor del campo Ds_Merchant_DateFrecuency o no M5GOO08

Ds Merchant 5umTotal tiene formato incorrecto5150123 5e ha excedido la fecha tope para realizar M5GOO08

tra nsacciones5150124 No ha transcurrido la frecuencia mínima en un pago M5GOO08

recurrente sucesivo5150133 La fecha de Confirmación de Autenticación no puede M5GOO08

superar en mas de 45 días a la de AutenticaciónPrevia. .

5150139 Error el caco recurrente inicial está duplicado M5GOO085150152 Error no existe operación sobre la que realizar la M5GOO08

cancelación5150153 El importe a cancelar debe ser el mismo de la M5GOO08

operación oriqinal5150154 Sólo se oueden cancelar ooeraciones no caoturadas M5GOO085150155 La operación va está cancelada M5GOO085150156 No se puede cancelar una operación con devoluciones M5GOO08

asociadas5150157 Es código CVV2 o CVC2 no puede tener más de 4 M5GOO08

posiciones



Anexo 111Respuesta "on-Ilne" de la TPV Virtual Bancomer al comercio

Esta opción esta disponible para aquellos comercios que necesitan una verificacióninmediata de la transacción para su gestión. En la cual contamos con 2 tipos deNotificaciones:

1.- Respuesta http:

La respuesta http es un proceso independiente de la conexión con el navegador delcliente y no tiene ningún reflejo en la pantalla del mismo. Evidentemente, en ellado del comercio, deberá existir un proceso que acepte y procese esta respuestahttp. •

El protocolo utilizado en las respuestas puede ser http o https, el formato de estemensaje es un formulario HTML, enviado con el método POST, y cuyos campos sonlos siguientes (en los campos la longitud se considera máxima por lo que no esimprescindible el relleno de los mismos; la firma será generada con los camposexactamente como se envíen):

DATO NOMBRE DEL DATO .LONG/ COMENTARIOSTIPO

Fecha Ds_Date dd/mm/yyyy Fecha de la transacción

Hora Ds_Hour HH:mm Hora de la transacción

Importe Ds_Amount 12/ Núm. Mismo valor que en la petición.

Moneda Ds_Currency 4/ Núm. Mismo valor que en la petición. 4 seconsidera su lonoitud máxima.

Número de pedido Ds_Order 12/ A-N. Mismo valor que en la petición.

Identificación de comercio Ds_MerchantCode 9/ N. Mismo valor que en la petición.

Terminal Ds_Terminal 3/ Núm. Número de terminal que le asignará subanco. 3 se considera su longitudmáxima.

Firma para el comercio Ds_Signature 40/ A-N Ver a pie de página las instruccionespara su cálculo.

Código de respuesta Ds_Response 4/ Núm. Ver tabla siguiente

Datos del comercio Ds_MerchantData 1024/ A-N Información opcional enviada por elcomercio en el formulario de naco.

Pago Seguro Ds_SecurePayment l/Núm. O - Si el pago se realizó en formatradicional

1 - Si el pago se realizó en modalidad3D Secure

Tipo de operación Ds_TransactionType 1/ A-N TIpo de operación que se envió en elformulario de oaoo

Idioma del titular Ds_ConsumerLanguage 3/ Núm El valor O, indicará que no se hadeterminado el idioma del cliente.(opcional). 3 se considera su longitudmáxima.

Código de error Ds_ErrorCode 7/ A-N·, Código de error. Sólo se enviará encaso de detectarse alouna anornálía



La finna para el comercio es calculada de acuerdo al algoritmo y operativa descritaen el anexo I, pero utilizando la siguiente fórmula

Digest = SHA-l(Ds_Amount + Ds_Order+ Ds_MerchantCode + Ds_Currency+ Ds_Response + CLAVE SECRETA)

La conexión utilizada para comunicar la confinnación "on-line" entre el TPV Virtual deBancomer y el comercio puede ser SSL. Opcional mente el comercio puede activar unfiltro para limitar la recepción de la confirmación "on-line" sólo desde el TPV Virtualde Bancomer para evitar comunicaciones fraudulentas.

El TPV Virtual de Bancomer por defecto puede comunicar a los puertos 80 y 443 delcomercio. Otros puertos deberán ser consultados.

Una vez que el comercio recibe el formulario, el código de respuesta (Ds_Response)tendrá los siguientes valores posibles:

CODIGO SIGNIFICADO

000 Transacción autorizada

001 Transacción denegada por el emisor

003 Merchant inválido

004 Tarieta robada

005 Tarieta sin fondos

013 Importe no válido

014 Número de tarieta no válido

040 Ooeración no sooortada

054 Tarieta caducada

081 Operación no soportada

Cualauier otro valor Transacción deneoada



2.- Método e-mail:

El formato de contestación es exactamente igual que en el métodoanterior. Sin embargo, en vez de enviarse un formulario http a la URLespecificada por el comercio, se envía un e-mail a una direcciónpreviamente acordada en el trámite de inscripción

Fecha: 16/07/2003 Hora: 12:16;Ds_SecurePayrnent: 1;Ds_Amount: 1;Ds_Currency: 484;Ds_Order: 315412155101;Ds_MerchantCode: 0010934;

Ds_Terminal: 001;Ds_Signature: B27BC8D862096B60E4D9379A8699B4~B3BE980A7;

Ds_Response: 000;Ds_MerchantData: Alfombrilla para raton;Server URL: XXXXXXXXXXXXXXXXX;Ds_TransactionType: O;Ds_ConsumerLanguage=l


documento de integración especificaciones … banco.pdfintegración tpv virtual bancomer v1.2...

Documents