moto pos pc - visanet.com.pe · se le hace entrega al comercio del cuestionario técnico con el fin...

MOTO POS PC

Guía de Integración de Comercios

Versión Nº: 2

SGC_GUI35

Propiedad de Compañía Peruana de Medios de Pago S.A.C. - Prohibida cualquier reproducción, distribución o comunicación, salvo autorización expresa de VisaNet Perú.

Página 1 de 25

MOTO – POS PC

GUÍA DE INTEGRACIÓN DE

COMERCIOS

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 2 de 25

1. Introducción ............................................................................................. 3

1.1. Objetivos ..................................................................................................... 3

1.2. Glosario ....................................................................................................... 3

1.3. Flujo de Compra ......................................................................................... 3

1.4. Pantalla de solicitud de datos del tarjetahabiente ................................... 4

2. Integración al V-POS ............................................................................... 5

2.1. Procedimiento de Integración al V-POS .................................................... 5

2.2. Administración de los certificados digitales ............................................ 6

2.3. Autorización – Inicio de transacción ......................................................... 8

2.4. Autorización – Fin de transacción ........................................................... 12

2.5. Solicitud de Reverso ................................................................................ 14

2.5.1. Respuesta de pago ................................................................................. 14

3. Integración con el Web Service ........................................................... 14

4. Preguntas y Respuestas Frecuentes ................................................... 15

5. Anexos ................................................................................................... 15

5.1. Anexo 1: Consumo del Web Service del VPOS WS en Java .................. 15

5.1.1. Requisitos necesarios.............................................................................. 15

5.1.2. Configuración de Axis para consumo de Web Service ............................. 15

5.2. Anexo 2: Listado de códigos de error ..................................................... 20

5.3. Anexo 3: Archivo de políticas a usar en el VPOSWSS11 ....................... 23

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 3 de 25

1. Introducción Actualmente, los comercios afiliados a Visanet del Perú que realizan ventas en entornos no presenciales de tarjetahabiente (excluyendo el canal de comercio electrónico), llevan a cabo el procesamiento de autorizaciones a través del canal MOTO, no efectuando la lectura electrónica de la tarjeta en un POS físico. En este escenario podemos ubicar a comercios que realizan operaciones de tipo “delivery”. Para este tipo de transacciones los comercios asumen el riesgo de la transacción ya que no se cuenta con presencia física del tarjetahabiente. Asimismo, los comercios incurren en procesos adicionales como la entrega de vouchers a los clientes en el punto de entrega, lo que ocasiona molestias, así como también se tiene un mayor costo operativo de la transacción que es asumido por el comercio. Para ello Visanet del Perú provee la solución POS PC para los comercios que actualmente trabajan bajo el esquema anteriormente expuesto. 1.1. Objetivos

Este documento tiene como objetivos lo siguiente: Describir las funcionalidades que brinda la solución POS PC. Describir los pasos necesarios para la integración con el VPOS, módulo denominado

“Plug In” en la solución POS PC. 1.2. Glosario

A lo largo del presente documento se utilizan los siguientes términos bajo la conceptualización que se señala a continuación: Proceso de Autorización: Servicio de autorización del pago V-POS: Virtual Point Of Sale. Interfaz del mundo transaccional de pagos virtuales Tarjetahabiente: Titular de la tarjeta Emisor: Banco emisor de una tarjeta de crédito o débito 1.3. Flujo de Compra

A continuación se listan los pasos del flujo del procesamiento (Ver Figura 1. Flujo de procesamiento):

1. El flujo de compra se inicia cuando un operador de Contact Center del comercio realiza el pago de una venta

2. El sistema de Contact Center del comercio consume un Web Service Seguro con los datos de compra. El servicio a consumir devuelve una URL (dirección web) que debe ser accedidas desde el navegador de Internet del operador, para poder continuar con el procesamiento en el V-POS.

3. El V-POS muestra en el navegador del operador una página donde se ingresa el número de tarjeta y la fecha de vencimiento.

4. El operador ingresa en la pantalla anterior los valores solicitados. 5. El V-POS procede a efectuar el proceso de autorización para consultar al banco

emisor de la tarjeta la autorización de la compra.

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 4 de 25

6. El V-POS luego de realizar el proceso de autorización envía un valor TOKEN a la URL o página de respuesta del sistema de Contact Center del Comercio.

7. El comercio se encargará de enviar el valor TOKEN al Web Service de finalización de compra, el cual devuelve los datos del resultado de procesamiento de la compra. También este servicio actúa como un acuse de recibo de la transacción en el comercio.

Figura Nº 1 Flujo del Procesamiento

1.4. Pantalla de solicitud de datos del tarjetahabiente

A continuación se presentación la pantalla de solicitud de datos del tarjetahabiente

Imagen Nº 1 Pantalla Solicitud de datos

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 5 de 25

En la imagen se puede apreciar el número de orden el cual debe estar asociado a un identificador de la operación. Esta información debe ser consignada automáticamente por el sistema del comercio.

2. Integración al V-POS 2.1. Procedimiento de Integración al V-POS

La integración se hace inicialmente en un ambiente de Pruebas y luego se traslada a un ambiente de Producción. Para el Ambiente de Pruebas: Los principales pasos para la integración del comercio al V-POS en el ambiente de Pruebas son: 1. Se le hace entrega al comercio del Cuestionario técnico con el fin de listar las

características de la plataforma del sitio Web, el cual debe ser devuelto con todos los datos llenos.

2. Se aprobará el cuestionario y se entregará la presente Guía de Integración de comercios.

3. El comercio revisará y evaluará para los desarrollos necesarios la Guía de Integración de comercios, preparación para el consumo del Web Service Seguro y administración de certificados digitales.

4. El comercio confirmará la fecha de término de su desarrollo y solicitará la habilitación del ambiente de prueba.

5. El comercio deberá ser registrado en los sistemas de autorización de ambiente de pruebas antes de iniciar un proceso de compra de prueba. En esta fase de registro del comercio, se le solicitarán los datos necesarios para su integración en el sistema MOTO POS PC.

6. Se enviarán las referencias o personas de contacto del comercio, que serán responsables de las pruebas, generación e intercambio de certificados digitales entre el PROVEEDOR y el comercio. Se hará entrega al comercio de los valores de configuración (Código de Comercio) requeridos para la generación del certificado del comercio.

7. El comercio generará el certificado a utilizar por el web services a través de la herramienta MOTO POS PC, a la cual accederá con el usuario administrador de comercio que hará entrega VISANET.

8. El comercio acuerda una fecha y hora para realizar las pruebas. Se definen los responsables de las pruebas tanto por el lado del PROVEEDOR como del comercio.

9. Se realizan las pruebas en ambiente de pruebas o testing. 10. El PROVEEDOR informa a VISANET el término y el resultado de las pruebas en el

Ambiente de Pruebas. 11. Es posible que VISANET realice pruebas adicionales de validación Para el Ambiente de Producción: Los principales pasos para la integración del comercio al V-POS en el ambiente de Producción son: 1. El comercio deberá ser registrado en el sistema MOTO POS PC de ambiente de

producción antes de iniciar un proceso de compra real.

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 6 de 25

2. El comercio generará el certificado a utilizar por el web services a través de la herramienta MOTO POS PC de ambiente de producción, a la cual accederá con el usuario administrador de comercio que hará entrega VISANET.

3. El comercio acuerda una fecha y hora para realizar las pruebas. Se definen los responsables de las pruebas tanto por parte de PROVEEDOR como por el lado del comercio.

4. Se realizan las pruebas 5. El PROVEEDOR informa a VISANET el término de las pruebas en el ambiente de

producción 6. Es posible que VISANET desee realizar pruebas adicionales de validación 2.2. Administración de los certificados digitales

Con la finalidad de que la transmisión de información entre el comercio y el V-POS se realice de manera segura, guardando los tres principios de seguridad: Protección, Integridad y Autenticidad de datos, el comercio deberá emplear un llavero de tipo PKCS12 que contendrá los certificados digitales para el consumo de los web services. A continuación se detalla el proceso de generación de certificados en la herramienta MOTO POS PC: 1. Ingresar a la herramienta MOTO POS PC:

a. Testing: https://test2.alignetsac.com/vpaymentweb/ b. Producción: https://vpayment.verifika.com/vpaymentweb/

Imagen Nº 2

2. Ingresar con el usuario y contraseña proporcionados por VISANET. 3. Seleccionar la opción Certificados

https://test2.alignetsac.com/vpaymentweb/

https://vpayment.verifika.com/vpaymentweb/

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 7 de 25

Imagen Nº 3

4. Hacer clic en el botón Agregar Certificado

Imagen Nº 4

5. Ingresar los siguientes datos: Organization: Organización encargada de implementar el web services Organization Unit: Área de la organización encargada de implementar el web services Locality: Ciudad donde se ubica el comercio Country: País donde se ubica el comercio Email Address: Cuenta de correo electrónico al que se notificará el vencimiento del

certificado a generar (2 años de vigencia)

Imagen Nº 5

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 8 de 25

6. Hacer clic en el botón Agregar Certificado 7. Descargar el certificado generado en el icono de descarga

Imagen Nº 6

2.3. Autorización – Inicio de transacción

La solicitud de pago se define como el conjunto de datos que necesita el V-POS para generar la solicitud de autenticación así como la solicitud de autorización. Para iniciar la solicitud de pago, el comercio deberá consumir el web service a partir de las siguientes URLs las cuales definen el servicio: Testing: https://test2.alignetsac.com/VPOS/services/VPOSMMWSS11?wsdl Producción: https://vpayment.verifika.com/VPOS/services/VPOSMMWSS11?wsdl Método a usar: transactionStart Parámetros de Envío Los parámetros que enviará el comercio al V-POS para iniciar la solicitud de pago son los siguientes:

Campo Descripción

OperationNumber Número único de operación en el comercio (alfanumérico) – Mandatario

CurrencyCode Valor que corresponde al código de moneda usado en la transacción, este código va acorde con el estándar ISO de 3 dígitos numéricos, este campo es mandatario

PurchaseAmount Monto total de la compra en la moneda definida, el formato es de texto numérico (contando los decimales de la moneda) pero sin el separador decimal – Mandatario

TipAmount Monto de la propina en el formato de monto como en PurchaseAmount – opcional.

purchaseCommerceAmount

Monto disgreagado del comercio, usado solo en malls transaccionales - opcional

terminalCode Código de terminal donde la transacción es realizada, este valor es una cadena numérica y es opcional

Language Lenguaje de la compra, esta en modo ISO de 2 caracteres (por defecto es SP) - Mandatario

IPAddress Dirección IP del tarjetahabiente – Mandatario

billingData Estructura de datos de tipo Address (ver tablas siguientes) correspondiente a la dirección de cobranza del tarjetahabiente - opcional

shippingData Estructura de datos de tipo Address (ver tablas siguientes) correspondiente a la dirección de embarque del producto o bien – opcional

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 9 de 25

Taxes Estructura de datos tipo Tax, la cual corresponde a todos los impuestos relacionados con la compra – Es un campo opcional pero si no se envía Tax alguno debe enaviarse un arreglo de tamaño 0

products Arreglo de estructuras de datos de tipo Product (ver tablas siguientes), con los productos relacionados a la compra – opcional pero si ningún producto será enviado debe enviarse un arreglo de longitud 0

reservedData Arreglo de estructuras de datos de tipo Reserved (ver tablas siguientes) el cual debería ser usado para uso extendido – opcional pero debe enviarse un arreglo de longitud cero s no se envía nada

shipperCode Codigo del operador logístico involucrado en el envío de los bienes o productos – opcional pero si es necesario el código será enviado por el PROVEEDOR

shipperAmount Monto de embarque incluido en el monto total de compra – opcional pero es requerido si el shipperCode es especificado

HTTPSession Valor de la sesión HTTP el cual es usado normalmente para obtener la sesión una vez que haya concluido la transacción - opcional

cardType Tipo de tarjeta ingresada de acuerdo a los siguientes valores: VISA, MC, AMEX, DINERS, DISC, JCB Enviar este valor sólo si el comercio ha convenido con VISANET que capturará los datos del tarjetahabiente – opcional

cardNumber Número de tarjeta de crédito/débito, cadena numérica permite un tamaño de 13 a 19 caracteres – opcional, enviar sólo si el comercio ha convenido con VISANET en enviar este valor

cardExpirationMonth Mes de expiración de la tarjeta en forma de entero (Enero corresponde al valor 1) – opcional, enviar sólo si el comercio ha convenido con VISANET en enviar este valor

cardExpirationYear Año de expiración de la tarjeta en forma de entero correspondiente al año completo (20XX) – opcional, enviar sólo si el comercio ha convenido con VISANET en enviar este valor

cardSecurityCode Código de seguridad impreso en la tarjeta en forma de cadena numérica – opcional, enviar sólo si el comercio ha convenido con VISANET en enviar este valor

Parámetros de Respuesta Parámetros que el método devuelve en respuesta

Campo Descripción

State Valor entero correspondiente al estado de inicio de la transacción sus valores corresponden a 0: Transacción inicializada existosamente y un valor válido de URLscreen es devuelto -1: Inicio erróneo, ningún valor de URLScreen es enviado y los valores de errorCode y errorMessage corresponden a la explicación del error

URLScreen URL con la dirección de redirección del VPOS, el sitio web debe indicar al navegador del tarjetahabiente que debe redireccionar a esa dirección, solo es retornado cuando la transacción inició correctamente.

errorCode Código de error de la inicialización de la transacción, ver códigos de

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 10 de 25

Error en el Apéndice 3

errorMessage Mensaje de error de inicio de la transacción, corresponde a una explicación del errorCode

A continuación se indican las estructuras de datos correspondientes al Web Service Estructura de Datos - Tax Esta estructura contiene los datos de un impuesto que está involucrado en la compra. Al Web Service se le envía un arreglo de Tax, este arreglo debe ser por lo menos de longitud cero, lo cual indica que ningún Tax será enviado

Campo Descripción

Id Identificador del impuesto, numérico e inicia en 0, este dato es obligatorio

Name Nombre del impuesto, alfanumérico y es obligatorio

Amount Monto del impuesto, valor numérico del mismo formato del monto de compra y es obligatorio

Estructura de datos - Product Esta estructura contiene los datos de cada producto involucrado en la transacción. El Web Service solicita un arreglo de Product y debe existir por lo menos un producto, de no consignar ningún producto crear un arreglo de longitud cero.

Campo Descripción

Item Identificador de ítem, numérico e inicia en 0, este dato es obligatorio

Code Código del producto interno para el comercio, este dato es generado por el comercio, alfanumérico y obligatorio

Amount Monto cargado al producto, mandatorio

La Clase Product es la clase padre de Flight y Good. Esta clase puede ser usada para enviar, en vez de un producto, información de vuelos de líneas aéreas, si se envían información de vuelo debe usarse esta clase. Estructura de datos – Good Esta estructura contiene la data de un bien involucrado en la compra el cual puede ser tangible o intangible, todos los campos son mandatarios.

Campo Descripción

Name Nombre del producto

Description Descripción del producto

Quantity Valor flotante con la cantidad involucrada en la transacción

unitPrice Precio unitario del producto

Estructura de datos - Flight Esta estructura contiene los datos de cada vuelo involucrado en la transacción (normalmente es un vuelo por transacción) al ser una clasificación de Product puede usarse dentro del arreglo del mismo.

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 11 de 25

Campo Descripción

AirlineCode Código identificador único de la línea aérea, alfanumérico y obligatorio

DepartureAirport Estructura de datos de tipo Airport, el cual contiene los datos del Aeropuerto de partida

ArriveAirport Estructura de datos de tipo Airport, el cual contiene los datos del Aeropuerto de llegada

DepartureDate Fecha – Hora de la partida, es un dato de tipo fecha

PassengerList Arreglo de estructuras de datos de clase Passenger

Estructura de datos - Airport Esta estructura contiene los datos del aeropuerto involucrado en el vuelo.

Campo Descripción

Code Código identificador único del aeropuerto, alfanumérico y obligatorio

City Nombre de la ciudad donde está el aeropuerto, alfanumérico y obligatorio

Country País de localización del aeropuerto, en formato ISO de 2 caracteres, alfanumérico y obligatorio

Estructura de datos - Passenger Esta estructura contiene los datos de cada pasajero involucrado en el vuelo

Campo Descripción

First Name Nombre del pasajero, alfanumérico y obligatorio

Last Name Apellido del pasajero, alfanumérico y obligatorio

Birth Date Fecha de nacimiento del pasajero, de tipo date y es obligatorio

Document Type Entero que indica el tipo de documento, obligatorio, posibles valores PASSPORT, NATIONAL_DOCUMENT, SSN, GREEN_CARD, OTHER

Document Numbre Valor alfanumérico que corresponde al número de documento utilizado, obligatorio

Class Valor alfanumérico que corresponde al FARE BASIS del ticket

Estructura de datos - AddressData Agrupa los datos correspondientes a una dirección, desde el más global como el país, hasta la más granular como la calle.

Campo Descripción

First Name Primer Nombre

Middle Name Segundo Nombre

Last Name Primer Apellido

Address Dirección con calle y número, alfanumérico y obligatorio

City Nombre de la ciudad, alfanumérico y obligatorio

State Nombre del estado o división político territorial donde se encuentra la ciudad, alfanumérico y obligatorio

Country Code Código del país correspondiente al estándar ISO de 2 caracteres, alfanumérico y obligatorio

Zip Code Código postal de la dirección, alfanumérico y obligatorio

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 12 de 25

Phone Numbre Número de teléfono a la cual cual pertenece la dirección, se debe incluir el código de área, alfanumércio y es obligatorio

Email Dirección de correo electrónico, alfanumérico y obligatorio

Estructura de datos - Reserved Contiene datos a para uso futuro, viene en forma de arreglo de Reserved y debe usarse previo acuerdo entre el Comercio y VISANET, si no se enviaran datos reservados crear un arreglo de longitud cero.

Campo Descripción

Id Identificador del campo reservado, inicia en 1, valor entero y obligatorio

Value Valor del campo reservado, alfanumérico y obligatorio

2.4. Autorización – Fin de transacción

Cuando el comercio inicio el proceso transaccional usando el método anteriormente descrito, el comercio le entrega al navegador del tarjetahabiente el control del proceso para continuar con la autenticación y la autorización, cuando esta ha finalizado le responde al comercio para que el mismo solicite el fin de la transacción por medio de un Web Service Para finalizar el pago, el comercio deberá consumir el web service a partir de las siguientes URLs las cuales definen el servicio: - Testing: https://test2.alignetsac.com/VPOS/services/VPOSMMWSS11?wsdl - Producción: https://vpayment.verifika.com/VPOS/services/VPOSMMWSS11?wsdl Método a usar: transactionFinish Parámetros de Envío Los parámetros que enviará el comercio al V-POS para iniciar la solicitud de pago son los siguientes:

Campo Descripción

Token Value Valor del Parámetro TOKEN devuelto por el VPOS a la página de respuesta del comercio. Junto con el parámetro TOKEN es enviado el parámetro COMMERCE el cual es el identificador del comercio.

cancel No usado en esta versión

Parámetros devueltos por el Web Service La respuesta de pago que devolverá el V-POS al comercio estará compuesta por los siguientes campos:

Campo Descripción

Result Valor numérico que indica si la transacción fue autorizada o no 0: Autorización aprobada 1: Autorización denegada (por el banco emisor) 2: Autorización rechazada (por el sistema VPOS)

AuthorizationCode Código de autorización generado por el Banco Emisor, sólo es

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 13 de 25

devuelto en caso la transacción haya sido aprobada

errorCode Código alfanumérico que indica el motivo de denegación o rechazo

errorMessage Cadena que muestra la descripción del errorCode

Authentication ECI Valor de Electronic Commerce Indicator, este valor es usado por el proceso de autorización y es generado por el proceso de autenticación.

Authentication VCI Valor de Verifika Commerce Indicator, el cual es generado por el PROVEEDOR para explicar el estado de autenticación, este valor es usado por el proceso de autorización.

HTTPSession Valor del identificador de sesión HTTP el cual ha sido enviado en el método transactionStart

Authorized Amount Monto autorizado por el banco emisor, normalmente es el mismo de purchaseAmount, está presente sólo en transacciones autorizadas exitosamente

planCode Código de plan seleccionado por el tarjetahabiente, solo usado por comercios y VISANET con plan/cuotas habilitado

planName Nombre del plan seleccionado por el tarjetahabiente, solo usado por los comercios y VISANET con plan/cuotas seleccionado

quotaCode Código de cuota seleccionado por el tarjetahabiente, solo usado por comercios y VISANET con plan/cuotas habilitado.

QuotaName Nombre de la cuota seleccionada por el tarjetahabiente, solo usado por los comercios y VISANET con plan/cuotas seleccionado

quotaAmount Monto a ser cargado por cada cuota del tarjetahabiente, solo usado por los comercios y VISANET con plan/cuotas seleccionado y en los que el VPOS realiza el cálculo de cuota

Taxes Arreglo de objetos Tax enviados por el comercio y posiblemente modificados por el VPOS, acorde a las necesidades de VISANET.

ReservedData Arreglos de objetos Reserved enviados por el comercio y posiblemente modificados por el sistema VPOS de acuerdo a las necesidades de VISANET.

cardType Tipo de tarjeta ingresado por el tarjetahabiente, el cual puede ser: VISA, MC, AMEX, DINERS, DISC

cardNumber Número enmascarado de tarjeta ingresado por el tarjetahabiente, solo muestra los 6 primeros dígitos y los 4 últimos.

cardExpiryMonth Mes de expiración de la tarjeta ingresada por el tarjetahabiente (con valor de 1 a 12) devuelto sólo si la transacción ha sido autorizada y VISANET permitió al comercio la devolución del valor

cardExpirationYear Año de expiración de la tarjeta como valor entero, retornado sólo si la transacción ha sido autorizada y permite la devolución del valor

fraudScore Para uso futuro

fraudFactor Para uso futuro

additionalObservations Observaciones adicionales retornadas por el sistema VPOS

Este método actúa como un acuse de recibo de la transacción, por lo tanto el comercio debe usarlo siempre para finalizar la transacción.

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 14 de 25

2.5. Solicitud de Reverso

La solicitud de reverso se define como el conjunto de datos que necesita el V-POS para generar la solicitud de reverso o anulación de una transacción autorizada. Para iniciar la solicitud de reverso, el comercio deberá consumir el web service a partir de las siguientes URLs las cuales definen el servicio: Testing: https://test2.alignetsac.com/VPOS/services/VPOSMMWSS11?wsdl Producción: https://vpayment.verifika.com/VPOS/services/VPOSMMWSS11?wsdl Método a usar: Reverse Parámetros de Envío Los parámetros que enviará el comercio al V-POS para iniciar la el reverso son los siguientes:

Campo Descripción

purchaseCode Código de compra, este valor es generado por el comercio, debe ser único por petición y es alfanumérico hasta 15 caracteres y debe corresponder al código de compra que generó la autorización a reversar, este dato es obligatorio.

2.5.1. Respuesta de pago

Parámetros devueltos por el Web Service La respuesta de reverso que devolverá el V-POS al comercio estará compuesta por los siguientes campos:

Campo Descripción

Result Valor numérico que indica si la transacción ha sido aprobada o denegada por el banco emisor o rechazada por el sistema (0=Aprobado, 1=Denegado)

errorCode Cadena que indica la causa de la denegación o el rechazo, devuelve un código

errorMessage Cadena que muestra en mensaje comprensible la causa de la denegación o rechazo, cada mensaje corresponde a un código de error

El comercio deberá basarse en estos valores para indicar si la autorización fue reversada o no.

3. Integración con el Web Service El comercio recibirá una URL con el WSDL necesario para el consumo del mismo. De acuerdo a cada plataforma de despliegue, existen diferentes formas de cómo consumir el Web Service Java – J2EE

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 15 de 25

4. Preguntas y Respuestas Frecuentes ¿Qué lenguajes soporta el consumo del Web Service? En la actualidad el Web Service ha sido probado en las plataformas J2EE 1.3, PHP y Microsoft .Net El documento describe que los comercios deben generar peticiones de certificados digitales. ¿Cómo se realiza esta generación? El comercio deberá generar los certificados digitales en la herramienta V-Payment, de acuerdo a lo explicado en el presente documento ¿Existe algún carrito de compras comercial que se integre al Web Service? No. En Internet existen varios sitios Web que ofrecen carritos de compras o sitios Web para comercios, pero para realizar la integración se necesita el soporte de un programador o desarrollador para que integre a la plataforma del comercio el consumo del Web Service.

5. Anexos 5.1. Anexo 1: Consumo del Web Service del VPOS WS en Java

5.1.1. Requisitos necesarios

Para poder utilizar consumir el Web Service del VPOSWS mediante el lenguaje de programación JAVA es necesario lo siguiente: Máquina Virtual de Java 1.4 o superior Entorno J2EE 1.3 o superior (para usarlo dentro de un contenedor Web) (http://ws.apache.org/axis2/) Si usan JDK 1.5 en adelante recomendamos descargarse la versión 1.4.1 o Superior (http://ws.apache.org/rampart/) Descargar el archivo correspondiente a la “Standard Binary Distribution” Rampart 1.5 o superior descargar de

http://www.apache.org/dyn/mirrors/mirrors.cgi/ws/rampart/1_3/rampart-1.3.zip Apache Ant 1.6 o superior BouncyCastle Provider 1.4 o superior http://downloads.bouncycastle.org/java/bcprov-

jdk1X-140.jar Donde 1X corresponde al 14 (JDK 1.4), 15 (JDK 1.5), etc.

5.1.2. Configuración de Axis para consumo de Web Service

Para consumir el Web Service usando Axis, se debe tener lo siguiente: 1. Apache Ant 1.6 o superior debidamente configurado. Debe definirse como variable de

entorno del sistema operativo con el nombre de ANT_HOME cuyo valor es el directorio donde se encuentra ubicado el directorio de Apache Ant.

2. Se debe descomprimir el archivo descargado correspondiente al Axis2 en el directorio de su preferencia (Ejemplo: c:\axis21.4\)

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 16 de 25

3. En el directorio indicado en el punto 2 se crea un subdirectorio para crear el stub cliente (Ejemplo: vposwscli)

4. En el directorio indicado en el punto 3 se debe crear un archivo build.xml con el siguiente contenido:

<project name="VPOSWSS10Client" default="main" basedir=".">

<tstamp></tstamp>

<target name="declare" >

<property name="axis.home" value=".."/>

<path id="axis.classpath">

<fileset dir="${axis.home}/lib">

<include name="**/*.jar" />

</fileset>

</path>

<taskdef name="codegen"

classname="org.apache.axis2.tool.ant.AntCodegenTask"

classpathref="axis.classpath"/>

</target>

<target name="main" depends="declare">

<codegen

databindingname="adb"

wsdlfilename="https://preprod.verifika.com/VPOS/services/VPOSMMWSS11?wsdl"

output="output-${DSTAMP}" serverside="true"

overwrite="true"

packagename="com.alignet.vpos.wss11.service"

namespacetopackages="http://www.alignet.com/VPOSMMWSS11/=com.alignet.vpos.wss11

,http://www.w3.org/2001/XMLSchema=com.alignet.vpos.wss11.types,=com.alignet.vpos.wss11

.types"

generateservicexml="true" generateallclasses="true" unpackclasses="true" >

</codegen>

</target>

</project>

Adicionalmente se debe crear un subdirectorio llamado output-AAAAMMDD con la fecha actual. *Nota: Para el ambiente de producción el url del valor wsdlfilename debe cambiar a: https://vpayment.verifika.com/VPOS/services/VPOSMMWSS11?wsdl 5. Agregar también los archivos jars que se encuentran en el directorio lib contenidos en el

archivo zip descargado de Rampart 1.3, los cuales deben ser copiados al directorio repository/modules del directorio creado en el paso 2 (directorio del Axis2)

6. Agregar el archivo jar del BouncyCastle descargado anteriormente 7. Se debe ejecutar desde líneas de comandos el comando ant, ubicándose en el

directorio del punto 3. 8. Se creará (tras ejecutar el punto anterior) un stub (esqueleto) de código el cual se

utilizará para el consumo del Web Service en el paquete

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 17 de 25

com.alignet.vpos.wss11.service. El código generado deberá llevarlo al aplicativo que usará el Web Services y se deberá colocar adicionalmente en el classpath del proyecto todos los archivos jar existentes de las carpetas lib de Axis2 y Rampart.

9. Como el servicio se debe usar mediante cliente seguro y este necesita acceso a los certificados y a las llaves contenidas en el archivo COM####.p12 (donde #### es un número que identifica al comercio) se tiene que crear un CallBack Handler (el cual es una clase que hereda de javax.security.auth.callback.Callback). En este caso se creará una clase llamada PasswordProvider

public class PasswordProvider implements CallbackHandler {

public void handle(Callback[] arg0) throws IOException,

UnsupportedCallbackException {

WSPasswordCallback pwdcallback = (WSPasswordCallback)

arg0[0];

pwdcallback.setPassword("vposmultimarcawss");

}

}

}

En este caso el valor del password del certificado descargado vía VPayment es vposmultimarcawss. 10. Debe crearse un archivo de políticas con la configuración de los certificados a usar en

testing. La base del archivo puede ser encontrada en la sección del final de este documento.

Entre los tags </sp:SignedParts> y </wsp:All> se agrega lo siguiente

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">

<ramp:user>client cert</ramp:user>

<ramp:encryptionUser>vposwssignature</ramp:encryptionUser>

<ramp:passwordCallbackClass>com.alignet.cliente.PasswordProvider

</ramp:passwordCallbackClass>

<ramp:signatureCrypto>

<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property

name="org.apache.ws.security.crypto.merlin.keystore.type">PKCS12</ramp:property>

<ramp:property

name="org.apache.ws.security.crypto.merlin.file">COM####.p12</ramp:property>

<ramp:property

name="org.apache.ws.security.crypto.merlin.keystore.password">vposmultimarcawss</ramp:

property>

</ramp:crypto>

</ramp:signatureCrypto>

<ramp:encryptionCypto>


<ramp:property


<ramp:property name="org.apache.ws.security.crypto.merlin.file">

COM####.p12</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">

vposmultimarcawss</ramp:property>

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 18 de 25

</ramp:crypto>

</ramp:encryptionCypto>

</ramp:RampartConfig>

A continuación se explica el significado de esta aserción en el archivo de políticas La estructura siguiente indica la configuración del Rampart <ramp:RampartConfig> … </ramp:RampartConfig> Se indica el alias del certificado con el que se firmará (alias del certificado cliente dentro del contenedor de certificados de firma). Ejemplo <ramp:user>client cert</ramp:user> A continuación se indica el alias del certificado de servidor dentro del contenedor de certificados de cifrado <ramp:encryptionUser>vposwssignature</ramp:encryptionUser> Se indica la clase que devuelve el valor del password del alias del certificado cliente como esta indicado en el paso 9 <ramp:passwordCallbackClass>com.alignet.cliente.PasswordProvider </ramp:passwordCallbackClass> A continuación se definen los contenedores de certificados para firma y cifrado, en este caso usamos el mismo El contenedor de certificados para firma se define con <ramp:signatureCrypto> … </ramp:signatureCrypto> El contenedor de certificados para cifrado se define con <ramp:encryptionCrypto> … </ramp:encryptionCrypto> Dentro de ambos contenedores puede ir el mismo contenido el cual indica que están en el mismo archivo o contenedor


<ramp:property


<ramp:property

name="org.apache.ws.security.crypto.merlin.file">COM####..p12</ramp:property>

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 19 de 25

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">

vposmultimarcawss</ramp:property>

</ramp:crypto>

Se indica que el contenedor está implementado por la clase org.apache.ws.security.components.crypto.Merlin la cual está contenida en el Rampart. También se indica que el contenedor es de tipo PKCS12 y el archivo se llama “COM####.p12” (donde #### es un identificador del comercio), la clave para abrir el archivo es “vposmultimarcawss” 11. Se muestra a continuación una clase que realiza el consumo del web service seguro

mediante políticas, para el método transactionStart

package com.alignet.cliente;

import org.apache.axiom.om.impl.builder.StAXOMBuilder;

import org.apache.axis2.context.ConfigurationContext;

import org.apache.axis2.context.ConfigurationContextFactory;

import org.apache.neethi.Policy;

import org.apache.neethi.PolicyEngine;

import org.apache.rampart.RampartMessageData;

import com.alignet.vpos.wss11.Currency;

import com.alignet.vpos.wss11.CurrencyCode;

import com.alignet.vpos.wss11.IPAddressType;

import com.alignet.vpos.wss11.LanguageType;

import com.alignet.vpos.wss11.OperationNumberType;

import com.alignet.vpos.wss11.TransactionStart;

import com.alignet.vpos.wss11.TransactionStartResponse;

import com.alignet.vpos.wss11.service.VPOSMMWSS11Stub;

public class ConsumeStart {

public static void main(String[] args) throws Exception {

ConfigurationContext ctx =

ConfigurationContextFactory.createConfigurationContextFromFileSystem("./client-repo", null);

// Se indica que el descriptor de modulos de Axis2 estas en client-repo

VPOSMMWSS11Stub client = new VPOSMMWSS11Stub(ctx,

"https://preprod.verifika.com/VPOS/services/VPOSMMWSS11?wsdl");

TransactionStart start = new TransactionStart();

CurrencyCode cc=new CurrencyCode();

cc.setCurrencyCode("840");

start.setCurrencyCode(cc);

IPAddressType ip = new IPAddressType();

ip.setIPAddressType("127.0.0.1");

start.setIPAddress(ip);

OperationNumberType on=new OperationNumberType();

on.setOperationNumberType("20");

start.setOperationNumber(on);

Currency cu=new Currency();

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 20 de 25

cu.setCurrency("100");

start.setPurchaseAmount(cu);

LanguageType l=new LanguageType();

l.setLanguageType("EN");

start.setLanguage(l);

client._getServiceClient().getOptions().setProperty(RampartMessageData

.KEY_RAMPART_POLICY, loadPolicy("client.policy.xml"));

client._getServiceClient().engageModule("rampart");

TransactionStartResponse response =

client.transactionStart(start);

System.out.println("getErrorCode : " +

response.getErrorCode());

System.out.println("getErrorMessage: " +

response.getErrorMessage());

System.out.println("getState : " + response.getState());

System.out.println("getURLScreen : " +

response.getURLScreen());

}

private static Policy loadPolicy(String xmlPath) throws Exception {

StAXOMBuilder builder = new StAXOMBuilder(xmlPath);

Policy politica =

PolicyEngine.getPolicy(builder.getDocumentElement());

return politica;

}

}

5.2. Anexo 2: Listado de códigos de error

A continuación se muestran los códigos de error devueltos por los métodos del Web Service (Pueden añadirse más códigos de error sin previo aviso). Códigos de Error del método “transactionFinish”

ErrorCode Error Message

00 Successful approval/completion

01 Refer to card issuer

02 Refer to card issuer, special condition

03 Invalid merchant/service provider

04 Pickup card

05 Do not honor

06 Error

07 Pick up card, special condition (other than lost/stolen card)

10 Partial approval

11 VIP approval

12 Invalid transacction

13 Invalid amount

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 21 de 25

14 Invalid account number (no such number)

15 No such issuer

19 Re-enter transaction

21 No action taken

25 Unable to locate record in file, or account number is missing from the inquiry

28 File is temporarily unavailable

41 Pickup card (lost card)

43 Pickup card (stolen card)

51 Not sufficient funds

52 No checking account

53 No saving account

54 Expired card

55 Incorrect PIN

57 Transaction not permitted to cardholder

58 Transaction not allowed at terminal

61 Exceeds withdrawal amount limit (activity amount limit exceeded)

62 Restricted card

63 Security violation

65 Activity count limit exceeded

75 Allowable number of PIN-entry tries exceeded

76 Unable to locate previous message (no match on Retrieval Reference number)

77 Previous message located for a repeat or reversal, butrepeat or reversal data are inconsistent with original message

80 Invalid date (For use in private label card transactions and check acceptance transactions)

81 PIN or CVV cryptographic error found (Used by VIC for error condition found by security module during PIN decryptation/CVV processing

82 Incorrect CVV

83 Unable to verify PIN

85 No reason to decline a request for account number verification or address verification, or CVV2 verification

91 Issuer or switch inoperative (stand-in not applicable or available for this transaction)

92 Destination cannot be found for routing

93 Transaction cannot be completed; violation of law

96 System malfunction/System malfunction or certain field error conditions

N0 Force STIP

N3 Cash service not available

N4 Cash request exceeds issuer limit

N7 Decline for CVV2 failure

P2 Invalid biller information

P5 PIN Change/Unblock request declined

P6 Unsafe PIN

R0 Stop Payment Order

R1 Revocation of Authorization Order

R3 Revocation of All Authorizations Order

Z3 Unable to go online; declined

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 22 de 25

XA Forward to issuer

XD Forward to issuer

Q1 Card Authentication failed

1001 Invalid Data sent by Commerce

1002 Invalid Currency for Commerce

1003 Invalid Commerce Code

1004 Duplicated order number

1101 Communication Problem

1102 Processing Problem

1103 Communication Problem

1104 Invalida Data

1107 Invalid VCI

1114 Card Number does not belong to selected brand

2100 Implementor Class not existent

2101 Default Plan Quotas inexistent

2102 Existing BIN for the acquirer but does not have Plan Quotas assigned

2200 Acquirer must need more data sent in the Plug-In

2201 Plan Quotas not sent by Commerce

2202 Duplicated order number

2300 User Cancelled in PASS 1



2308 Card Brand is not correct

2309 Card Number is not correct

2310 Card Expiry Date is not correct

2311 Card Security Code is not correct

2312 Card Number is not present and is required

2313 Commerce not well configured

2314 Acquirer not well configured

2315 Will not go to authorization due to Pre-Authorization Rules

2316 Transaction has been authorized but Post-Authentication Rules refused it

2317 Transaction has been authorized but has been reversed by Post-Authentication Rules

2303 PurchaseCode Field must not be greater than 12 characters

2305 Commerce is not active

2306 Acquirer is not active

2307 Transaction has been processed

2318 PurchaseOperationNumber is greater than 8 characters (Maximum for Associated Commerce)

2319 PurchaseOperationNumber is greater than 12 characters

2400 Transaction is rejected and will not be authorized due to pre-authorization rules

2401 Pre Authentication rules not approved

2402 Post Authenticacion rules not approved

2403 Maximum Monthly accumulated amount has been reached

2404 Maximum Daily accumulated amount has been reached

2405 Maximum Daily order number has been reached

2406 Maximum Monthly order number has been reached

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 23 de 25

2410 Mall cannot start transactions

2411 Shipper is needed but not found

2412 Shipping amount is not valid

2413 Purchase amount is not valid

2414 Associated Commerce amount is not valid

2415 Purchase Amount and Associated Commerce amount are not valid

3001 Rejected by Ecommerce rule

3002 Rejected by Ecommerce rule Error\t

3003 Rejected by Ecommerce rule Comm. Error

5000 Certificate does not belong to commerceId sent

2320 Commerce does not belong to Acquirer Sent

2304 Commerce does not exist

2203 Currency does not exists

Códigos de error del método “reverse”

ErrorCode Error Message

00 Successful approval/completion

4000 Trasaction neither exists nor has authorized state

4001 Execution error un reversal messaging, contact provider

5.3. Anexo 3: Archivo de políticas a usar en el VPOSWSS11

A continuación se muestra el contenido de las políticas a usar por el cliente Web Services

<?xml version="1.0" encoding="UTF-8"?>

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">

<wsp:ExactlyOne>

<wsp:All>

<sp:AsymmetricBinding

xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">

<wsp:Policy>

<sp:InitiatorToken>

<wsp:Policy>

<sp:X509Token

sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Alway

sToRecipient">

<wsp:Policy>

<sp:WssX509V3Token10/>

</wsp:Policy>

</sp:X509Token>

</wsp:Policy>

</sp:InitiatorToken>

<sp:RecipientToken>

<wsp:Policy>

<sp:X509Token

sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never

">

<wsp:Policy>

MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 24 de 25

<sp:WssX509V3Token10/>

</wsp:Policy>

</sp:X509Token>

</wsp:Policy>

</sp:RecipientToken>

<sp:AlgorithmSuite>

<wsp:Policy>

<sp:Basic128Rsa15/>

</wsp:Policy>

</sp:AlgorithmSuite>

<sp:Layout>

<wsp:Policy>

<sp:Strict/>

</wsp:Policy>

</sp:Layout>

</wsp:Policy>

</sp:AsymmetricBinding>

<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">

<wsp:Policy>

<sp:MustSupportRefKeyIdentifier/>

<sp:MustSupportRefEmbeddedToken/>

<sp:MustSupportRefIssuerSerial/>

</wsp:Policy>

</sp:Wss10>

<sp:EncryptedParts


<sp:Body/>

</sp:EncryptedParts>

<sp:SignedParts


<sp:Body/>

</sp:SignedParts>

<ramp:RampartConfig

xmlns:ramp="http://ws.apache.org/rampart/policy">

<ramp:user>client cert</ramp:user>

<ramp:encryptionUser>vposwssignature</ramp:encryptionUser>

<ramp:passwordCallbackClass>com.alignet.cliente.PasswordProvider</ramp:passwordCa

llbackClass>

<ramp:signatureCrypto>

<ramp:crypto

provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property


<ramp:property


MOTO POS PC


Versión Nº: 2

SGC_GUI35


Página 25 de 25

<ramp:property

name="org.apache.ws.security.crypto.merlin.keystore.password">vposmultimarcawss</ramp:pr

operty>

</ramp:crypto>

</ramp:signatureCrypto>

<ramp:encryptionCrypto>

<ramp:crypto

provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property


<ramp:property


<ramp:property

name="org.apache.ws.security.crypto.merlin.keystore.password">vposmultimarcawss</ramp:pr

operty>

</ramp:crypto>

</ramp:encryptionCrypto>

</ramp:RampartConfig>

</wsp:All>

</wsp:ExactlyOne>

</wsp:Policy>

moto pos pc - visanet.com.pe · se le hace entrega al comercio del cuestionario técnico con el fin...

Documents