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
/libsdel 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:
applicationIden el archivobuild.gradleversionNameen el archivobuild.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,reasonTexty 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íaftContactlessManager.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().initServicedebe 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 ainitService.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 objetoTerminalDatacon 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. onVoucherSentmermaid
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. onVoucherSentPasos 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 comandostopTransaction.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. onHistoryTransactionsResponsemermaid
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. onHistoryTransactionsResponsePasos 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