Guia de Integración de SDK Contactless

1. Guía de Integración del SDK

Bienvenido a la Guía de Integración del SDK. Este documento le ayudará a integrar el SDK en su proyecto y ponerlo en marcha. Siga los pasos a continuación para garantizar una integración fluida.

1.1 Requisitos previos

Android Studio (o su IDE preferido) instalado.
SDK AAR del proveedor.
VISA SENSORY BRANDING AAR; este archivo se encuentra en el directorio /libs del proyecto de demostración.
Android 8.0 o superior para la versión de destino de la aplicación. El dispositivo DEBE tener un lector NFC.

1.2 Configuración del proyecto y uso

Paso 1: Agregar el SDK a la dependencia de Gradle de su proyecto

Agregue las siguientes líneas a su archivo build.gradle:

groovy

dependencies {

    /**
     * SDK FTT and VISA
     *
     * Both are required to use the SDK
     */
    api files('libs/aggressive_protected_2_0_81_ftcontactlesslib_release_develop_with_pin_SANDBOX.aar')
    api files('libs/VisaSensoryBranding.aar')

    // Necessary dependencies for the SDK
    implementation group: 'com.google.android.gms', name: 'play-services-base', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-safetynet', version: '16.0.0'
    implementation group: 'com.google.android.gms', name: 'play-services-tasks', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-basement', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-location', version: '17.0.0'

    implementation("com.google.android.play:integrity:1.0.2")
    implementation 'org.apache.commons:commons-lang3:3.1'
    implementation 'commons-logging:commons-logging:1.1'
    implementation 'commons-validator:commons-validator:1.6'
    implementation 'org.apache.httpcomponents.client5:httpclient5:5.0.3'
    implementation 'org.apache.httpcomponents.core5:httpcore5:5.0'
    implementation 'org.slf4j:slf4j-api:1.7.30'

    implementation 'androidx.security:security-crypto:1.1.0-alpha05'
    implementation 'com.google.crypto.tink:tink-android:1.12.0'
    implementation('com.scottyab:rootbeer-lib:0.1.1')
}

groovy

dependencies {

    /**
     * SDK FTT and VISA
     *
     * Both are required to use the SDK
     */
    api files('libs/aggressive_protected_2_0_81_ftcontactlesslib_release_develop_with_pin_SANDBOX.aar')
    api files('libs/VisaSensoryBranding.aar')

    // Necessary dependencies for the SDK
    implementation group: 'com.google.android.gms', name: 'play-services-base', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-safetynet', version: '16.0.0'
    implementation group: 'com.google.android.gms', name: 'play-services-tasks', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-basement', version: '16.0.1'
    implementation group: 'com.google.android.gms', name: 'play-services-location', version: '17.0.0'

    implementation("com.google.android.play:integrity:1.0.2")
    implementation 'org.apache.commons:commons-lang3:3.1'
    implementation 'commons-logging:commons-logging:1.1'
    implementation 'commons-validator:commons-validator:1.6'
    implementation 'org.apache.httpcomponents.client5:httpclient5:5.0.3'
    implementation 'org.apache.httpcomponents.core5:httpcore5:5.0'
    implementation 'org.slf4j:slf4j-api:1.7.30'

    implementation 'androidx.security:security-crypto:1.1.0-alpha05'
    implementation 'com.google.crypto.tink:tink-android:1.12.0'
    implementation('com.scottyab:rootbeer-lib:0.1.1')
}

Paso 2: Agregar la aplicación a los sistemas FTT mediante ATC

Es necesario compartir los siguientes campos con ACT para el registro en los sistemas FTT y así inicializar el SDK:

applicationId en el archivo build.gradle
versionName en el archivo build.gradle

Asegúrese de que estos campos estén correctamente configurados y sean accesibles para la inicialización del SDK.

Paso 3: Configurar la API de integridad de Google y Huawei SafetyDetect

Es necesario configurar la API de integridad de Google Play y Huawei SafetyDetect (si es compatible con dispositivos Huawei). Comparta las credenciales resultantes con los sistemas FTT.

Google Play Integrity API

Habilita la API
- Google Play Integrity API
- Ve a https://console.cloud.google.com/
- Selecciona o crea tu proyecto
- Ve a API y Servicios > Biblioteca
- Busca la API de Integridad de Google Play y habilítala
Obtén las credenciales JSON
- Ve a API y Servicios > Credenciales
- Crea una cuenta de servicio y asígnale el rol de usuario de Integridad de Google Play
- Descarga y comparte la clave JSON de forma segura con los sistemas FTT
Obtén el ID del proyecto
- Ve a IAM y Administración > Configuración
- Copia el ID del proyecto y compártelo

Huawei SafetyDetect API

Habilita la API de SafetyDetect en Huawei AppGallery Connect.
Genera y comparte las credenciales JSON de SafetyDetect con los sistemas FTT.

Paso 4: Inicialización del SDK

En tu MainActivity o actividad de punto de entrada, inicializa el SDK. Consulta el método initService o la aplicación de demo.

Paso 5: Incorporación del ID del dispositivo

Tras la primera inicialización del SDK, recibirá un ID del dispositivo. Este ID debe completar el proceso de incorporación para habilitar las transacciones.

Este paso es crucial para vincular el dispositivo al sistema de forma segura y habilitar las capacidades de transacción. Asegúrese de gestionar la respuesta del SDK correctamente y siga los procedimientos de incorporación requeridos, descritos con el proveedor.

Paso 6: Gestión de las devoluciones de llamada del SDK

Debe implementar métodos de devolución de llamada (callbacks) para gestionar las respuestas del SDK, como las de éxito, errores y actualizaciones de estado.

Ejemplo:

java

@Override
public void onDeviceIdResponse(String deviceId) {
    Log.i("TAG", "Device ID: " + deviceId);
    tvDeviceId.setText(deviceId);
}

java

@Override
public void onDeviceIdResponse(String deviceId) {
    Log.i("TAG", "Device ID: " + deviceId);
    tvDeviceId.setText(deviceId);
}

1.3 Solución de problemas

Si encuentra algún problema durante el proceso de integración, consulte las devoluciones de llamada del SDK a reasonText y reasonCode para la mayoría de los errores. Además, compruebe si hay excepciones generales y revise el seguimiento de la pila (stack trace) para diagnosticar posibles problemas.

Si la información de las devoluciones de llamada y el seguimiento de la pila no resuelve el problema y necesita crear un ticket de soporte, proporcione la siguiente información:

Una explicación completa de las acciones que está realizando.
La devolución de llamada realizada o la excepción general presentada.
responseCode, reasonText y seguimiento de la pila.
El número de serie del dispositivo, el ID del terminal y cualquier otro dato relevante que pueda ayudar a inspeccionar el problema.

Esto permitirá investigar el problema de forma más eficiente y ofrecer una solución más rápida.

2. Descripción de los métodos del SDK

Clase base para todos los métodos: ftContactlessManager, accedida vía ftContactlessManager.getManager().

2.1 Inicialización del SDK — `initService`

Overloads
`initService(final Activity mActivity, onContactlessReaderResponse uiResponse, PinDialogStyle pinDialogStyle, boolean supportMcMaestro)`
`initService(final Activity mActivity, onContactlessReaderResponse uiResponse, PinDialogStyle pinDialogStyle, boolean useExternalVisaSensoryBranding, long waitMillsForSensoryBranding, boolean supportMcMaestro)`
`initService(final Activity mActivity, onContactlessReaderResponse uiResponse, PinDialogStyle pinDialogStyle, boolean useHuaweiSafetyDetect, String huaweiSafetyDetectAppId, boolean useExternalVisaSensoryBranding, long waitMillsForSensoryBranding, boolean supportMcMaestro)`

Código de ejemplo:

java

ftContactlessManager.getManager().initService(MainMenuActivity.this,
    MainMenuActivity.this, pinDialogStyle, false);

java

ftContactlessManager.getManager().initService(MainMenuActivity.this,
    MainMenuActivity.this, pinDialogStyle, false);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Indica el contexto de la llamada de inicialización actual
`uiResponse`	onContactlessReaderResponse	Interfaz implementada en una clase que gestionará los callbacks del SDK
`pinDialogStyle`	PinDialogStyle	Estilo usado para el popup de solicitud de PIN en transacciones con PIN
`useHuaweiSafetyDetect`	boolean	Bandera para usar el servicio Huawei SafetyDetect (solo dispositivos Huawei)
`huaweiSafetyDetectAppId`	String	Id generado en la consola de Huawei para identificar la aplicación (usado para SafetyDetect)
`useExternalVisaSensoryBranding`	boolean	Bandera para habilitar el uso de un Visa Sensory Branding externo
`waitMillsForSensoryBranding`	long	Tiempo en milisegundos a esperar por la animación del sensory branding externo
`supportMcMaestro`	boolean	Soporte para Maestro

2.2 Realizar transacción — `doTransaction`

Overloads
`doTransaction(Activity mActivity, onContactlessReaderResponse uiResponse, double transactionAmount, CurrencyInfo transactionCurrency, int merchantDetailId)`
`doTransaction(..., int merchantDetailId, String transactionId)`
`doTransaction(..., int merchantDetailId, TransactionConfirmationMode confirmationMode)`
`doTransaction(..., int merchantDetailId, String transactionId, TransactionConfirmationMode confirmationMode)`
`doTransaction(Activity mActivity, onContactlessReaderResponse uiResponse, int merchantDetailId, double transactionAmount, CurrencyInfo transactionCurrency, int quotas, int extrafinancing, boolean isLoyaltyTransaction)`
`doTransaction(..., boolean isLoyaltyTransaction, String transactionId)`
`doTransaction(..., boolean isLoyaltyTransaction, TransactionConfirmationMode confirmationMode)`
`doTransaction(..., boolean isLoyaltyTransaction, String transactionId, TransactionConfirmationMode confirmationMode)`
`doTransaction(..., String transactionId, TransactionConfirmationMode confirmationMode, Boolean cybersourceApplyDecisionManager, CybersourceBillTo cybersourceBillTo)`

Código de ejemplo:

java

ftContactlessManager.getManager().doTransaction(activity,
    MainMenuActivity.this, transactionAmount, transactionCurrency, merchantId);

java

ftContactlessManager.getManager().doTransaction(activity,
    MainMenuActivity.this, transactionAmount, transactionCurrency, merchantId);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`transactionAmount`	double	Monto de la transacción actual
`transactionCurrency`	CurrencyInfo	Moneda de la transacción actual
`merchantDetailId`	int	Id que identifica al comercio usado en la transacción
`quotas`	int	Cuotas usadas; las cuotas permitidas se devuelven en el objeto de detalles del comercio
`extrafinancing`	int	Financiamiento extra usado; las opciones permitidas se devuelven en el objeto de detalles del comercio
`isLoyaltyTransaction`	boolean	Indica si la transacción es de fidelización, solo si el comercio lo permite
`transactionId`	String	Id de la transacción en curso
`confirmationMode`	TransactionConfirmationMode	Por defecto `AUTOMATIC_CONFIRMATION`; si se define `USER_CONFIRMATION`, la transacción espera a que se llame `transactionConfirmation`
`cybersourceBillTo`	CybersourceBillTo	Objeto opcional con información adicional para Cybersource
`cybersourceApplyDecisionManager`	boolean	Si es `TRUE`, se incluye la información de `cybersourceBillTo` en la transacción; si es `FALSE`, se ignora aunque se haya provisto

2.3 Transacción con impuesto — `doTaxTransaction`

Overloads
`doTaxTransaction(Activity mActivity, onContactlessReaderResponse uiResponse, int merchantDetailId, double transactionBaseAmount, CurrencyInfo transactionCurrency, int quotas, double transactionTaxAmount, double transactionTaxAmountDiscounted, int extrafinancing, boolean isLoyaltyTransaction)`
`doTaxTransaction(..., boolean isLoyaltyTransaction, String transactionId)`
`doTaxTransaction(..., boolean isLoyaltyTransaction, TransactionConfirmationMode confirmationMode)`
`doTaxTransaction(..., boolean isLoyaltyTransaction, String transactionId, TransactionConfirmationMode confirmationMode)`

Código de ejemplo:

java

ftContactlessManager.getManager().doTaxTransaction(activity,
    MainMenuActivity.this, merchantId, transactionBaseAmount, transactionCurrency,
    quotas, transactionTaxAmount, transactionTaxAmountDiscounted,
    extrafinancing, isLoyaltyTransaction);

java

ftContactlessManager.getManager().doTaxTransaction(activity,
    MainMenuActivity.this, merchantId, transactionBaseAmount, transactionCurrency,
    quotas, transactionTaxAmount, transactionTaxAmountDiscounted,
    extrafinancing, isLoyaltyTransaction);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`merchantDetailId`	int	Id que identifica al comercio
`transactionBaseAmount`	double	Monto base de la transacción
`transactionCurrency`	CurrencyInfo	Moneda de la transacción
`quotas`	int	Cuotas usadas
`transactionTaxAmount`	double	Monto total, `baseAmount + ISV Tax`
`transactionTaxAmountDiscounted`	double	Monto con descuento, `transactionTaxAmount − ISV discount`
`extrafinancing`	int	Financiamiento extra usado
`isLoyaltyTransaction`	boolean	Marca de transacción de fidelización
`transactionId`	String	Id de la transacción en curso
`confirmationMode`	TransactionConfirmationMode	Ver descripción en `doTransaction`

2.4 Transacción manual — `doManualTransaction`

Código de ejemplo:

java

ftContactlessManager.getManager().doManualTransaction(activity,
    MainMenuActivity.this, transactionAmount, transactionCurrency,
    selectedMerchantDetail.getId(), Pan, date, cvc, description);

java

ftContactlessManager.getManager().doManualTransaction(activity,
    MainMenuActivity.this, transactionAmount, transactionCurrency,
    selectedMerchantDetail.getId(), Pan, date, cvc, description);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`transactionAmount`	double	Monto de la transacción
`transactionCurrency`	CurrencyInfo	Moneda de la transacción
`merchantDetailId`	int	Id del comercio
`PAN`	String	Número de cuenta principal de la tarjeta
`date`	String	Fecha de vencimiento de la tarjeta
`CVC`	String	CVC de la tarjeta
`saleDescription`	String	Descripción breve de la transacción manual

2.5 Transacción manual con impuesto — `doManualTaxTransaction`

Código de ejemplo:

java

ftContactlessManager.getManager().doManualTaxTransaction(activity,
    MainMenuActivity.this, TransactionBaseAmount, TransactionCurrency(),
    selectedMerchantDetail.getId(), pan, date, cvc, description,
    TransactionTaxAmount, TransactionTaxDiscountedAmount);

java

ftContactlessManager.getManager().doManualTaxTransaction(activity,
    MainMenuActivity.this, TransactionBaseAmount, TransactionCurrency(),
    selectedMerchantDetail.getId(), pan, date, cvc, description,
    TransactionTaxAmount, TransactionTaxDiscountedAmount);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`transactionAmount`	double	Monto de la transacción
`transactionCurrency`	CurrencyInfo	Moneda de la transacción
`merchantDetailId`	int	Id del comercio
`PAN`	String	Número de cuenta principal de la tarjeta
`date`	String	Fecha de vencimiento de la tarjeta
`CVC`	String	CVC de la tarjeta
`saleDescription`	String	Descripción breve de la transacción
`transactionTaxAmount`	double	Monto total, `baseAmount + ISV Tax`
`transactionTaxAmountDiscounted`	double	Monto con descuento, `transactionTaxAmount − ISV discount`

2.6 Check-In — `doCheckInTransaction`

Código de ejemplo:

java

ftContactlessManager.getManager().doCheckInTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

java

ftContactlessManager.getManager().doCheckInTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`merchantDetailId`	int	Id del comercio
`transactionBaseAmount`	double	Monto base de la transacción
`transactionCurrency`	CurrencyInfo	Moneda de la transacción
`isTaxTransaction`	boolean	Marca de transacción con impuesto, si el comercio lo permite
`transactionTaxAmount`	double	Monto total, `baseAmount + ISV Tax`
`transactionTaxAmountDiscounted`	double	Monto con descuento
`transactionId`	String	Id de la transacción
`folioNumber`	String	Folio que identifica el check-in

2.7 Check-In — Reautorización — `doCheckInReauthorizationTransaction`

Mismos parámetros que doCheckInTransaction (ver sección 2.6).

Código de ejemplo:

java

ftContactlessManager.getManager().doCheckInReauthorizationTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

java

ftContactlessManager.getManager().doCheckInReauthorizationTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

2.8 Check-Out — `doCheckOutTransaction`

Mismos parámetros que doCheckInTransaction (ver sección 2.6).

Código de ejemplo:

java

ftContactlessManager.getManager().doCheckOutTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

java

ftContactlessManager.getManager().doCheckOutTransaction(mActivity,
    MainActivity.this, merchantDetailId, transactionBaseAmount, transactionCurrency,
    isTaxTransaction, transactionTaxAmount, transactionTaxAmountDiscounted,
    transactionId, folioNumber);

2.9 Detener transacción — `stopTransaction`

Código de ejemplo:

java

ftContactlessManager.getManager().stopTransaction(activity, MainMenuActivity.this);

java

ftContactlessManager.getManager().stopTransaction(activity, MainMenuActivity.this);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK

2.10 Enviar confirmación de transacción — `transactionConfirmation`

Overloads
`transactionConfirmation(Activity mActivity, onContactlessReaderResponse uiResponse, boolean sendTransactionAuthorization)`
`transactionConfirmation(Activity mActivity, onContactlessReaderResponse uiResponse, Boolean sendTransactionAuthorization, AdditionalTransactionInfo additionalTransactionInfo)`

Código de ejemplo:

java

ftContactlessManager.getManager().transactionConfirmation(activity,
    MainMenuActivity.this, true);

java

ftContactlessManager.getManager().transactionConfirmation(activity,
    MainMenuActivity.this, true);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`sendTransactionAuthorization`	boolean	Indica si la transacción debe enviarse al host o no (cancelada)
`additionalTransactionInfo`	AdditionalTransactionInfo	Estructura con datos adicionales requeridos para procesar la transacción

2.11 Reembolso — `doRefundTransaction`

Overloads
`doRefundTransaction(Activity mActivity, onContactlessReaderResponse uiResponse, double transactionAmount, CurrencyInfo transactionCurrency, String authorizationId, int merchantDetailId)`
`doRefundTransaction(..., int merchantDetailId, TransactionConfirmationMode confirmationMode)`

Código de ejemplo:

java

ftContactlessManager.getManager().doRefundTransaction(this.activity,
    MainMenuActivity.this, TransactionBaseAmount, TransactionCurrency,
    AuthorizationId, merchantId, transactionConfirmationMode);

java

ftContactlessManager.getManager().doRefundTransaction(this.activity,
    MainMenuActivity.this, TransactionBaseAmount, TransactionCurrency,
    AuthorizationId, merchantId, transactionConfirmationMode);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`transactionAmount`	Double	Monto de la transacción
`transactionCurrency`	CurrencyInfo	Moneda usada para el reembolso
`authorizationId`	String	Identificador de la transacción aprobada a reembolsar
`merchantDetailId`	int	Id del comercio vinculado
`transactionConfirmationMode`	TransactionConfirmationMode	Ver descripción en `doTransaction`

2.12 Enviar datos del voucher — `sendVoucherData`

Overloads
`sendVoucherData(Activity mActivity, onContactlessReaderResponse uiResponse, String signaturePath, Queue<String> userMailVoucher, String voucherComments)`
`sendVoucherData(..., String voucherComments, Boolean sendVoucherMail)`

Código de ejemplo:

java

ftContactlessManager.getManager().sendVoucherData(activity,
    MainMenuActivity.this, this.signaturePath, this.userMailVoucherQueue,
    voucherComments, true);

java

ftContactlessManager.getManager().sendVoucherData(activity,
    MainMenuActivity.this, this.signaturePath, this.userMailVoucherQueue,
    voucherComments, true);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`signaturePath`	String	Cadena con la firma del tarjetahabiente
`userMailVoucher`	Queue<String>	Cola de correos que recibirán el voucher virtual
`voucherComments`	String	Comentarios adicionales al voucher virtual
`sendVoucherData`	Boolean	Si `true`, el voucher se envía a los correos de la lista; si `false`, no se envía por email pero se almacena para que el usuario lo gestione

2.13 Historial de transacciones — `getHistoryTransactions`

Overloads
`getHistoryTransactions(Activity mActivity, onContactlessReaderResponse uiResponse)`
`getHistoryTransactions(Activity mActivity, onContactlessReaderResponse uiResponse, String invoiceRefNoOrTransactionId)`

Código de ejemplo:

java

ftContactlessManager.getManager().getHistoryTransactions(MainMenuActivity.this,
    MainMenuActivity.this);

java

ftContactlessManager.getManager().getHistoryTransactions(MainMenuActivity.this,
    MainMenuActivity.this);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`invoiceRefNoOrTransactionId`	String	Número de factura o Id de transacción para recuperar solo esa transacción

2.14 Anular transacción — `sendTransactionAnnulment`

Código de ejemplo:

java

ftContactlessManager.getManager().sendTransactionAnnulment(activity,
    MainMenuActivity.this, historyItem);

java

ftContactlessManager.getManager().sendTransactionAnnulment(activity,
    MainMenuActivity.this, historyItem);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`transaction`	HistoryItem	Objeto con todos los datos de la transacción a anular

2.15 Enviar cierre de lote — `sendSettlement`

Código de ejemplo:

java

ftContactlessManager.getManager().sendSettlement(activity, MainMenuActivity.this);

java

ftContactlessManager.getManager().sendSettlement(activity, MainMenuActivity.this);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK

2.16 Registro de usuario — `sendUserSignUp`

Código de ejemplo:

java

ftContactlessManager.getManager().sendUserSignUp(activity, MainMenuActivity.this,
    merchantDetailId, userName, userLastName, userEmail, userPhoneNumber,
    userPasswordQuestion, userPasswordAnswer);

java

ftContactlessManager.getManager().sendUserSignUp(activity, MainMenuActivity.this,
    merchantDetailId, userName, userLastName, userEmail, userPhoneNumber,
    userPasswordQuestion, userPasswordAnswer);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`merchantDetailId`	int	Id del comercio vinculado con el usuario a crear
`userName`	String	Nombre del usuario a crear
`userLastName`	String	Apellido del usuario a crear
`userEmail`	String	Correo del usuario a crear
`userPhone`	String	Teléfono del usuario a crear
`userQuestion`	String	Pregunta de seguridad para recuperar la contraseña
`userAnswer`	String	Respuesta a la pregunta de seguridad

2.17 Alta rápida de comercio — `sendMerchantRapidOnBoard`

Código de ejemplo:

java

ftContactlessManager.getManager().sendMerchantRapidOnBoard(MainMenuActivity.this, robData);

java

ftContactlessManager.getManager().sendMerchantRapidOnBoard(MainMenuActivity.this, robData);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK
`robData`	RapidOnBoardingData	Datos del alta rápida del comercio

2.18 Obtener Id del dispositivo — `getDeviceId`

Código de ejemplo:

java

ftContactlessManager.getManager().getDeviceId(MainMenuActivity.this, MainMenuActivity.this);

java

ftContactlessManager.getManager().getDeviceId(MainMenuActivity.this, MainMenuActivity.this);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Contexto de la llamada actual
`uiResponse`	onContactlessReaderResponse	Interfaz de gestión de callbacks del SDK

2.19 Obtener versión del SDK — `getCoreVersion`

Código de ejemplo:

java

ftContactlessManager.getManager().getCoreVersion();

java

ftContactlessManager.getManager().getCoreVersion();

No requiere parámetros.

2.20 Mostrar Visa Sensory Branding — `showVisaSensoryBranding`

Código de ejemplo:

java

ftContactlessManager.getManager().showVisaSensoryBranding(mActivity, onSensoryComplete);

java

ftContactlessManager.getManager().showVisaSensoryBranding(mActivity, onSensoryComplete);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Activity actual
`onSensoryComplete`	onSensoryBrandingComplete	Interfaz con el método `onComplete`, invocado al finalizar el splash de Visa

2.21 Mostrar Mastercard Sensory Branding — `showMastercardSensoryBranding`

Código de ejemplo:

java

ftContactlessManager.getManager().showMastercardSensoryBranding(mActivity, onSensoryComplete);

java

ftContactlessManager.getManager().showMastercardSensoryBranding(mActivity, onSensoryComplete);

Parámetro	Tipo	Descripción
`mActivity`	Activity	Activity actual
`onSensoryComplete`	onSensoryBrandingComplete	Interfaz con el método `onComplete`, invocado al finalizar el splash de Mastercard

3. Descripción de la interfaz de callback UI (`onContactlessReaderResponse`)

Todos los métodos siguientes forman parte de la interfaz onContactlessReaderResponse, que la aplicación cliente debe implementar para recibir las respuestas asíncronas del SDK.

Método	Descripción
`onProcessingCommand()`	Se invoca mientras el SDK está procesando un comando.
`onConnectingService()`	Se invoca cuando el SDK envía la autenticación al host y descarga la configuración del dispositivo (IMEI).
`onServiceConnected(TerminalData terminalData)`	Se invoca cuando el host responde con la configuración del dispositivo. Devuelve un objeto `TerminalData`.
`onCouldNotConnectService(String reason, String responseCode)`	Se invoca si el mensaje de autenticación no pudo enviarse al host.
`onCouldNotValidateIntegrity(String message)`	Se invoca si la validación de integridad determina que el dispositivo no es seguro (rooteado o SO modificado).
`onPresentCardRequest()`	Se invoca tras llamar a `doTransaction`, indicando que debe acercarse la tarjeta al lector NFC.
`onReadingCardData()`	Se invoca cuando la tarjeta ha sido tocada y se está leyendo.
`onReturnCurrentTransactionInfo(CurrentTransactionInfo currentTransactionInfo, TransactionConfirmationMode confirmationMode)`	Se invoca tras leer la tarjeta, con datos como el monto y el nombre del tarjetahabiente. Debe seguirse con `transactionConfirmation`.
`onSendingTransactionAuthorization()`	Se invoca cuando el SDK envía la autorización de la transacción actual.
`onSendingTransactionRefundAuthorization()`	Se invoca cuando el SDK envía la autorización de un reembolso.
`onSendingCheckInTransactionAuthorization()`	Se invoca cuando el SDK envía la autorización de un check-in.
`onSendingCheckOutTransactionAuthorization()`	Se invoca cuando el SDK envía la autorización de un check-out.
`onStoringOfflineAuthorizedTransaction()`	Se invoca cuando el host pierde conexión y el SDK guarda la transacción autorizada localmente.
`onTransactionCancelled()`	Se invoca cuando la transacción ha sido cancelada.
`onVoucherDataResponse(VoucherData voucherData)`	Se invoca cuando el host responde y la transacción es aprobada; incluye los datos del voucher.
`onVoucherSent()`	Se invoca cuando el voucher de la transacción ha sido enviado al host.
`onHistoryTransactionsResponse(TransactionsHistory transactionsHistory)`	Se invoca tras llamar a `getHistoryTransactions`, con el historial de transacciones no liquidadas.
`onSettlementResponse(boolean settlementComplete, String resultMessage)`	Se invoca tras llamar a `sendSettlement`, con el estado del cierre de lote.
`onSignUpUserResponse(boolean userCreated, String resultMessage, String usernameResult, String userEmail, String passwordResult)`	Se invoca tras llamar a `sendUserSignUp`, con el resultado de la creación del usuario.
`onNFCStateOff()`	Se invoca si, al llamar `doTransaction`, se detecta que el NFC está apagado.
`onDeviceIdResponse(String deviceId)`	Se invoca tras llamar a `getDeviceId`, devolviendo el identificador del dispositivo.
`onNewDeviceIdResponse(String deviceId)`	Se invoca con el identificador del dispositivo tras recibir la configuración del host.
`onGeneralException(GeneralException exception, String msg)`	Se invoca si falla una validación interna o el procesamiento de un comando.
`onGeneralSecurityException(GeneralSecurityException exception)`	Se invoca si falla una validación de seguridad interna del dispositivo.
`onTransactionConfirmed(boolean sendCurrentTransaction, TransactionConfirmationMode confirmationModeUsed)`	Se invoca al confirmarse la transacción, sea de forma automática o por confirmación de usuario.
`onStartingAutomaticReversal()`	Se invoca cuando la transacción va a revertirse por motivos de seguridad.
`onAutomaticReversalResponse(boolean transactionReversed, String resultMessage, String retrievalRefNo, String systemTraceNo)`	Se invoca cuando la transacción ha sido revertida por motivos de seguridad.

Detalle de parámetros relevantes

Callback	Parámetro	Tipo	Descripción
`onServiceConnected`	`terminalData`	TerminalData	Configuración del dispositivo actual (IMEI)
`onCouldNotConnectService`	`reason`	String	Descripción breve del problema
`onCouldNotConnectService`	`responseCode`	String	Código de respuesta de la solicitud `initService`
`onCouldNotValidateIntegrity`	`message`	String	Descripción breve del problema de integridad
`onReturnCurrentTransactionInfo`	`currentTransactionInfo`	CurrentTransactionInfo	Campos específicos de la transacción actual
`onReturnCurrentTransactionInfo`	`confirmationMode`	TransactionConfirmationMode	Indica si la confirmación es automática o manual
`onVoucherDataResponse`	`voucherData`	VoucherData	Datos del voucher, incluyendo el Id de autorización
`onHistoryTransactionsResponse`	`transactionsHistory`	TransactionsHistory	Historial de transacciones no liquidadas
`onSettlementResponse`	`settlementComplete`	boolean	`true` si se procesó correctamente, `false` si no
`onSettlementResponse`	`resultMessage`	String	Descripción del estado del cierre
`onSignUpUserResponse`	`userCreated`	boolean	Resultado del comando de creación de usuario
`onSignUpUserResponse`	`resultMessage`	String	Descripción del resultado
`onSignUpUserResponse`	`usernameResult`	String	Nombre de usuario creado
`onSignUpUserResponse`	`userEmail`	String	Correo usado para crear el usuario
`onSignUpUserResponse`	`passwordResult`	String	Contraseña temporal generada por el host
`onDeviceIdResponse` / `onNewDeviceIdResponse`	`deviceId`	String	Identificador del dispositivo actual
`onGeneralException`	`exception`	GeneralException	Enum que describe la excepción
`onGeneralException`	`msg`	String	Mensaje descriptivo de la excepción
`onGeneralSecurityException`	`exception`	GeneralSecurityException	Enum que describe la excepción de seguridad
`onTransactionConfirmed`	`sendCurrentTransaction`	boolean	`true` si la transacción fue confirmada, `false` si no
`onTransactionConfirmed`	`confirmationModeUsed`	TransactionConfirmationMode	Modo de confirmación utilizado
`onAutomaticReversalResponse`	`transactionReversed`	boolean	`true` si la transacción fue revertida
`onAutomaticReversalResponse`	`resultMessage`	String	Indica si la transacción fue revertida o no
`onAutomaticReversalResponse`	`retrievalRefNo`	String	Número de referencia de recuperación de la transacción
`onAutomaticReversalResponse`	`systemTraceNo`	String	Número de rastreo del sistema de la transacción

4. Diagramas generales del SDK

4.1 Proceso de inicialización del SDK

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call initService
    SDK->>Backend: 2. Validate Device Integrity y retrieve merchant Data (request)
    Backend-->>SDK: 2. Respuesta de validación
    SDK-->>App: 3. onDeviceIdResponse (siempre)
    SDK-->>App: 3. onConnectingService (siempre)
    SDK--)App: 3. onGeneralException (si aplica)
    SDK--)App: 3. onCouldNotValidateIntegrity (si aplica)
    SDK--)App: 3. onServiceConnected (si aplica)
    SDK--)App: 3. onCouldNotConnectService (si aplica)

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call initService
    SDK->>Backend: 2. Validate Device Integrity y retrieve merchant Data (request)
    Backend-->>SDK: 2. Respuesta de validación
    SDK-->>App: 3. onDeviceIdResponse (siempre)
    SDK-->>App: 3. onConnectingService (siempre)
    SDK--)App: 3. onGeneralException (si aplica)
    SDK--)App: 3. onCouldNotValidateIntegrity (si aplica)
    SDK--)App: 3. onServiceConnected (si aplica)
    SDK--)App: 3. onCouldNotConnectService (si aplica)

Pasos del proceso de inicialización:

ftContactlessManager.getManager().initService debe llamarse antes que cualquier otro método del SDK; inicializa toda la información requerida.
El SDK se conecta al backend para validar la integridad del dispositivo actual y recuperar la información del comercio asociada al serial de la aplicación.
Cualquiera de los siguientes callbacks puede ser invocado por el SDK hacia la UI:
- onDeviceIdResponse: devuelve el serial de la aplicación actual; se ejecuta siempre tras llamar a initService.
- onConnectingService: indica que el SDK se está conectando con el backend.
- onGeneralException: si se detecta algún problema interno, indica la descripción del mismo.
- onCouldNotValidateIntegrity: si la validación de integridad determina que el dispositivo no es seguro.
- onServiceConnected: se ejecuta al completarse la inicialización; el SDK devuelve un objeto TerminalData con los datos del comercio.
- onCouldNotConnectService: si hay algún problema de comunicación con el backend.

4.2 Proceso de `doTransaction`

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call doTransaction
    SDK--)App: 2. onGeneralException (si aplica)
    SDK--)App: 2. onNFCStateOff (si aplica)
    SDK--)App: 2. onProcessingCommand (si aplica)
    SDK--)App: 2. onPresentCardRequest (si aplica)
    Card->>SDK: 3. Usuario acerca la tarjeta
    SDK-->>App: 4. onReadingCardData
    SDK-->>App: 5. onUserCardPinRequest
    SDK--)App: 6. onUserCardPinCanceled (si aplica)
    SDK--)App: 7. onTransactionCancelled (si aplica)
    SDK-->>App: 8. onReturnCurrentTransactionInfo
    SDK-->>App: 9. onTransactionConfirmed
    SDK->>Backend: 10. Procesa la transacción
    Backend-->>SDK: 10. Resultado del procesamiento
    SDK-->>App: 11. onSendingTransactionAuthorization
    SDK-->>App: 12. onVoucherDataResponse
    App->>SDK: 13. Call sendVoucherData
    SDK-->>App: 14. onVoucherSent

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call doTransaction
    SDK--)App: 2. onGeneralException (si aplica)
    SDK--)App: 2. onNFCStateOff (si aplica)
    SDK--)App: 2. onProcessingCommand (si aplica)
    SDK--)App: 2. onPresentCardRequest (si aplica)
    Card->>SDK: 3. Usuario acerca la tarjeta
    SDK-->>App: 4. onReadingCardData
    SDK-->>App: 5. onUserCardPinRequest
    SDK--)App: 6. onUserCardPinCanceled (si aplica)
    SDK--)App: 7. onTransactionCancelled (si aplica)
    SDK-->>App: 8. onReturnCurrentTransactionInfo
    SDK-->>App: 9. onTransactionConfirmed
    SDK->>Backend: 10. Procesa la transacción
    Backend-->>SDK: 10. Resultado del procesamiento
    SDK-->>App: 11. onSendingTransactionAuthorization
    SDK-->>App: 12. onVoucherDataResponse
    App->>SDK: 13. Call sendVoucherData
    SDK-->>App: 14. onVoucherSent

Pasos del proceso doTransaction:

Para iniciar un nuevo proceso de transacción, la UI debe llamar a doTransaction.
La UI puede recibir, según corresponda:
- onGeneralException: problema interno detectado, con su descripción.
- onNFCStateOff: el NFC está apagado; debe encenderse para procesar la transacción.
- onProcessingCommand: la transacción está en progreso.
- onPresentCardRequest: el SDK indica que la tarjeta puede acercarse al lector NFC del dispositivo.
El usuario acerca la tarjeta al dispositivo.
onReadingCardData: una vez tocada la tarjeta, el SDK indica que la lectura está en progreso.
onUserCardPinRequest: la transacción actual requiere ingreso de PIN; el SDK muestra el diálogo correspondiente.
onUserCardPinCanceled: si se cancela el ingreso de PIN o el SDK pasa a segundo plano.
onTransactionCancelled: si la transacción fue detenida con el comando stopTransaction.
onReturnCurrentTransactionInfo: al completarse la lectura de la tarjeta, el SDK devuelve datos de la transacción en curso.
onTransactionConfirmed: antes de enviar la transacción al backend para solicitar autorización.
El SDK envía el paquete de la transacción al backend solicitando autorización, y recibe el resultado.
onSendingTransactionAuthorization: indica que la transacción ya fue enviada.
onVoucherDataResponse: al recibir la respuesta, el SDK la traslada a la UI mediante este callback.
Desde la UI debe llamarse al método sendVoucherData.
onVoucherSent: confirma que el voucher fue enviado.

4.3 Proceso de `getHistoryTransactions`

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call getHistoryTransactions
    SDK--)App: 2. onGeneralException (si aplica)
    SDK-->>App: 3. onProcessingCommand
    SDK->>Backend: 4. Procesa la transacción
    Backend-->>SDK: 4. Resultado del procesamiento
    SDK-->>App: 5. onHistoryTransactionsResponse

mermaid

sequenceDiagram
    participant App as Client Application
    participant Card as CardHolder
    participant SDK as T2P SDK
    participant Backend as FTT Backend

    App->>SDK: 1. Call getHistoryTransactions
    SDK--)App: 2. onGeneralException (si aplica)
    SDK-->>App: 3. onProcessingCommand
    SDK->>Backend: 4. Procesa la transacción
    Backend-->>SDK: 4. Resultado del procesamiento
    SDK-->>App: 5. onHistoryTransactionsResponse

Pasos del proceso getHistoryTransactions:

Debe llamarse al método getHistoryTransactions.
onGeneralException: si se detecta algún problema durante el proceso.
onProcessingCommand: indica que el comando está siendo procesado.
El SDK envía un comando al backend para recuperar todas las transacciones actuales no liquidadas.
onHistoryTransactionsResponse: mediante este callback, el SDK devuelve a la UI toda la información recuperada.

En esta página

Guia de Integración de SDK Contactless

Guia de Integración de SDK Contactless

1. Guía de Integración del SDK

1.1 Requisitos previos

1.2 Configuración del proyecto y uso

Paso 1: Agregar el SDK a la dependencia de Gradle de su proyecto

Paso 2: Agregar la aplicación a los sistemas FTT mediante ATC

Paso 3: Configurar la API de integridad de Google y Huawei SafetyDetect

Paso 4: Inicialización del SDK

Paso 5: Incorporación del ID del dispositivo

Paso 6: Gestión de las devoluciones de llamada del SDK

1.3 Solución de problemas

2. Descripción de los métodos del SDK

2.1 Inicialización del SDK — initService

2.2 Realizar transacción — doTransaction

2.3 Transacción con impuesto — doTaxTransaction

2.4 Transacción manual — doManualTransaction

2.5 Transacción manual con impuesto — doManualTaxTransaction

2.6 Check-In — doCheckInTransaction

2.7 Check-In — Reautorización — doCheckInReauthorizationTransaction

2.8 Check-Out — doCheckOutTransaction

2.9 Detener transacción — stopTransaction

2.10 Enviar confirmación de transacción — transactionConfirmation

2.11 Reembolso — doRefundTransaction

2.12 Enviar datos del voucher — sendVoucherData

2.13 Historial de transacciones — getHistoryTransactions

2.14 Anular transacción — sendTransactionAnnulment

2.15 Enviar cierre de lote — sendSettlement

2.16 Registro de usuario — sendUserSignUp

2.17 Alta rápida de comercio — sendMerchantRapidOnBoard

2.18 Obtener Id del dispositivo — getDeviceId

2.19 Obtener versión del SDK — getCoreVersion

2.20 Mostrar Visa Sensory Branding — showVisaSensoryBranding

2.21 Mostrar Mastercard Sensory Branding — showMastercardSensoryBranding

3. Descripción de la interfaz de callback UI (onContactlessReaderResponse)

Detalle de parámetros relevantes

4. Diagramas generales del SDK

4.1 Proceso de inicialización del SDK

4.2 Proceso de doTransaction

4.3 Proceso de getHistoryTransactions

2.1 Inicialización del SDK — `initService`

2.2 Realizar transacción — `doTransaction`

2.3 Transacción con impuesto — `doTaxTransaction`

2.4 Transacción manual — `doManualTransaction`

2.5 Transacción manual con impuesto — `doManualTaxTransaction`

2.6 Check-In — `doCheckInTransaction`

2.7 Check-In — Reautorización — `doCheckInReauthorizationTransaction`

2.8 Check-Out — `doCheckOutTransaction`

2.9 Detener transacción — `stopTransaction`

2.10 Enviar confirmación de transacción — `transactionConfirmation`

2.11 Reembolso — `doRefundTransaction`

2.12 Enviar datos del voucher — `sendVoucherData`

2.13 Historial de transacciones — `getHistoryTransactions`

2.14 Anular transacción — `sendTransactionAnnulment`

2.15 Enviar cierre de lote — `sendSettlement`

2.16 Registro de usuario — `sendUserSignUp`

2.17 Alta rápida de comercio — `sendMerchantRapidOnBoard`

2.18 Obtener Id del dispositivo — `getDeviceId`

2.19 Obtener versión del SDK — `getCoreVersion`

2.20 Mostrar Visa Sensory Branding — `showVisaSensoryBranding`

2.21 Mostrar Mastercard Sensory Branding — `showMastercardSensoryBranding`

3. Descripción de la interfaz de callback UI (`onContactlessReaderResponse`)

4.2 Proceso de `doTransaction`

4.3 Proceso de `getHistoryTransactions`