Referencia del SDK
Catálogo de la superficie pública del SDK de Android: qué métodos puedes llamar, qué callbacks recibes y qué traen las entidades principales. Para el paso a paso de una integración, empieza por Instalación del SDK.
Todo se invoca sobre el objeto migoSDK (com.migo.sdkmigo.presentation.migoSDK), que es un singleton: no lo instancias.
:::warning Inicializa primero
Todos los métodos salvo initService fallan con IllegalStateException si el SDK no fue inicializado. Llama initService una vez y espera onServiceConnected antes de operar.
:::
Métodos
Cada método recibe un objeto de parámetros y no devuelve valor: el resultado llega siempre por un callback.
| Método | Proveedor | Resultado por callback |
|---|---|---|
initService | Ambos | onConnectingService → onServiceConnected → onDeviceIdResponse |
doTransaction | Ambos | onCreateTerminalPaymentResponse → … → onVoucherDataResponse |
transactionConfirmation | Solo MIGO_PAY | onTransactionConfirmationResult → onSendingTransactionAuthorization |
doFinishTransaction | Ambos | onCreateSettlementResponse / onCreateSettlementError |
stopTransaction | Solo MIGO_PAY | onTransactionCancelled + onGeneralException(STATE_TRANSACTION_CANCELLED_BY_USER). Nunca durante la lectura de la tarjeta |
sendTransactionAnnulment | Ambos | onReversalPreviewSuccess → onReversalConfirmed / onReversalCompensated / onReversalPending. No finalices con doFinishTransaction |
doSignatureTransaction | Solo MIGO_LINK | onSignatureListenerResponse → onSignatureUploaded / onSignatureUploadError |
getHistoryTransactions | Ambos* | onHistoryTransactionsResponse |
getSingleTerminalTransaction | Ambos | onGetSingleTransactionResponse / onGetSingleTransactionError |
getDeviceId | Ambos | onDeviceIdResponse |
sendSettlement | Solo MIGO_PAY | onSettlementResponse |
deactivate | Solo MIGO_LINK | Desvincula el dispositivo del proveedor nativo |
* getHistoryTransactions resuelve por REST cuando le pasas terminalId. Si lo dejas en null, cae al proveedor nativo — y ahí en MIGO_LINK no hace nada. Pásalo siempre.
Disponibilidad por proveedor
El sdkProvider que elegiste en initService decide qué proveedor nativo corre por debajo, y no todos implementan lo mismo. Un método no soportado por tu proveedor no falla: simplemente no hace nada y ningún callback se dispara — por eso conviene tenerlo presente antes de depurar un flujo que "se queda callado".
MIGO_PAY | MIGO_LINK_GTQ · MIGO_LINK_HNL · MIGO_LINK_USD | |
|---|---|---|
Confirmar el cobro (transactionConfirmation) | ✅ | ❌ |
Abortar el cobro (stopTransaction) | ✅ | ❌ |
Cierre por lote (sendSettlement) | ✅ | ❌ |
Firma del titular (doSignatureTransaction) | ❌ | ✅ |
Desvincular el dispositivo (deactivate) | ❌ | ✅ |
| Cobrar, finalizar, reversar, historial | ✅ | ✅ |
La verificación de identidad (verifyDocuments, verifyFace, createSelfServeLead) es REST y no depende del proveedor.
Objetos de parámetros
Todos los que operan sobre la UI reciben mActivity, la Activity desde la que corre el SDK.
InitServiceParams(
mActivity: Activity,
uiMigoCallback: MigoSDKCallbacks,
supportMcMaestro: Boolean,
sdkProvider: MigoProvider,
merchantId: String,
signature: String,
authMigoCallback: AuthSDKCallbacks,
authUserId: Int? = null,
branchId: Int? = null,
onlyRestServices: Boolean = false,
appVersion: String? = null
)
DoTransactionParams(
mActivity: Activity,
transactionAmount: Double, // monto, no string
transactionCurrency: CurrencyMigoInfo?,
merchantDetailId: String,
merchantTerminalId: String,
confirmationMode: TransactionConfirmationMigoMode?,
isApiRest: Boolean
)
TransactionConfirmationParams(
mActivity: Activity,
sendTransactionAuthorization: Boolean, // false aborta el cobro
additionalTransactionInfo: AdditionalTransactionMigoInfo?
)
DoFinishTransactionParams(
mActivity: Activity,
terminalPaymentId: Int, // entero, no string
status: String, // "approved" | "reversed"
authorizationId: String,
voucherData: VoucherMigoData
)
GetHistoryTransactionsParams(
mActivity: Activity,
terminalId: String?,
transactionId: String? // null = historial completo
)
SendTransactionAnnulmentParams(mActivity: Activity, historyItem: HistoryMigoItem?)
DoSignatureTransactionParams(historyItem: HistoryMigoItem?, signature: Bitmap)
StopTransactionParams(mActivity: Activity)
SendSettlementParams(mActivity: Activity)
GetDeviceIdParams(mActivity: Activity)
:::note Dos tipos que suelen confundirse
transactionAmount es un Double (150.50, no "150.50") y terminalPaymentId es un Int (no un String). El compilador te avisa, pero es la fuente más común de fricción al migrar desde guías antiguas.
:::
Callbacks
Implementa MigoSDKCallbacks y pásala como uiMigoCallback en initService. La interfaz es amplia: la mayoría de los métodos son obligatorios de implementar aunque tu integración no los use — déjalos vacíos.
:::caution MIGO_LINK trae sus propias pantallas
En las integraciones MIGO_LINK_* el lector conduce el cobro con su propia experiencia de pantallas: pedir la tarjeta, leerla, el PIN y la confirmación ocurren dentro de esa UI, no en la tuya. Por eso la mayoría de los callbacks del cobro no se disparan en MIGO_LINK: recibes el resultado (onVoucherDataResponse) pero no el paso a paso.
Si vienes de MIGO_PAY, esta es la diferencia más grande entre ambos: ahí sí construyes tú cada pantalla del cobro. :::
Conexión e inicialización
| Callback | Proveedor | Cuándo se dispara |
|---|---|---|
onServiceConnected(terminalData) | Ambos | Conectado. Trae activeTerminal y mPosParameters |
onDeviceIdResponse(deviceId) | Ambos | Identificador único del dispositivo |
onCouldNotConnectService(reason, code) | Ambos | No se pudo conectar con la plataforma |
onConnectingService() | Solo MIGO_PAY | El SDK empieza a conectarse |
onNewDeviceIdResponse(deviceId) | Solo MIGO_PAY | Se asignó un deviceId nuevo |
onCouldNotValidateIntegrity(message) | Solo MIGO_PAY | El dispositivo no es seguro (root o SO modificado) |
GeneralSecurityException(exception) | Solo MIGO_PAY | Falló una validación de seguridad — ver GeneralSecurityMigoException |
La autenticación viaja aparte, en AuthSDKCallbacks, y aplica a ambos:
interface AuthSDKCallbacks {
fun onAuthError(reason: String, description: String)
}
Cobro con tarjeta presente
Los que van marcados Solo MIGO_PAY son los que MIGO_LINK resuelve dentro de la UI del lector.
| Callback | Proveedor | Cuándo se dispara |
|---|---|---|
onCreateTerminalPaymentResponse(response) | Ambos | El pago se creó en el backend. Guarda response.data.id |
onCreateTerminalPaymentError(msg, raw) | Ambos | Falló la creación. El cobro se detiene aquí |
onVoucherDataResponse(voucher) | Ambos | Respuesta de la transacción. Revisa isTransactionApproved |
onCreateSettlementResponse(response) | Ambos | Liquidación creada |
onCreateSettlementError(msg, raw) | Ambos | Falló la liquidación |
onNFCStateOff() | Ambos | NFC apagado |
onGeneralException(exception, message) | Ambos | Error — ver GeneralMigoException |
onPresentCardRequest(data) | Solo MIGO_PAY | Pide acercar la tarjeta al lector |
onReadingCardData() | Solo MIGO_PAY | Leyendo la tarjeta |
onUserCardPinRequest() | Solo MIGO_PAY | Se requiere el PIN del titular |
onUserCardPinCanceled() | Solo MIGO_PAY | El usuario canceló el ingreso del PIN |
onReturnCurrentTransactionInfo(info, mode) | Solo MIGO_PAY | Tarjeta leída. Debes llamar transactionConfirmation() |
onTransactionConfirmationResult(confirmed, mode) | Solo MIGO_PAY | Resultado de la confirmación |
onSendingTransactionAuthorization() | Solo MIGO_PAY | Enviando a autorizar |
onTransactionCancelled() | Solo MIGO_PAY | La transacción se canceló |
onStoringOfflineAuthorizedTransaction() | Solo MIGO_PAY | Se perdió conexión: la transacción quedó guardada localmente |
onSettlementResponse(success, message) | Solo MIGO_PAY | Respuesta del cierre por lote (sendSettlement) |
onVoucherSent() | Solo MIGO_PAY | El voucher se envió |
onProcessingCommand() | Solo MIGO_PAY | El SDK está ocupado: no envíes otro comando |
onGPSNeeded() | Solo MIGO_PAY | Se requiere la ubicación GPS |
onFinishTransactionResponse(data) | — | Respuesta del cierre de la transacción |
Los callbacks onSendingRefundTransactionAuthorization, onSendingCheckIn*, onSendingCheckOut*, onSignUpUserResponse y la familia onROB* corresponden a flujos legados o internos que las integraciones actuales no usan. Impleméntalos vacíos.
Firma del titular
Solo MIGO_LINK. Ver Capturar la firma del titular.
| Callback | Cuándo se dispara |
|---|---|
onSignatureRequired(voucher) | La transacción exige firma. Excluyente con onVoucherDataResponse |
onSignatureListenerResponse(reason, code) | El lector guardó la firma (reason == null) o no pudo |
onSignatureUploaded(url) | La firma se subió al servidor y quedó pegada al cobro |
onSignatureUploadError(msg, code) | No se pudo subir. No afecta al cobro |
Los tres últimos tienen implementación por defecto vacía: impleméntalos solo si capturas firmas.
Historial
Ambos proveedores — se resuelven por REST.
| Callback | Cuándo se dispara |
|---|---|
onHistoryTransactionsResponse(history, terminalId) | Historial recuperado. Puede venir vacío |
onGetSingleTransactionResponse(item) | Detalle de una transacción como HistoryMigoItem |
onGetSingleTransactionError(msg, raw) | Error al recuperar el detalle |
Reversión
Ambos proveedores. Todos con implementación por defecto vacía — impleméntalos igual: sin ellos una reversión no elegible no notifica nada. El uso está en Reversar un cobro autorizado.
| Callback | Cuándo se dispara |
|---|---|
onReversalPreviewSuccess(preview) | El cobro es reversible. El SDK continúa automáticamente |
onReversalPreviewError(reason, msg, preview) | No se pudo iniciar. No se toca la tarjeta |
onReversalConfirmed(reversalId) | La reversión quedó completa |
onReversalConfirmError(reason, message) | Falló la confirmación en el servidor |
onReversalCompensated(reversalId) | El procesador rechazó y se recargó el monto |
onReversalCompensationError(reason, message) | Falló la compensación |
onReversalPending(reversalId) | Quedó pendiente; se resolverá más tarde |
Motivos de inelegibilidad que puede traer reason: outsideSameDayWindow, notLiquidated, settlementNotFound, insufficientBalance, balanceUnavailable.
Enums
TransactionConfirmationMigoMode
| Valor | Comportamiento |
|---|---|
USER_CONFIRMATION | El flujo se pausa en onReturnCurrentTransactionInfo hasta que llames transactionConfirmation() |
AUTOMATIC_CONFIRMATION | El SDK sigue a la autorización sin pausa |
AuthorizationMigoType
NONE, SALE, REFUND, CHECKIN, CHECKIN_REAUTHORIZATION, CHECKOUT, VOID.
En un cobro con tarjeta presente verás SALE; en una anulación, VOID.
MigoProvider
| Valor | Moneda | País |
|---|---|---|
MIGO_PAY | GTQ | Guatemala |
MIGO_LINK_GTQ | GTQ | Guatemala |
MIGO_LINK_HNL | HNL | Honduras |
MIGO_LINK_USD | USD | El Salvador |
GeneralMigoException
Llega en onGeneralException(exception, message). El enum tiene más de 60 valores; estos son los que verás con más frecuencia:
| Valor | Significado |
|---|---|
STATE_TRANSACTION_CANCELLED_BY_USER | La transacción se canceló con stopTransaction() |
STATE_NFC_DISABLED | NFC apagado |
NO_NETWORK_AVAILABLE | Sin conectividad |
NO_GPS_AVAILABLE | Sin ubicación disponible |
STATE_READING_CARD_ERROR | Error leyendo la tarjeta |
STATE_CAN_NOT_READ_THE_CARD | La tarjeta no se pudo leer |
STATE_READING_CARD_TIME_OUT | Se agotó el tiempo de lectura |
STATE_PLEASE_TAP_CARD_AGAIN | Pide reintentar el acercamiento |
STATE_PLEASE_USE_ANOTHER_CARD | La tarjeta no sirve para este cobro |
STATE_CONTACTLESS_APPLICATION_NOT_ALLOWED | La aplicación contactless de la tarjeta no está permitida |
STATE_TRANSACTION_OFFLINE_DECLINED | Declinada sin conexión |
STATE_ESSENTIAL_PERMISSIONS_NOT_GRANTED_YET | Faltan permisos de Android |
INVALID_TRANSACTION_CURRENCY | La moneda enviada no es válida |
INVALID_MERCHANT_ID | El identificador de comercio no es válido |
COULD_NOT_SEND_VOID_FOR_A_VOIDED_TRANSACTION | Ya estaba anulada |
GeneralSecurityMigoException
Llega en GeneralSecurityException(exception): NONE, STATE_DEVICE_IS_ROOTED, STATE_DEVICE_IS_DEBUG, STATE_DEVICE_IS_EMULATOR, STATE_DEVICE_INVALID_APP_SIGNATURE, STATE_DEVICE_INVALID_APP_INSTALLER, STATE_DEVICE_APP_TAMPERED.
Entidades
TerminalMigoData
Llega en onServiceConnected. Campos que usarás:
| Campo | Tipo | Para qué |
|---|---|---|
activeTerminal | Boolean? | Debe ser true para poder cobrar |
mPosParameters | List<MerchantMigoDetail>? | Configuración de comercio: de aquí salen los ids del cobro |
mPosUserName / mPosUserEmail | String? | Datos del usuario de la terminal |
dashboardUrl | String? | URL del panel asociado |
externalId | String? | Tu identificador externo, si lo configuraste |
MerchantMigoDetail
Cada elemento de mPosParameters:
| Campo | Tipo | Para qué |
|---|---|---|
id | String? | El merchantDetailId de doTransaction |
terminalId | String? | El merchantTerminalId de doTransaction |
currencyInfoList | List<CurrencyMigoInfo>? | Monedas habilitadas; la primera es la de la terminal |
countryCode | String? | País de la afiliación |
cardAcqId | String? | Identificador del adquirente |
CurrencyMigoInfo
CurrencyMigoInfo(
currencyCode: String?, // "320"
currencyDescription: String?, // "Quetzal"
currencyCode3: String? // "GTQ"
)
Tómala de mPosParameters[0].currencyInfoList[0] en lugar de construirla a mano: así siempre coincide con la configuración de la terminal.
CurrentTransactionMigoInfo
Llega en onReturnCurrentTransactionInfo, para mostrar la pantalla de confirmación: transactionAmount, transactionCurrencyCode3, cardHolderName, cardObfPan, cardLabel, cardAID, authorizationMigoType, quotas, baseAmount, taxAmount, dateTimeTransaction.
VoucherMigoData
Llega en onVoucherDataResponse. Los campos que deciden el flujo:
| Campo | Tipo | Para qué |
|---|---|---|
isTransactionApproved | Boolean? | Revísalo primero. Si no es true, no finalices |
authorizationMigoType | AuthorizationMigoType? | SALE → "approved"; VOID → "reversed" |
authorizationId | String? | Código de autorización, requerido por doFinishTransaction |
responseCode | String? | Código del procesador ("14" en un VOID indica reversa fallida) |
responseCodeDescription / reasonText | String? | Detalle legible del rechazo |
isSignatureNeeded | Boolean? | La transacción requiere firma |
isTransactionOfflineApproved | Boolean? | Aprobada sin conexión |
Para el voucher impreso: cardObfPAN, cardholderName, cardLabel, transactionAuthorizedAmount, transactionCurrencyCode3, transactionDateTime, referenceNumber, systemTrace, batchNumber, terminalId, cardAcquirerName.
HistoryMigoItem
Cada transacción del historial. Campos propios del SDK:
| Campo | Tipo | Para qué |
|---|---|---|
_internalId | Int | El terminalPaymentId al anular desde el historial |
_signatureUrl | String? | Ubicación de la firma almacenada, si la hay |
_signatureData | String? | La firma en sí, para volver a dibujarla |
Relacionado
- Instalación del SDK — inicialización y activación de la terminal.
- Procesar un pago con terminal — el cobro paso a paso.
- Cancelar un cobro en curso — abortar antes de la autorización.
- Reversar un cobro autorizado — deshacer un cobro aprobado.
- Catálogo de errores — códigos del backend de Migo.