Story Transcript
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
CARPETA DE INTEGRACIÓN DE LIBRERÍA MPOS PARA DISPOSITIVOS MÓVILES ANDROID
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 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
Í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 ................................................................................. 9
7.1.
PARÁMETROS DE RESPUESTA ..................................................................................... 9
7.2.
RESPUESTA FINAL AL TARJETAHABIENTE .............................................................. 10
8.
AMBIENTE DE DESARROLLO .......................................................................................... 10
9.
PASE A PRODUCCIÓN ...................................................................................................... 11
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 2 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
1.
Versión N° 1.0
Objetivo General Este documento tiene como objetivo proveer los lineamientos para la integración de la librería desarrollada por VisaNet Perú que va a funcionar dentro de las aplicaciones móviles de comercios afiliados para permitir efectuar transacciones de mPOS desde cualquier dispositivo móvil con sistemas operativos Android.
2.
Definiciones
3.
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.
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)
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 3 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
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 posterior. 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.
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 4 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
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”. compile 'com.android.support:appcompat-v7:22.0.0' compile(name:'visanetMPOS.1.0', ext:'aar')
El archivo debe quedar similar a la imagen
4. Configurar el archivo …\app\src\main\AndroidManifest.xml a. Agregar las siguientes líneas en la raíz del archivo.
b. Agregar las siguientes líneas dentro de la rama “aplication”.
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 MPOSmanager.
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. ii. Entrega de resultado a la aplicación del comercio para que está genere, presente y envío/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.
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 6 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
1
ii. manager.setIsVoucherRequired (false) . 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.
c. Reporte de Operaciones.
1
Si selecciona este tipo de integración debe revisar el anexo “Generación de Voucher”. 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 7 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
Nota: A partir del momento de la invocación de algún método el control pasa a la librería de VisaNet Perú.
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.
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 8 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
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: # 1
Parámetro
Descripción
responseCode
Estado de la transacción
2
transactionId
a. Aprobado = 00, 09 u 11 b. Denegada = Otros valores 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
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)
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 9 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android
Versión N° 1.0
22
version
Versión utilizada
23
voucherType
Tipo de voucher:
24
currencyCode
a. CREDITO b. DEBITO 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)
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
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 10 de 11
22/04/2015
Carpeta de Integración de Librería mPOS para Dispositivos Móviles – Android 9.
Versión N° 1.0
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.
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 11 de 11
22/04/2015