carpeta de integraciÓn de librerÍa mpos para …€¦ · 3 merchantreference número de...

Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android

Versión N° 2.0

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 12

CARPETA DE INTEGRACIÓN

DE LIBRERÍA MPOS PARA

DISPOSITIVOS MÓVILES

ANDROID


Versión N° 2.0


Página 2 de 12

ÍNDICE

1. OBJETIVO GENERAL .......................................................................................................... 3

2. DEFINICIONES ...................................................................................................................... 3

3. REQUISITOS OBLIGATORIOS PARA EL APP DEL COMERCIO ...................................... 3

3.1. SECCIÓN DE PAGOS ....................................................................................................... 3

3.2. NO DIFERENCIACIÓN ENTRE MEDIOS DE PAGO ........................................................ 3

4. USO E IMPLEMENTACIÓN DE LOS LOGOS DE VISA PARA APPS ................................ 3

5. DIAGRAMA DE ALTO NIVEL DE LA SOLUCIÓN ............................................................... 4

6. EJEMPLO DE INTEGRACIÓN PARA ANDROID (JAVA) ................................................... 4

7. RESULTADO DE LA TRANSACCIÓN ............................................................................... 10

7.1. PARÁMETROS DE RESPUESTA ................................................................................... 10

7.2. RESPUESTA FINAL AL TARJETAHABIENTE .............................................................. 11

8. AMBIENTE DE DESARROLLO .......................................................................................... 12

9. PASE A PRODUCCIÓN ...................................................................................................... 12


Versión N° 2.0


Página 3 de 12

1. Objetivo General

Este documento tiene como objetivo proveer los lineamientos para integrar la librería mPOS, desarrollada por VisaNet del Perú, en aplicaciones móviles de comercios afiliados y a través de esta efectuar transacciones de mPOS desde cualquier dispositivo con sistemas operativos Android 4.1.x (SDK 16+) o superior.

2. Definiciones

Integración: Proceso de pruebas y adecuaciones para poder realizar ventas por

aplicativos móviles utilizando las librerías de VisaNet Perú y cumplir con los requerimientos especificados en este documento.

Sección de Pagos: Pantalla donde se selecciona el producto o servicio a cobrar. Tarjetahabiente: Persona titular de una tarjeta, en este caso, de la marca VISA. App: Es un aplicativo informático diseñado para ser ejecutado en teléfonos

inteligentes, tabletas y otros dispositivos móviles.

3. Requisitos Obligatorios para el APP del Comercio

3.1. Sección de Pagos

Colocar el logo de Visa según lo especificado en el punto 4. Uso e implementación de los logos de Visa para APPS. 3.2. No diferenciación entre medios de pago

La marca VISA, sus logos y la indicación de poder pagar con medios de pago VISA no deben tener menor prominencia que otras marcas o medios de pago.

4. Uso e implementación de los logos de Visa para APPS

Los logos oficiales de la marca VISA deben ser descargados desde la web del producto http://www.visanet.com.pe/comercio_electronico, en la sección “Descargar Logo”, tal y como se muestra en la figura. Utilizar únicamente el Logo VISA (no aplica el de Verified by Visa)

http://es.wikipedia.org/wiki/Tel%C3%A9fonos_inteligentes

http://es.wikipedia.org/wiki/Tel%C3%A9fonos_inteligentes

http://es.wikipedia.org/wiki/Tableta_(computadora)

http://www.visanet.com.pe/comercio_electronico


Versión N° 2.0


Página 4 de 12

Los logos VISA, o alguna porción de éstos, nunca deben ocultarse, distorsionarse,

desfigurarse ni alterarse de manera alguna, ni aparecer con menor prominencia que otras marcas de medios de pagos.

Los comercios afiliados no podrán usar las marcas ni logos propiedad de Visa de una manera que pudiera perjudicar la reputación de Visa Inc., VisaNet del Perú o cualquiera de sus afiliadas y de las Marcas Propiedad de Visa.

Los comercios que no cumplan con los requisitos para la implementación y uso de los logos VISA no podrán completar la integración ni ser activados en producción.

VisaNet Perú podrá revisar periódicamente el cumplimiento de los lineamientos para la implementación de logos.

5. Diagrama de Alto Nivel de la Solución

La integración de los comercios afiliados a VisaNet Perú se hará a través de una librería que se conectará a la plataforma de VisaNet Perú y enviará la información de la transacción. La librería está desarrollada para la plataforma: Android 4.1.x (SDK 16+).

6. Ejemplo de Integración para Android (Java)

Para poder integrar la librería en una aplicación Android se deberá seguir los siguientes pasos:

1. Consideraciones previas: a. Utilizar IDE Android Studio 1.1.0 o superior. b. Utilizar un Smartphone o Tablet certificada por Google (Play Store instalado de

fábrica) con SO Android 4.1 o superior. c. Tener activo el Bluetooth y vincular el PINPAD que VisaNet proporcionará. d. Tener conexión a Internet desde el dispositivo móvil.

2. Incluir el archivo “visanetMPOS.x.x.aar” (donde x.x corresponde a la versión vigente) en la carpeta “libs” del proyecto de aplicación.


Versión N° 2.0


Página 5 de 12

3. Configurar el archivo …\app\build.grandle.

a. Agregar las siguientes líneas en la raíz del archivo. repositories{ flatDir{ dirs 'libs' } }

b. Agregar las siguientes líneas dentro de la rama “dependencies”. //estas 2 librerías son necesarias en la lib 2.0.

compile 'com.android.support:percent:22.2.0'

compile 'com.android.support:design:23.1.1'

////////////////////

compile(name:'visanetMPOS.2.0', ext:'aar')

El archivo debe quedar similar a la imagen

Versión N° 2.0


Página 6 de 12

4. Configurar el archivo …\app\src\main\AndroidManifest.xml a. Agregar las siguientes líneas en la raíz del archivo.

<uses-permission android:name="android.permission.BLUETOOTH" />

<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

b. Agregar las siguientes líneas dentro de la rama “aplication”. 

<activity

android:name="pe.beyond.visanet.events.authorization.AuthorizationActivity"

android:configChanges="keyboardHidden|orientation|screenSize"

android:theme="@style/ThemeVisanetNoTitleDialog"></activity>

<activity

android:name="pe.beyond.visanet.events.cancellation.CancellationActivity"



<activity

android:name="pe.beyond.visanet.events.history.HistoryActivity"



<activity

android:name="pe.beyond.visanet.events.initialization.InitializationActivity"



<activity

android:name="pe.beyond.visanet.events.linkTerminal.LinkTerminalActivity"



5. Definir las variables estáticas dentro de su Proyecto/Activity para indicar el ambiente al que se desea apuntar y definir el Api Key que debe utilizar. Más adelante se indican las URL de desarrollo y de producción.

a. URL_VISA_MPOS b. API_KEY

6. Inicializar el manejador de la librería para poder utilizar los métodos para esto debe

realizar lo siguiente: a. Definir la variable “manager” de tipo MPOSManagerSession.

b. Inicializar la variable en el método onCreate.

c. Manejo de voucher. La librería permite dos tipos de manejo de voucher:

i. Generación, presentación y envío de voucher desde de la librería de VisaNet.


Versión N° 2.0


Página 7 de 12

ii. Entrega de resultado a la aplicación del comercio para que está genere, presente y envíe/imprima el voucher.

Para determinar el modo de trabajar se debe indicar i. manager.setIsVoucherRequired(true). Para que la generación del

voucher quede dentro del manejo de la librería. ii. manager.setIsVoucherRequired(false)1. Para que la librería entregue el

resultado a la aplicación del comercio y esta genere el voucher.

7. Sobrescribir el método “onActivityResult”.

8. Invocar a los métodos de la librería. Una vez que realizó la inicialización de variables ya

se puede utilizar los métodos proporcionados por la librería de VisaNet. A continuación se indican los segmentos de código de cada una de los métodos (Autorizar, Anular, Reporte de Operaciones).

a. Autorizar.

b. Anular.

1 Si selecciona este tipo de integración debe revisar el anexo “Generación de Voucher MPOS”.


Versión N° 2.0


Página 8 de 12

c. Reporte de Operaciones.

Nota: A partir del momento de la invocación de algún método el control pasa a la librería de VisaNet Perú.


Versión N° 2.0


Página 9 de 12

9. Procesar la respuesta. Cada uno de los métodos expuestos por la librería retorna un

Bean con la información de respuesta de la transacción realizada. Para cada uno de los métodos la respuesta se obtiene de la siguiente forma.

a. Autorizar.

b. Anular.

c. Reporte de Operaciones.


Versión N° 2.0


Página 10 de 12

10. Al terminar los procesos dentro de la librería el control vuelve a la aplicación del comercio. Para conocer el estado de la transacción de autorización y anulación se debe analizar el estado del campo “isResponseSuccessful” (true= Tx. satisfactoria y false= Tx. denegada).

7. Resultado de la Transacción

7.1. Parámetros de Respuesta

Al momento que la transacción haya sido procesada, el método invocado devolverá un objeto (MPOSBean) con los siguientes parámetros:

# Parámetro Descripción

1 responseCode Estado de la transacción

a. Aprobado = 00, 09 u 11

b. Denegada = Otros valores

2 transactionId Identificador Único de la transacción (sólo en caso de aprobadas)

3 merchantReference Número de referencia generado por el sistema del comercio

4 bank Nombre del emisor de la tarjeta usada en el pago

5 merchantName Nombre del comercio

6 merchantId Código del comercio

7 merchantLocation Localidad del comercio

8 track2 Número de tarjeta enmascarada

9 logicalTerminalId Identificación del terminal

10 batchNumber Número de Lote

11 ticketNumber Número de referencia de la transacción

12 authorizationCode Código de autorización

13 transactionLocalDate Fecha de la transacción

14 transactionLocalTime Hora de la transacción


Versión N° 2.0


Página 11 de 12

15 currencyLabel Moneda de la transacción

16 transactionAmount Importe de la transacción

17 prizeMessage Mensaje de premio.

18 hostMessage Mensaje del host.

19 tApp Etiqueta de la aplicación (este valor sólo retorna cuando la transacción se realiza

con lectura de chip)

20 tAid Dato AID = Application ID (este valor sólo retorna cuando la transacción se realiza

con lectura de chip)

21 tCT Dato CT = Criptograma (este valor sólo retorna cuando la transacción se realiza con

lectura de chip)

22 version Versión utilizada

23 voucherType Tipo de voucher:

a. CREDITO

b. DEBITO

24 currencyCode Código de moneda

25 traceNumber Número de trace

26 statusType Estado de la transacción (AUTHORIZED, REFUNDED, DENIED)

27 processingCode Código de procesamiento = 000000

28 discountAmount Importe de descuento

29 retrievalReferenceNumber Numero de referencia de recuperación

30 terminalId Número físico del terminal

31 transactionUUID Identificador único de la transacción mPOS

32 prizeCode Código de premio

33 prizeType Tipo de premio

34 voucherPaymentsNumber Número de cuotas.

35 voucherPaymentsAmount Valor de la cuota aproximada.

36 voucherEmail Correo de tarjetahabiente.

7.2. Respuesta Final al Tarjetahabiente

Una vez obtenido el resultado de la transacción, el comercio deberá mostrar la pantalla final de respuesta al cliente. La pantalla final de compra debe mostrar, cómo mínimo y obligatoriamente, la siguiente información:

ID de la transacción // En caso sea aprobada la operación Resultado de la Operación (Aprobada o Denegada) Motivo de Denegación // En caso sea denegada la operación Número de Tarjeta Enmascarado (PAN) Importe Autorizado (IMP_AUTORIZADO)


Versión N° 2.0


Página 12 de 12

Cuando la integración utiliza la opción de manejo de voucher “manager. setIsVoucherRequired(false)” (ver punto 6.c del documento). Es obligatorio que el aplicativo del comercio genere, presente y envíe/imprima el voucher (para generar el voucher debe seguir los lineamientos del anexo “Generación de Voucher”). Adicionalmente, se debe solicitar de manera obligatoria la firma al tarjetahabiente en el voucher.

8. Ambiente de Desarrollo

Durante la etapa de integración (desarrollo) el comercio debe configurar en el código fuente el parámetro EndPointURL con la siguiente URL: https://devapps.vnmpos.com/ecore.gateway/api/v1/transactions

9. Pase a Producción

VisaNet Perú realizará las revisiones necesarias para garantizar que el App del comercio cumpla con lo especificado en este documento antes de autorizar el pase a producción del mismo de acuerdo al procedimiento definido. Una vez terminada la etapa de integración, y con la certificación de VisaNet Perú, el comercio debe configurar en el código fuente el parámetro EndPointURL con la siguiente URL: https://apps.vnmpos.com/ecore.gateway/api/v1/transactions

10. Aplicación de Ejemplo

VisaNet Perú proporcionará una aplicación de ejemplo donde se encontrá cada una de las funcionalidades explicada en el presente documento sin que ello implique alguna obligatoriedad o compromiso por parte de VisaNet Perú de entregar programas fuentes o revisar los programas fuentes del propio comercio.

https://devapps.vnmpos.com/ecore.gateway/api/v1/transactions

https://apps.vnmpos.com/ecore.gateway/api/v1/transactions

carpeta de integraciÓn de librerÍa mpos para …€¦ · 3 merchantreference número de...

Documents