Saltar al contenido principal
Migo Docs

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étodoProveedorResultado por callback
initServiceAmbosonConnectingService → onServiceConnected → onDeviceIdResponse
doTransactionAmbosonCreateTerminalPaymentResponse → … → onVoucherDataResponse
transactionConfirmationSolo MIGO_PAYonTransactionConfirmationResult → onSendingTransactionAuthorization
doFinishTransactionAmbosonCreateSettlementResponse / onCreateSettlementError
stopTransactionSolo MIGO_PAYonTransactionCancelled + onGeneralException(STATE_TRANSACTION_CANCELLED_BY_USER). Nunca durante la lectura de la tarjeta
sendTransactionAnnulmentAmbosonReversalPreviewSuccess → onReversalConfirmed / onReversalCompensated / onReversalPending. No finalices con doFinishTransaction
doSignatureTransactionSolo MIGO_LINKonSignatureListenerResponse → onSignatureUploaded / onSignatureUploadError
getHistoryTransactionsAmbos*onHistoryTransactionsResponse
getSingleTerminalTransactionAmbosonGetSingleTransactionResponse / onGetSingleTransactionError
getDeviceIdAmbosonDeviceIdResponse
sendSettlementSolo MIGO_PAYonSettlementResponse
deactivateSolo MIGO_LINKDesvincula 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_PAYMIGO_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​

CallbackProveedorCuándo se dispara
onServiceConnected(terminalData)AmbosConectado. Trae activeTerminal y mPosParameters
onDeviceIdResponse(deviceId)AmbosIdentificador único del dispositivo
onCouldNotConnectService(reason, code)AmbosNo se pudo conectar con la plataforma
onConnectingService()Solo MIGO_PAYEl SDK empieza a conectarse
onNewDeviceIdResponse(deviceId)Solo MIGO_PAYSe asignó un deviceId nuevo
onCouldNotValidateIntegrity(message)Solo MIGO_PAYEl dispositivo no es seguro (root o SO modificado)
GeneralSecurityException(exception)Solo MIGO_PAYFalló 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.

CallbackProveedorCuándo se dispara
onCreateTerminalPaymentResponse(response)AmbosEl pago se creó en el backend. Guarda response.data.id
onCreateTerminalPaymentError(msg, raw)AmbosFalló la creación. El cobro se detiene aquí
onVoucherDataResponse(voucher)AmbosRespuesta de la transacción. Revisa isTransactionApproved
onCreateSettlementResponse(response)AmbosLiquidación creada
onCreateSettlementError(msg, raw)AmbosFalló la liquidación
onNFCStateOff()AmbosNFC apagado
onGeneralException(exception, message)AmbosError — ver GeneralMigoException
onPresentCardRequest(data)Solo MIGO_PAYPide acercar la tarjeta al lector
onReadingCardData()Solo MIGO_PAYLeyendo la tarjeta
onUserCardPinRequest()Solo MIGO_PAYSe requiere el PIN del titular
onUserCardPinCanceled()Solo MIGO_PAYEl usuario canceló el ingreso del PIN
onReturnCurrentTransactionInfo(info, mode)Solo MIGO_PAYTarjeta leída. Debes llamar transactionConfirmation()
onTransactionConfirmationResult(confirmed, mode)Solo MIGO_PAYResultado de la confirmación
onSendingTransactionAuthorization()Solo MIGO_PAYEnviando a autorizar
onTransactionCancelled()Solo MIGO_PAYLa transacción se canceló
onStoringOfflineAuthorizedTransaction()Solo MIGO_PAYSe perdió conexión: la transacción quedó guardada localmente
onSettlementResponse(success, message)Solo MIGO_PAYRespuesta del cierre por lote (sendSettlement)
onVoucherSent()Solo MIGO_PAYEl voucher se envió
onProcessingCommand()Solo MIGO_PAYEl SDK está ocupado: no envíes otro comando
onGPSNeeded()Solo MIGO_PAYSe 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.

CallbackCuá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.

CallbackCuá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.

CallbackCuá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​

ValorComportamiento
USER_CONFIRMATIONEl flujo se pausa en onReturnCurrentTransactionInfo hasta que llames transactionConfirmation()
AUTOMATIC_CONFIRMATIONEl 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​

ValorMonedaPaís
MIGO_PAYGTQGuatemala
MIGO_LINK_GTQGTQGuatemala
MIGO_LINK_HNLHNLHonduras
MIGO_LINK_USDUSDEl 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:

ValorSignificado
STATE_TRANSACTION_CANCELLED_BY_USERLa transacción se canceló con stopTransaction()
STATE_NFC_DISABLEDNFC apagado
NO_NETWORK_AVAILABLESin conectividad
NO_GPS_AVAILABLESin ubicación disponible
STATE_READING_CARD_ERRORError leyendo la tarjeta
STATE_CAN_NOT_READ_THE_CARDLa tarjeta no se pudo leer
STATE_READING_CARD_TIME_OUTSe agotó el tiempo de lectura
STATE_PLEASE_TAP_CARD_AGAINPide reintentar el acercamiento
STATE_PLEASE_USE_ANOTHER_CARDLa tarjeta no sirve para este cobro
STATE_CONTACTLESS_APPLICATION_NOT_ALLOWEDLa aplicación contactless de la tarjeta no está permitida
STATE_TRANSACTION_OFFLINE_DECLINEDDeclinada sin conexión
STATE_ESSENTIAL_PERMISSIONS_NOT_GRANTED_YETFaltan permisos de Android
INVALID_TRANSACTION_CURRENCYLa moneda enviada no es válida
INVALID_MERCHANT_IDEl identificador de comercio no es válido
COULD_NOT_SEND_VOID_FOR_A_VOIDED_TRANSACTIONYa 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:

CampoTipoPara qué
activeTerminalBoolean?Debe ser true para poder cobrar
mPosParametersList<MerchantMigoDetail>?Configuración de comercio: de aquí salen los ids del cobro
mPosUserName / mPosUserEmailString?Datos del usuario de la terminal
dashboardUrlString?URL del panel asociado
externalIdString?Tu identificador externo, si lo configuraste

MerchantMigoDetail​

Cada elemento de mPosParameters:

CampoTipoPara qué
idString?El merchantDetailId de doTransaction
terminalIdString?El merchantTerminalId de doTransaction
currencyInfoListList<CurrencyMigoInfo>?Monedas habilitadas; la primera es la de la terminal
countryCodeString?País de la afiliación
cardAcqIdString?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:

CampoTipoPara qué
isTransactionApprovedBoolean?Revísalo primero. Si no es true, no finalices
authorizationMigoTypeAuthorizationMigoType?SALE → "approved"; VOID → "reversed"
authorizationIdString?Código de autorización, requerido por doFinishTransaction
responseCodeString?Código del procesador ("14" en un VOID indica reversa fallida)
responseCodeDescription / reasonTextString?Detalle legible del rechazo
isSignatureNeededBoolean?La transacción requiere firma
isTransactionOfflineApprovedBoolean?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:

CampoTipoPara qué
_internalIdIntEl terminalPaymentId al anular desde el historial
_signatureUrlString?Ubicación de la firma almacenada, si la hay
_signatureDataString?La firma en sí, para volver a dibujarla

Relacionado​