Saltar a contenido

PagoEfectivo SDK para Android


Orbis Mobile Developers

Overview


PagoEfectivo SDK le permitirá implementar de forma rápida y sencilla transacciones online a través de la plataforma de PagoEfectivo para teléfonos Android.

En el siguiente manual encontrará todo lo necesario para poder empezar la implementación del SDK, así como la forma correcta de implementar sus principales funciones tales como: Generar un CIP, Listar CIPS, etc.

Pre requisitos


  • Android Studio 1.5.* o superior
  • JDK 7 ó superior
  • Versión actualizada del Android SDK
  • Android API 16 en adelante (Android 4.1 en adelante)

Instalación


Instalación manual

Para poder hacer uso del SDK de PagoEfectivo, necesitamos descargar el sdk através el siguiente link

Ahora agregaremos un nuevo modulo a nuestro proyecto, para ello tenemos 2 opciones

1. Primera Opción

Agregaremos un nuevo modulo para ello seguimos los siguientes pasos:

  1. Nos dirigimos a file -> seleccionamos new -> click en new

PagoEfectivoSDK par Android

  1. Ahora agregaremos un nuevo modulo ya sea importando un archivo .jar o .aar

PagoEfectivoSDK par Android

2. Segunda Opción
  1. Damos click en el icono "Project Structure" de Android Studio

    PagoEfectivoSDK par Android

  2. Ahora damos click en el icono "+", y luego nos aparecerá la ventana de nuevo modulo que esta en apartado Primera opción.

    PagoEfectivoSDK par Android

  3. Ahora seleccionamos la ruta del sdk de PagoEfectivo (.aar) y damos click en finish.

    PagoEfectivoSDK par Android

  4. Ahora podremos ver que el modulo se ha agregado a la estructura de nuestro proyecto

    PagoEfectivoSDK par Android

Finalmente no olvidar compilar el nuevo modulo con tu aplicación, en el archivo build.gradle dentro del modulo app agregar las siguiente

1
2
3
4
5
dependencies {
    ...
    implementation project(':pagoefectivosdk')
    ...
}

Inicializar PagoEfectivo SDK


Para poder implementar las funciones CIPs de PagoEfectivo en tu proyecto, es necesario inicializar la librería. Para lo cual necesitas los siguientes valores antes de empezar:

  • Service Id
  • Access Key
  • Secret Key

Info

Si aún no tienes tus Keys de conexión por favor comunicarse aquí

Inicializar la librería de PagoEfectivo es muy simple, sólo necesitas llamar a la siguiente línea:

Java

1
    PagoEfectivoSdk pagoEfectivoSdk = PagoEfectivoSdk.initialize(this);

Kotlin

1
    val pagoEfectivoSdk = PagoEfectivoSdk.initialize(this)

Luego en el objeto PagoEfectivoSdk, es necesario setear las variables mencionadas anteriormente.

Java

1
2
3
    pagoEfectivoSdk.setServiceId(SERVICEID);
    pagoEfectivoSdk.setAccessKey("ACCESKEY");
    pagoEfectivoSdk.setSecretKey("SECRETKEY");

Kotlin

1
2
3
    pagoEfectivoSdk.setServiceId(SERVICEID)
    pagoEfectivoSdk.setAccessKey("ACCESKEY")
    pagoEfectivoSdk.setSecretKey("SECRETKEY")

SandBox

En ambos lenguajes, si se desease trabajar en modo SandBox (ambientes PRE), se tiene que setear la siguiente propiedad en true, de no hacerse, el SDK siempré trabajara por default apuntando a Producción.

1
    pagoEfectivoSdk.setSandBox(true);

Como se observa, el objeto necesita un contexto para inicializarse. El cual puede ser obtenido de cualquier actividad y/o fragmento. Se recomienda obtenerlo de la subclase Application en el método onCreate.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        PagoEfectivoSdk pagoEfectivoSdk = PagoEfectivoSdk.initialize(this);
        pagoEfectivoSdk.setServiceId(SERVICEID);
        pagoEfectivoSdk.setAccessKey("ACCESKEY");
        pagoEfectivoSdk.setSecretKey("SECRETKEY");
    }
}

Kotlin

1
2
3
4
5
6
7
8
class MyApplication : Application() {
    override fun onCreate() {
        val pagoEfectivoSdk = PagoEfectivoSdk.initialize(this)
        pagoEfectivoSdk.setServiceId(SERVICEID)
        pagoEfectivoSdk.setAccessKey("ACCESKEY")
        pagoEfectivoSdk.setSecretKey("SECRETKEY")
    }
}

No olvidar que al implementar nuestra propia subclase Application es necesario declarar su nombre en el AndroidManifest.xml

1
2
3
4
<application
  android:name=".MyApplication"
  ...
/>

Uso de PagoEfectivo SDK | CIP's Functions


Con el SDK ya instalado en nuestro IDE las llamadas a las funciones para CIP's serán muy sencillas.

Paso 1: Crear una variable en tu clase de tipo PagoEfectivoSdk

Java

1
    PagoEfectivoSdk instance;

Kotlin

1
    val instance

Paso 2: Inicializar tu variable con el método getInstance().

Java

1
    instance = PagoEfectivoSdk.getInstance();

Kotlin

1
    instance = PagoEfectivoSdk.getInstance()

Paso 3: Llamar las funciones que requieras!

generateCip()

Java

1
    instance.generateCip(Language.SPANISH_PERU, cipRequest, this);

Kotlin

1
    instance.generateCip(Language.SPANISH_PERU, cipRequest, this)

searchCip()

Java

1
    instance.searchCip(Language.SPANISH_PERU, requestList, this);

Kotlin

1
    instance.searchCip(Language.SPANISH_PERU, requestList, this)

PagoEfectivo SDK | Generar CIP


Para poder generar un CIP se tiene que tener en cuenta los siguientes 3 pasos:

  • Preparar objeto CipRequest
  • Implementar CipListener
  • Llamar al método generateCip()

Veamos cómo hacerlo en detalle:

1. Preparar Objeto CipRequest

La petición para crear un CIP requiere de los siguientes campos:

  • currency (Requerido)
  • amount (Requerido)
  • transactionCode (Requerido)
  • adminEmail (Opcional)
  • dateExpiry (Opcional)
  • paymentConcept (Opcional)
  • additionalData (Opcional)
  • userEmail (Requerido)
  • userName (Opcional)
  • userLastName (Opcional)
  • userUbigeo (Opcional)
  • userCountry (Opcional)
  • userDocumentType (Opcional)
  • userDocumentNumber (Opcional)
  • userPhone (Opcional)
  • userCodeCountry (Opcional)

Todos estos campos los puedes setear declarando un objeto de tipo CipRequest. Aquí te mostramos un pequeño ejemplo con algunos campos.

Java

1
2
3
4
    CipRequest cipRequest = new CipRequest();
    cipRequest.setUserEmail("user@gmail.com");
    cipRequest.setTransactionCode("777");
    cipRequest.setAmount(777.77);

Kotlin

1
2
3
4
    val cipRequest = CipRequest()
    cipRequest.userEmail = "user@gmail.com"
    cipRequest.transactionCode = "777"
    cipRequest.amount = 777.77

Para el caso de currency y userDocumentType, se debe setear los campos con variables predefinidas por el SDK. como ejemplo de moneda a usar USD y de tipo de documento DNI.

Java

1
2
    cipRequest.setCurrency(Currency.USD);
    cipRequest.setUserDocumentType(DocumentType.DNI);

Kotlin

1
2
    cipRequest.currency = Currency.USD
    cipRequest.userDocumentType = DocumentType.DNI

El uso de los objetos Currency o DocumentType les permite acceder a las opciones disponibles para cada campo respectivamente.

Currency Currency


DocumentType DocumentType)

Hecho todo lo anterior, se procede con el paso número 2.

2. Implementar CipListener

El SDK provee un callback que le permite tener los siguientes 3 estados al generar un CIP

  • onCipSuccessful | Evento lanzado cuando el CIP fue generado correctamente, devolviendo un objeto de tipo CIP con todos sus datos respectivos.
  • onCipError | Evento lanzado cuando sucedió un error al generar el CIP, devuelve una lista de todos los errores o error ocurridos durante el proceso (Ver apartado de Errores).
  • onCipFailure | Evento lanzado cuando sucedió un error de conexión con los servicios de PagoEfectivo, devolviendo un mensaje de error (String) de lo sucedido.

Para poder llamar los callbacks de la generación de CIP, basta con implementar en la clase donde se esté trabajando, la interfaz CipListener

Ejemplo de implementación en una Actividad

Java CipListener

Kotlin CipListener

Cuando la interfaz es implementada, sus respectivos métodos son llamados en la clase.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    @Override
    public void onCipSuccessful(CipEntity cipEntity) {
        //TODO: CODE HERE
    }

    @Override
    public void onCipError(List<CipError> message) {
        //TODO: CODE HERE
    }

    @Override
    public void onCipFailure(String message) {
        //TODO: CODE HERE
    }

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    override fun onCipSuccessful(cipEntity: CipEntity) {
        TODO("CODE HERE")
    }

    override fun onCipError(message: List<CipError>) {
        TODO("CODE HERE")
    }

    override fun onCipFailure(message: String) {
        TODO("CODE HERE")
    }

Con los pasos anteriores hechos, se procede a llamar a la función de generación de CIP's.

3. Método generateCip()

El método generateCip() recibe 3 parámetros:

  • Objeto CipRequest | Generado en el paso 1
  • CipListener Callback | Generado en el paso 2
  • Lenguaje de la petición (Language Object)

Para el lenguaje de la petición, el SDK provee una clase que le dará los idiomas soportados por el SDK. Esta es la clase Language.

Clase Language Language

Teniendo definido los 3 parámetros, el método se llama con una instancia de la clase PagoEfectivoSdk. Aquí te mostramos un ejemplo usando como idioma predefinido el idioma SPANISH_PERU

Java

1
2
3
4
    PagoEfectivoSdk instance;
    instance = PagoEfectivoSdk.getInstance();

    instance.generateCip(Language.SPANISH_PERU, cipRequest, this);

Kotlin

1
2
3
    val instance = PagoEfectivoSdk.getInstance()

    instance.generateCip(Language.SPANISH_PERU, cipRequest, this)

Cabe mencionar que en caso no se setee el lenguaje en la petición, esté será por default SPANISH_PERU.

Java

1
2
3
4
    PagoEfectivoSdk instance;
    instance = PagoEfectivoSdk.getInstance();

    instance.generateCip(cipRequest, this);

Kotlin

1
2
3
    val instance = PagoEfectivoSdk.getInstance()

    instance.generateCip(cipRequest, this)

El CIP generado por este método, se podrá consumir desde el llamado del callback onCipSuccessful(), método que devuelve un objeto CIP resultante del método anterior, con todos sus métodos getters respectivos para poder consumirlo y usarlo como convenga en la aplicación cliente.

onCipSuccessful()

Java onCipSuccessful


Kotlin onCipSuccessful

PagoEfectivo SDK | Listar CIP's


En la función de Listar CIP's se consideran los siguientes 3 pasos:

  • Preparar un CIP o una lista de CIP's a buscar (elementos de tipo Int)
  • Implementar SearchListener
  • Llamar al método searchCip()

1. Preparar Cip(s)

Para buscar CIPs podemos hacerlo directamente con una variable de tipo int o con una lista de este mismo tipo, si se desea buscar más de un CIP al mismo tiempo:

Java

1
2
3
4
5
6
7
    //Only one Cip
    int cip = 7777777;

    //Multiple Cips
    List<Integer> listCips = new ArrayList<>();
    listCips.add(7777777);
    listCips.add(3333333);

Kotlin

1
2
3
4
5
6
7
    //Only one Cip
    val cip = 7777777

    //Multiple Cips
    val listCips = ArrayList<Int>()
    listCips.add(7777777)
    listCips.add(3333333)

2. Implementar SearchListener

El SDK provee un callback que le permite tener los siguientes 3 estados al generar un CIP

  • onSearchSuccessful | Evento lanzado cuando la búsqueda se efectuó correctamente, devolviendo una lista de objetos de tipo CipSearch con todos sus datos respectivos. Cabe resaltar en este punto que si se envió una lista con varios Cips a buscar y uno o más de ellos son inexistentes o erróneos, el método devolverá una lista con los cips correctos, y los incorrectos aparecerán con una estructura vacía por ser valores no encontrados.
  • onCipError | Evento lanzado cuando sucedió un error al buscar CIPs, devuelve una lista de todos los errores o error ocurridos durante el proceso (Ver apartado de Errores).
  • onCipFailure | Evento lanzado cuando sucedió un error de conexión con los servicios de PagoEfectivo, devolviendo un mensaje de error (String) con lo sucedido.

Para poder llamar los callbacks de la búsqueda de CIPs, basta con implementar en la clase donde se esté trabajando, la interfaz SearchListener

Ejemplo de implementación en una Actividad

Java SearchListener Kotlin SearchListener

Cuando la interfaz es implementada, sus respectivos métodos son llamados en la clase.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    @Override
    public void onSearchSuccessful(List<CipError> list) {
        //TODO: CODE HERE
    }

    @Override
    public void onCipError(List<CipError> message) {
        //TODO: CODE HERE
    }

    @Override
    public void onCipFailure(String message) {
        //TODO: CODE HERE
    }

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    override fun onSearchSuccessful(list: List<CipSearch>) {
        TODO("CODE HERE")
    }

    override fun onCipError(message: List<CipError>) {
        TODO("CODE HERE")
    }

    override fun onCipFailure(message: String) {
        TODO("CODE HERE")
    }

Con los pasos anteriores hechos, se procede a llamar a la función de búsqueda de CIP's.

3. Método searchCip()

El método searchCip() recibe 3 parámetros:

  • CIP o CIPs a buscar | Generado en el paso 1
  • SearchListener Callback | Generado en el paso 2
  • Lenguaje de la petición (Language Object)

Para el lenguaje de la petición, el SDK provee una clase que le dará los idiomas soportados por el SDK. Esta es la clase: Language.

Clase Language Language

Teniendo definido los 3 parámetros, el método se llama con una instancia de la clase PagoEfectivoSdk. Aquí te mostramos un ejemplo usando como idioma predefinido el idioma SPANISH_PERU

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    PagoEfectivoSdk instance;
    instance = PagoEfectivoSdk.getInstance();

    //One Cip
    instance.searchCip(Language.SPANISH_PERU, cip, this);

    //Multiple Cips
    List<Integer> listCips = new ArrayList<>();
    listCips.add(7777777);
    listCips.add(3333333);

    instance.searchCip(Language.SPANISH_PERU, listCips, this);

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    val instance: PagoEfectivoSdk
    instance = PagoEfectivoSdk.getInstance()

    //One Cip
    instance.searchCip(Language.SPANISH_PERU, cip, this)

    //Multiple Cips
    val listCips = ArrayList<Int>()
    listCips.add(7777777)
    listCips.add(3333333)

    instance.searchCip(Language.SPANISH_PERU, listCips, this)

Cabe mencionar que en caso no se setee el lenguaje en la petición, esté será por default SPANISH_PERU tal como sucede en el generateCip().

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    PagoEfectivoSdk instance;
    instance = PagoEfectivoSdk.getInstance();

    //One Cip
    instance.searchCip(cip, this);

    //Multiple Cips
    List<Integer> listCips = new ArrayList<>();
    listCips.add(7777777);
    listCips.add(3333333);

    instance.searchCip(listCips, this);

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    val instance: PagoEfectivoSdk
    instance = PagoEfectivoSdk.getInstance()

    //One Cip
    instance.searchCip(cip, this)

    //Multiple Cips
    val listCips = ArrayList<Int>()
    listCips.add(7777777)
    listCips.add(3333333)

    instance.searchCip(listCips, this)

El CIP(s) resultante(s) de esta función, se podrá(n) consumir desde el llamado del callback onSearchSuccessful(), método que devuelve todos los CIPs buscados por el usuario a través de una lista de objetos CipSearch.

onSearchSuccessful()

Java onSearchSuccessful Kotlin onSearchSuccessful

PagoEfectivo SDK | Tratamiento de Errores


Para la implementación de generateCip() y searchCip() fueron necesarios el uso de sus respectivos listener (CipListener & SearchListener) los cuales tienen en común una función para el tratamiento de errores onCipError().

onCipError() devuelve una lista de objetos de tipo CipError. El cual tiene 3 campos básicos:

  • code --> Código del error generado
  • field --> Campo Errado o Sección errada
  • message --> Descripción del error

Al ser una lista, esta se puede recorrer listando así el(los) error(es) que se puedan generar al llamar las funciones respectivas del SDK.

Java ciperror

Kotlin ciperror

PagoEfectivo SDK | Proguard Configurations


Si está usando ProGuard en su proyecto agregue las siguientes líneas a su archivo de configuración Proguard:

1
2
3
-keep class pe.kdsep.** { *; }
-dontwarn javax.annotation.**
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement

Cualquier duda puedes escribirnos a: feedback@pagoefectivo.pe.