SDK de Android v2.2.2

Introducción

Desarrolla una aplicación de punto de venta para dispositivos móviles utilizando el SDK de Clip y un dispositivo Clip Plus.

Prerrequisitos

Para poder integrar el SDK de Clip a tu aplicación de Android, debes cumplir los siguientes prerrequisitos:

• Tener una cuenta de Clip.
• Que tu aplicación soporte, como mínimo, la versión 17 de Android.
• Agregar las librerías del SDK como dependencias en el proyecto de Android.
• Configurar los permisos del dispositivo requeridos por el SDK.

Ambientes de desarrollo

📘

Nota

Por el momento no existe un ambiente “sandbox” para pruebas y sólo está disponible el ambiente de producción.

Trabajando con el proyecto demo

El SDK de Clip para Android te ofrece un proyecto demo. Es una referencia para la integración del SDK en una aplicación Android.

Las funciones que permite desarrollar la librería son:

• Crear un objeto de pago
• Obtener el historial de transacciones
• Iniciar y cerrar la sesión de Clip desde tu aplicación
• Configurar los ajustes del dispositivo (Settings)
• Crear enlaces para pagos a distancia

Permisos del dispositivo

Para poder integrar el SDK de Clip en tu aplicación de Android, es necesario incluir los siguientes permisos para el dispositivo que utilizará la aplicación.

Configura tu archivo AndroidManifest.xml con los siguientes permisos:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

La siguiente lista incluye una descripción para cada uno de los permisos del dispositivo:

• INTERNET: Permite que la aplicación se conecte a internet.
• ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE: Permite verificar el estado de conectividad de red del dispositivo.
• ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION: Para obtener la ubicación del lugar en que se realiza la transacción.
• BLUETOOTH, BLUETOOTH_ADMIN: Para descubrir y emparejar nuevos dispositivos desde la aplicación Android y conectarse con la terminal de Clip.

Agregando las Dependencias

Es necesario agregar el SDK de Clip como dependencia en el archivo build.gradle de tu proyecto de Android.

Agrega el siguiente repositorio en el módulo del proyecto:

allprojects {
	        repositories {
                   …
                   maven {url 'https://developer.huawei.com/repo/'}
               } 
	}

Agrega las siguientes dependencias en el módulo de aplicación:

dependencies {
	        implementation 'com.payclip.sdk:payment-ui:2.2.2'
	        implementation 'com.payclip.sdk:plus-reader:1.2.0'
	}

Inicializando la aplicación

Inicializa el SDK de Clip desde tu clase Application.

class MyApplication : Application() {
   override fun onCreate() {
       super.onCreate()
       ClipApi.init(this, ClipPlusApi())
   }
}

public class MyApplication extends Application {
   @Override
   public void onCreate() {
       super.onCreate();
       ClipApi.init(this, new ClipPlusApi());
   }
}

📘

Nota

La instancia de ClipPlusApi() brinda compatibilidad para los lectores Clip Plus y Clip Plus 2.

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para configurar el SDK en tu proyecto.

Iniciar la sesión de Clip

Desde tu aplicación, puedes iniciar la sesión de Clip en tu aplicación.

Para iniciar la sesión de Clip desde la aplicación, implementa la siguiente función:

ClipApi.login(email: String, password: String, object: LoginListener {
   override fun onLoginSuccess(statusCode: Int) {
       // Login was successful
   }

   override fun onLoginFailed(statusCode: Int) {
       // Login failed
   }
})

ClipApi.login(String email, String password, new LoginListener() {
    @Override
    public void onLoginSuccess(int statusCode) {
        //Login was successful.
    }

    @Override
    public void onLoginFailed(int statusCode) {
        //Login failed.
    }
});

📘

Nota

También es posible iniciar la sesión de Clip desde la pantalla de Ajustes.

Cerrar la sesión de Clip

Desde tu aplicación, puedes solicitar cerrar la sesión de Clip.

Para cerrar la sesión de Clip desde la aplicación, implementa la siguiente función:

ClipApi.logout(object : LogoutListener{
  override fun onLogoutSuccess() {
    // Logout was successful
  }

  override fun onLogoutError(errorCode: StatusCode.ClipError) {
    // Logout failed
  }

ClipApi.logout(new LogoutListener() {
  @Override
  public void onLogoutSuccess() {
    // Logout was successful
  }

  @Override
  public void onLogoutError(@NotNull StatusCode.ClipError clipError) {
    // Logout failed
  }
});

📘

Nota

También es posible cerrar la sesión de Clip desde la pantalla de Ajustes.

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para iniciar y cerrar la sesión de Clip en tu proyecto.

El objeto ClipPayment

Crear un objeto de pago

Para integrar la función de pagos con tarjeta usando el Clip Plus, se requiere:

• Crear un objeto de pago en la aplicación
• Agregar un listener para el botón o elemento gráfico de pago en tu aplicación

Para crear un objeto de pago, implementa la siguiente función:

val clipPayment = ClipPayment.Builder()
                .amount(amount: BigDecimal)
                .enableContactless(enabled: Boolean)
                .enableTips(enabled: Boolean)
                .roundTips(round: Boolean)
                .enablePayWithPoints(enabled: Boolean)
                .customTransactionId(customTransactionId: String?)
                .build()

ClipPayment clipPayment = new ClipPayment.Builder()
               .amount(BigDecimal: amount)
               .enableContactless(boolean enabled)
               .enabledTips(boolean enabled)
               .roundTips(boolean round)
               .enablePayWithPoints(boolean enabled)
               .customTransactionId(String customTransactionId)
               .build();

La siguiente tabla incluye una descripción para los elementos del objeto ClipPayment:

En el listener del botón de pago de tu aplicación, agrega la siguiente función:

ClipApi.launchPaymentActivity(activity: Activity, payment: ClipPayment, requestCode: Int)

ClipApi.launchPaymentActivity(Activity activity, ClipPayment payment, int requestCode);

El resultado de una transacción será recibido en el método onActivityResult() del Activity que invocó el método de pago.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    when (requestCode) {
        REQUEST_CODE_PAYMENT -> {
            when (data?.getIntExtra(StatusCode.RESULT_CODE, StatusCode.FAILURE)) {
                StatusCode.SUCCESSFUL -> {
                    val transactionResult = data.getParcelableExtra<ClipTransaction>(StatusCode.RESULT_PAYMENT_DATA)
                    // Transaction succeeded
                }
                StatusCode.FAILURE -> {
                    // Transaction failed
                }
            }
        }

        else -> super.onActivityResult(requestCode, resultCode, data)
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    String content;
    if (requestCode == REQUEST_CODE_PAYMENT) {
        case REQUEST_CODE_PAYMENT_RESULT :
        switch(data.getIntExtra(StatusCode.RESULT_CODE, StatusCode.FAILURE)) {
            case StatusCode . SUCCESSFUL :
            ClipTransaction transactionResult = data . getParcelableExtra (StatusCode.RESULT_PAYMENT_DATA);
            // Transaction succeeded
            break;
            case StatusCode . FAILURE :
            int errorCode = data . getIntExtra (StatusCode.RESULT_ERROR, -1);
            String errorCodeDesc = data . getStringExtra (StatusCode.RESULT_ERROR_DESC);
            String messageError = data . getStringExtra (StatusCode.RESULT_ERROR_MESSAGE);
            // Transaction failed
            break;
        }
    } else {
        super.onActivityResult(requestCode, resultCode, data);
    }
}

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para recibir un pago con tarjeta en tu proyecto.

Restringir pagos con ciertos tipos de tarjetas

El SDK de Clip permite especificar una lista de números BIN (Número de Identificación Bancario, por sus siglas en inglés) restringidos de las tarjetas de las que no se desea recibir pagos. El número BIN son los primeros seis dígitos de una tarjeta.

📘

Nota

La función de restringir pagos por número BIN sólo es compatible con pagos con tarjeta swipe y chip. No es compatible para pagos en modo contactless.

Para proporcionar esta lista restringida al SDK, primero es necesario crear una lista de objetos del tipo CardBin cuyo único parámetro es un String que contiene el BIN de la tarjeta:

val listOfBins = listOf(CardBin(“XXXXXX”), CardBin(“XXXXXX”))

List<CardBin> listOfBins = Arrays.asList(CardBin(“XXXXXX”), CardBin(“XXXXXX”));

📘

Nota

El regex que se valida es: ^\d{0,6}$
De no cumplir con el formato especificado, se regresará una excepción de tipo: InvalidParameterFormat.

Ya que se creó y envió la lista, es necesario llamar a la función ClipApi.setCardBinRestriction() y pasar como parámetro la lista creada:

ClipApi.setCardBinRestriction(restrictionType: RestrictionType, listOfBins: List<CardBin>)

ClipApi.setCardBinRestriction(RestrictionType restrictionType, List<CardBin> listOfBins);

La siguiente tabla incluye una descripción para el objeto RestrictionType:

📘

Nota

Es necesario crear y enviar la lista de números restringidos antes de iniciar una transacción.

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para restringir pagos a ciertas tarjetas en tu proyecto.

Obtener el historial de transacciones

El SDK de Clip permite obtener el historial de transacciones que se han realizado.

Las funciones disponibles para trabajar con el historial son las siguientes:

• search(): permite realizar una búsqueda de transacciones del mismo día y aplicar distintos filtros.
• detail(): muestra detalles para una transacción individual.
• refund(): realiza el reembolso de una transacción.

La siguiente tabla muestra los elementos en el objeto de respuesta ClipTransaction que regresan las funciones anteriores:

Buscar transacciones en el historial

Implementa la siguiente función para buscar transacciones en el historial:

ClipHistory.search(SearchParamsRequest.byDate(date: Date, page: Int), object : ClipHistoryListener.OnSearchSuccessListener {
                override fun onSearchSuccess(response: List<ClipTransaction>?) {
                }
            }, , object : ClipHistoryListener.OnErrorListener {
                override fun onError(error: StatusCode.ClipError) {
                }
            })

ClipHistory.search(SearchParamsRequest.byDate(Date date, int page), new ClipHistoryListener.OnSearchSuccessListener() {
            @Override
            public void onSearchSuccess(@Nullable List<ClipTransaction> list) {
            }
        }, new ClipHistoryListener.OnErrorListener() {
            @Override
            public void onError(@NotNull StatusCode.ClipError clipError) {
            }
        });

La siguiente tabla incluye una descripción para los parámetros de la función:

CardNumber: El objeto CardNumber está compuesto por los últimos 4 dígitos que aparecen en la tarjeta.

ReceiptNumber: El objeto ReceiptNumber representa el número de recibo generado por Clip al concluir una transacción de manera exitosa.

Mostrar los detalles de una transacción

Implementa la siguiente función para mostrar los detalles de una transacción en específico:

ClipHistory.detail(receiptNumber: ReceiptNumber, object : ClipListener<ClipTransaction?> {
     override fun onCompleteListener(response: ClipTransaction?, error: StatusCode.ClipError?) {}
})

ClipHistory.detail(ReceiptNumber receiptNumber, new ClipListener<ClipTransaction?>() {
            @Override
            public void onCompleteListener(@Nullable ClipTransaction clipTransaction, @Nullable StatusCode.ClipError error) {
            }
        });

La siguiente tabla incluye una descripción para los parámetros de la función:

Realizar una devolución de transacción

Implementa la siguiente función para realizar una devolución de transacción en específico:

ClipRefund.refund(receiptNumber: ReceiptNumber, object : ClipListener<Boolean> {
                override fun onCompleteListener(response: Boolean, error: StatusCode.ClipError?) {}})

ClipRefund.refund(ReceiptNumber receiptNumber, new ClipHistoryListener<Boolean>() {
            @Override
            public void onCompleteListener(boolean response, @Nullable StatusCode.ClipError error) {
            }
        }});

La siguiente tabla incluye una descripción para los parámetros de la función:

Configurar los ajustes del dispositivo

La librería de Clip permite configurar ciertos ajustes del dispositivo desde tu aplicación de Android.

Actualmente, los ajustes de configuración que se pueden consultar son:

• Batería: muestra el nivel de batería en el dispositivo Clip.
• Firmware: muestra la versión de firmware instalada en el dispositivo Clip.
• Tiempo de apagado: permite configurar el tiempo de apagado automático en tu Clip Plus 2 para ahorrar batería.
• Sesión de Clip: la sección de ajustes permite cerrar sesión en la cuenta Clip.
• Lector conectado: permite conectar o desconectar un lector Clip por medio de conexión Bluetooth.

📘

Nota

La configuración de Tiempo de apagado solo está disponible para el dispositivo Clip Plus 2.

Para agregar la función de configuración de ajustes, en el listener del botón tu aplicación Android, agrega la siguiente función:

ClipApi.showSettingsActivity(activity: Activity, loginEnabled: Boolean, logoutEnabled: Boolean, requestCode: Integer)

ClipApi.showSettingsActivity(Activity activity, boolean loginEnabled, boolean logoutEnabled, requestCode: Integer);

La siguiente tabla incluye una descripción para los parámetros de la función:

Pagos a distancia

El SDK de Clip permite que con tu propia aplicación de Android generes enlaces para pagos a distancia.

Esta sección incluye cómo implementar las siguientes funciones:

• Crear un enlace para pago a distancia
• Consultar el historial y realizar búsquedas
• Consultar detalles individuales de un pago a distancia
• Cancelar un enlace de pago a distancia

Crear un pago a distancia

Para poder generar un URL de pago a distancia, es necesario llamar a la siguiente función:

ClipApi.launchRemotePaymentActivity(activity: Activity, amount: BigDecimal, requestCode: Int)

ClipApi.launchRemotePaymentActivity(Activity activity, BigDecimal amount, int requestCode);

📘

Nota:

Esta función valida que el formato de la cantidad sea de máximo 5 cifras y 2 decimales. Cualquier cantidad mayor a 99999.99 regresa un código de error 12005.

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para crear un enlace de pago a distancia en tu proyecto.

Consultar el historial de pagos a distancia

Para agregar la función de historial de pagos a tu aplicación, el primer paso es crear un objeto con el tipo de filtro que se desea aplicar.

Los diferentes tipos de búsqueda que incluye este método son:

• Fecha
• Rango de fechas
• Cantidad
• Correo electrónico del cliente
• Código de enlace de pago

Para buscar por cantidad del enlace de pago:

val query = SearchParamsRequest.byAmount(amount: String, page: Int)

Map<String, String> query = SearchParamsRequest.byAmount(String amount, int page);

Para buscar por dirección de correo electrónico del cliente:

val query = SearchParamsRequest.byCustomerEmail(customerEmail: String, page: Int)

Map<String, String> query = SearchParamsRequest.byCustomerEmail(String customerEmail, int page);

Para buscar por fecha:

val query = SearchParamsRequest.byDate(date: Calendar, page: Int)

Map<String, String> query = SearchParamsRequest.byDate(Calendar date, int page);

Para buscar por rango de fechas:

val query = SearchParamsRequest.byDateRange(dateFrom: Calendar, dateTo: Calendar, page: Int)

Map<String, String> query = SearchParamsRequest.byDateRange(Calendar dateFrom, Calendar dateTo, int page);

Para buscar por código del enlace de pago:

val query = SearchParamsRequest.byRequestNumber(requestCode: String, page: Int)

Map<String, String> query = SearchParamsRequest.byRequestNumber(String requestCode, int page);

Implementar el método de búsqueda:

Después de crear el método con el tipo o tipos de búsqueda a integrar en tu aplicación, agrega el método de búsqueda general.

Para agregar la función de historial de pagos a tu aplicación, implementa el siguiente método:

ClipRemotePayment.search(searchQuery: SearchQuery, object : ClipListener<RemotePaymentHistoryResponse?> {
    override fun onCompleteListener(response: RemotePaymentHistoryResponse?, error: StatusCode.ClipError?) {

    }

    })

ClipRemotePayment.search(Map<String, String> searchQuery, new ClipListener<RemotePaymentHistoryResponse?>() {
    @Override
    public void onCompleteListener(@Nullable RemotePaymentHistoryResponse response, StatusCode.ClipError error) {

    }
});

Filtrar el historial de pagos a distancia por estado de la transacción:

Adicionalmente, la lista de resultados del historial de pagos a distancia permite filtrar por estado de la transacción.

Los estados de transacción que puede tener un pago a distancia son:

• PENDING: estado pendiente de la transacción desde el momento de su creación hasta que se realiza el pago. Una transacción con estado pendiente tiene un tiempo de expiración de 72 horas.
• PAID: el pago a distancia ha sido completado de forma exitosa.
• CANCELLED: el pago a distancia fue cancelado antes de realizar el pago.
• OVERDUE: el pago no se completó dentro de las 72 horas de validez.
• REFUNDED: el pago fue reembolsado.

Para integrar el filtro por estado de transacción, crea el siguiente objeto:

val query = SearchParamsRequest.byStatus(status: RemotePaymentFilter, page: Int)

Map<String, String> query = SearchParamsRequest.byStatus(RemotePaymentFilter status, int page);

Los códigos de estado que actúan como parámetro son:

• RemotePaymentFilter.PENDING: 0
• RemotePaymentFilter.PAID: 1
• RemotePaymentFilter.CANCELLED: 2
• RemotePaymentFilter.OVERDUE: 3
• RemotePaymentFilter.REFUNDED: 4

La siguiente tabla describe los elementos que regresa la función en el objeto de respuesta RemotePaymentHistoryResponse:

Consultar los detalles de un pago a distancia

Se consultan los detalles de una transacción por medio del identificador Request Code.

Para consultar los detalles de la transacción, agrega la siguiente función:

ClipRemotePayment.detail(requestCode: String, object : ClipListener<RemotePaymentDetailResponse?>{
    override fun onCompleteListener(response: RemotePaymentDetailResponse, error: StatusCode.ClipError?) {

    }

})

ClipRemotePayment.detail(String requestCode, new ClipListener<RemotePaymentDetailResponse>(){
    @Override
    public void onSuccess(@Nullable RemotePaymentDetailResponse response, @Nullable StatusCode.ClipError error) {

    }

});

La siguiente tabla describe los elementos que regresa la función en el objeto de respuesta RemotePaymentDetailResponse:

Cancelar un pago a distancia

La librería del SDK de Clip permite cancelar un URL de pago a distancia antes de que se haya completado el pago.

La solicitud de un pago a distancia se identifica por un Request Code.

Para cancelar un pago a distancia, agrega la siguiente función:

ClipRemotePayment.cancel(requestCode: RequestCode, object : ClipListener<RemotePaymentDetailResponse?>{
    override fun onCompleteListener(response: RemotePaymentDetailResponse?, error: StatusCode.ClipError?) {
        
    }

})

ClipRemotePayment.cancel(RequestCode requestCode, new ClipListener<RemotePaymentDetailResponse>() {
    @Override
    public void onCompleteListener(@Nullable RemotePaymentDetailResponse response, @Nullable StatusCode.ClipError error) {
        
    }

});