Saltar al contenido principal
Migo Docs

Instalación del SDK

Tap to Phone se entrega como un SDK de Android que tu app embebe. El SDK usa el lector NFC del teléfono para leer la tarjeta presente, habla con la plataforma de Migo para crear y liquidar el cobro, y expone todo el ciclo de la transacción a través de callbacks — no se requiere hardware POS dedicado. El punto de entrada es el objeto migoSDK (paquete com.migo.sdkmigo.presentation).

:::info Requisitos del dispositivo El SDK es solo para Android (minSdk 29). Una versión para iOS aún no está disponible. El dispositivo debe tener NFC y no estar rooteado — el SDK valida la integridad al inicializar. :::

En cuatro pasos​

1. Agrega el repositorio y la dependencia Gradle
2. Declara los permisos AndroidManifest.xml
3. Inicializa con migoSDK.initService(...) merchantId + signature
4. Espera la activación de la terminal activeTerminal = true ──► listo para cobrar

Prerrequisitos​

El cobro con tarjeta presente se apoya en una jerarquía que Migo aprovisiona contigo antes de que integres. No registras estas entidades por API; las define tu contacto comercial:

Lo que Migo aprovisionaPara qué sirve en el SDK
Cuenta Migo (tenant / merchant)Tu cuenta dentro de la plataforma de Migo
UsuarioEl usuario autenticado dueño de la terminal — su id es el authUserId que pasas al SDK
Comercio / negocioEl negocio que opera los cobros
Sucursal (branch)Dónde se registran las terminales — su id es el branchId que pasas al SDK
merchantId y signatureLas credenciales con las que el SDK se autentica contra la plataforma en cada llamada
Credenciales del repositorio del SDKClave JSON para descargar el SDK y sus dependencias

La terminal en sí no se aprovisiona de antemano: el SDK la registra automáticamente la primera vez que se inicializa en un dispositivo nuevo (ver Registro y activación de la terminal).

:::caution merchantId y signature son secretos La signature autentica a tu comercio contra la plataforma. Trátala como una credencial: no la publiques en el repositorio ni la dejes escrita en el código. Cárgala desde tu configuración de build (por ejemplo local.properties o una variable de entorno de CI) o desde tu backend. :::

1. Agregar el repositorio y el SDK​

Migo te entrega la librería del SDK y una clave JSON con acceso al repositorio Maven privado que hospeda sus dependencias. Declara el repositorio en tu build de Gradle:

repositories {
maven {
url 'https://us-central1-maven.pkg.dev/tap-on-phone-testers/developer'
credentials {
username = '_json_key_base64'
password = MIGO_SDK_JSON_KEY_BASE64 // la clave JSON que te entrega Migo, en base64
}
authentication {
basic(BasicAuthentication)
}
}
mavenCentral()
google()
}

Luego agrega la librería del SDK de Migo (com.migo.sdkmigo) tal como Migo la distribuye para tu integración.

Flavors de entorno​

El SDK se publica con flavors que fijan la URL base de la plataforma:

FlavorEntornoURL base
sandboxQA / pruebashttps://api-qa.ali.app/rest
prodProducciónhttps://api.ali.app/rest

Usa sandbox mientras integras y cambia a prod para salir a producción.

Configuración de build requerida​

# gradle.properties
android.enableJetifier=true

android.enableJetifier=true es obligatorio: sin él las dependencias de Visa que usa el SDK no resuelven y el build falla.

Además:

  • minSdk de tu app debe ser 29 o superior.
  • compileSdk debe ser 36 o superior — el SDK se compila contra ese nivel y Gradle rechaza consumir una librería compilada con un compileSdk mayor al de la app.
  • La compatibilidad de Java es 1.8 (sourceCompatibility / targetCompatibility / jvmTarget).

:::note El identificador de tu app debe coincidir El package name y la versión de tu aplicación deben ser los mismos que registraste con Migo al crear el proyecto del SDK. Si no coinciden, la autenticación falla y el SDK no conecta. :::

2. Permisos​

El SDK necesita estos permisos en tu AndroidManifest.xml (NFC es el crítico para tarjeta presente):

<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.VIBRATE" />

<uses-feature android:name="android.hardware.nfc" android:required="false" />

El SDK no solicita los permisos en tiempo de ejecución: pídelos tú desde tu app antes de inicializar. POST_NOTIFICATIONS en particular queda a tu criterio, el SDK no lo reclama.

3. Inicializar el SDK​

Inicializa el SDK una sola vez, pasando un InitServiceParams con tus credenciales, tu implementación de MigoSDKCallbacks (los eventos del ciclo de vida de la transacción) y tu implementación de AuthSDKCallbacks (los errores de autenticación).

import com.migo.sdkmigo.presentation.migoSDK
import com.migo.sdkmigo.domain.usecasesparams.InitServiceParams
import com.migo.sdkmigo.domain.callbacks.AuthSDKCallbacks
import com.migo.sdkmigo.domain.enums.MigoProvider

migoSDK.initService(
InitServiceParams(
mActivity = this, // tu Activity
uiMigoCallback = migoCallbacks, // tu implementación de MigoSDKCallbacks
supportMcMaestro = true,
sdkProvider = MigoProvider.MIGO_PAY,
merchantId = MIGO_MERCHANT_ID, // credencial entregada por Migo
signature = MIGO_SIGNATURE, // credencial entregada por Migo
authMigoCallback = object : AuthSDKCallbacks {
override fun onAuthError(reason: String, description: String) {
// credenciales inválidas o firma vencida — el SDK no queda operativo
}
},
authUserId = userId, // id del usuario aprovisionado
branchId = branchId, // id de la sucursal aprovisionada
appVersion = BuildConfig.VERSION_NAME
)
)

initService no devuelve valor: todo el resultado llega por callbacks.

Campos de InitServiceParams​

CampoTipoRequeridoNotas
mActivityActivitySíLa Activity desde la que opera el SDK
uiMigoCallbackMigoSDKCallbacksSíRecibe todos los eventos del ciclo de vida — ver Referencia del SDK
supportMcMaestroBooleanSíHabilita el soporte de Mastercard Maestro
sdkProviderMigoProviderSíProveedor y moneda de la integración — ver tabla abajo
merchantIdStringSíIdentificador del comercio para autenticarse contra la plataforma
signatureStringSíFirma secreta que autentica las peticiones
authMigoCallbackAuthSDKCallbacksSíRecibe onAuthError(reason, description) si la autenticación falla
authUserIdInt?No*Id del usuario dueño de la terminal — necesario para registrar/activar la terminal
branchIdInt?No*Id de la sucursal donde se registra la terminal — necesario para registrar/activar la terminal y para subir firmas
onlyRestServicesBooleanNoPor defecto false. En true inicializa solo la capa REST y omite el proveedor nativo de pago: útil si tu integración no usa NFC/tarjeta presente
appVersionString?NoVersión de tu app (por ejemplo "1.4.0"). Se adjunta a los tickets de conciliación para identificar con qué versión se hizo la transacción

* Son opcionales en la firma, pero si faltan (o son <= 0) el SDK no puede crear ni activar una terminal nueva, y las firmas manuscritas no se suben. Pásalos siempre para cobros con tarjeta presente.

Valores de MigoProvider​

El sdkProvider define qué proveedor nativo se usa y con qué moneda opera la integración:

ValorMonedaPaís
MIGO_PAYGTQ — QuetzalGuatemala
MIGO_LINK_GTQGTQ — QuetzalGuatemala
MIGO_LINK_HNLHNL — Lempira hondureñoHonduras
MIGO_LINK_USDUSD — Dólar estadounidenseEl Salvador

Tu contacto en Migo te indica cuál corresponde a tu integración.

Qué llega después de inicializar​

Durante la inicialización, tu MigoSDKCallbacks recibe en orden:

  • onConnectingService() — el SDK comienza a conectarse a la plataforma. Muestra un indicador de carga.
  • onServiceConnected(terminalData) — conectado. terminalData (TerminalMigoData) trae la configuración de la terminal, incluido el flag activeTerminal y, si está activa, mPosParameters con los identificadores de comercio y terminal que usarás para cobrar.
  • onDeviceIdResponse(deviceId) — identificador único del dispositivo (la terminal física).
private var terminal: TerminalMigoData? = null

override fun onServiceConnected(terminalData: TerminalMigoData?) {
terminal = terminalData
if (terminalData?.activeTerminal == true) {
// lista para cobrar: mPosParameters trae merchantDetailId y merchantTerminalId
} else {
// activación pendiente — todavía no se puede cobrar
}
}

:::warning Solo cobra si la terminal está activa No llames a doTransaction hasta que onServiceConnected entregue terminalData.activeTerminal == true. Guarda el terminalData completo: de ahí salen los identificadores que necesita el cobro. :::

Flujos de fallo durante la inicialización:

CallbackQué pasóQué hacer
onAuthError(reason, description)merchantId o signature inválidos. Llega por authMigoCallbackCorrige las credenciales y vuelve a llamar initService. El SDK no queda operativo
onCouldNotConnectService(reason, code)No se pudo conectar con la plataformaReintenta; revisa conectividad
onCouldNotValidateIntegrity(message)El dispositivo no es seguro (root o SO modificado)Bloquea el cobro en ese dispositivo
onGeneralException(exception, message)Error inesperadoVer el catálogo en Referencia del SDK

4. Registro y activación de la terminal​

La terminal no se aprovisiona de antemano. Cuando el SDK se conecta y detecta que la terminal de este dispositivo es nueva o está inactiva (terminalData.activeTerminal == false), y dispone de authUserId y branchId válidos, la registra automáticamente:

  1. Consulta la terminal por dispositivo — GET /devices/users/{authUserId}/terminals/{deviceId}.
  2. Si no existe (404), la crea — POST /devices/users/{authUserId}/terminals con { deviceId, branchId, notifyZendesk: true }.
  3. notifyZendesk: true abre un ticket de soporte para solicitar la activación de la terminal (en Guatemala, vía Zendesk).

Mientras el ticket esté pendiente, la terminal existe pero no puede cobrar con tarjeta presente. Una vez que Migo la activa, en la siguiente conexión terminalData.activeTerminal llega en true y mPosParameters trae los id de comercio y terminalId que necesita el cobro.

initService()
└─ onServiceConnected(terminalData)
├─ activeTerminal == true ──► lista para cobrar (ver Procesar un pago)
└─ activeTerminal == false ──► el SDK crea la terminal (notifyZendesk=true)
└─ ticket de activación (Guatemala) ──► Migo activa ──► lista para cobrar
nota

El vehículo de liquidación de los cobros (tarjeta, cuenta bancaria o balance) se define con tu contacto comercial al activar la terminal. Ver Liquidación.

Múltiples terminales por sucursal​

Una sucursal puede correr más de una terminal. Cada dispositivo Android tiene su propio deviceId y, por lo tanto, su propia terminal bajo el mismo branchId. Instala el SDK en dispositivos adicionales y cada uno se registrará y activará por separado.

Desvincular el dispositivo​

migoSDK.deactivate() desvincula el dispositivo del proveedor nativo de pago. Úsalo al cerrar sesión o al dar de baja el equipo; después de llamarlo hay que volver a inicializar para poder cobrar.

:::caution Solo existe en MIGO_LINK deactivate() solo está implementado en las integraciones MIGO_LINK_*. En MIGO_PAY la llamada no hace nada. :::

migoSDK.deactivate()

Relacionado​