Skip to main content
Migo Docs

SDK Reference

A catalog of the Android SDK's public surface: which methods you can call, which callbacks you receive, and what the main entities carry. For a step-by-step integration, start with SDK Install.

Everything is invoked on the migoSDK object (com.migo.sdkmigo.presentation.migoSDK), which is a singleton: you don't instantiate it.

:::warning Initialize first Every method except initService fails with IllegalStateException if the SDK has not been initialized. Call initService once and wait for onServiceConnected before operating. :::

Methods​

Each method takes a parameter object and returns no value: the result always arrives through a callback.

MethodProviderResult callback
initServiceBothonConnectingService β†’ onServiceConnected β†’ onDeviceIdResponse
doTransactionBothonCreateTerminalPaymentResponse β†’ … β†’ onVoucherDataResponse
transactionConfirmationMIGO_PAY onlyonTransactionConfirmationResult β†’ onSendingTransactionAuthorization
doFinishTransactionBothonCreateSettlementResponse / onCreateSettlementError
stopTransactionMIGO_PAY onlyonTransactionCancelled + onGeneralException(STATE_TRANSACTION_CANCELLED_BY_USER). Never while the card is being read
sendTransactionAnnulmentBothonReversalPreviewSuccess β†’ onReversalConfirmed / onReversalCompensated / onReversalPending. Don't finalize with doFinishTransaction
doSignatureTransactionMIGO_LINK onlyonSignatureListenerResponse β†’ onSignatureUploaded / onSignatureUploadError
getHistoryTransactionsBoth*onHistoryTransactionsResponse
getSingleTerminalTransactionBothonGetSingleTransactionResponse / onGetSingleTransactionError
getDeviceIdBothonDeviceIdResponse
sendSettlementMIGO_PAY onlyonSettlementResponse
deactivateMIGO_LINK onlyUnlinks the device from the native provider

* getHistoryTransactions resolves over REST when you pass terminalId. Leave it null and it falls through to the native provider β€” where on MIGO_LINK it does nothing. Always pass it.

Availability by provider​

The sdkProvider you chose in initService decides which native provider runs underneath, and they don't all implement the same things. A method your provider doesn't support doesn't fail: it simply does nothing and no callback fires β€” worth remembering before debugging a flow that "goes quiet".

MIGO_PAYMIGO_LINK_GTQ Β· MIGO_LINK_HNL Β· MIGO_LINK_USD
Confirm the charge (transactionConfirmation)βœ…βŒ
Abort the charge (stopTransaction)βœ…βŒ
Batch close (sendSettlement)βœ…βŒ
Cardholder signature (doSignatureTransaction)βŒβœ…
Unlink the device (deactivate)βŒβœ…
Charge, finalize, reverse, historyβœ…βœ…

Identity verification (verifyDocuments, verifyFace, createSelfServeLead) is REST and does not depend on the provider.

Parameter objects​

Every one that operates on the UI takes mActivity, the Activity the SDK runs from.

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, // amount, not a string
transactionCurrency: CurrencyMigoInfo?,
merchantDetailId: String,
merchantTerminalId: String,
confirmationMode: TransactionConfirmationMigoMode?,
isApiRest: Boolean
)

TransactionConfirmationParams(
mActivity: Activity,
sendTransactionAuthorization: Boolean, // false aborts the charge
additionalTransactionInfo: AdditionalTransactionMigoInfo?
)

DoFinishTransactionParams(
mActivity: Activity,
terminalPaymentId: Int, // integer, not a string
status: String, // "approved" | "reversed"
authorizationId: String,
voucherData: VoucherMigoData
)

GetHistoryTransactionsParams(
mActivity: Activity,
terminalId: String?,
transactionId: String? // null = full history
)

SendTransactionAnnulmentParams(mActivity: Activity, historyItem: HistoryMigoItem?)
DoSignatureTransactionParams(historyItem: HistoryMigoItem?, signature: Bitmap)
StopTransactionParams(mActivity: Activity)
SendSettlementParams(mActivity: Activity)
GetDeviceIdParams(mActivity: Activity)

:::note Two types that trip people up transactionAmount is a Double (150.50, not "150.50") and terminalPaymentId is an Int (not a String). The compiler will tell you, but it's the most common friction when migrating from older guides. :::

Callbacks​

Implement MigoSDKCallbacks and pass it as uiMigoCallback in initService. The interface is broad: most methods must be implemented even if your integration doesn't use them β€” leave those empty.

:::caution MIGO_LINK brings its own screens On MIGO_LINK_* integrations the reader drives the charge with its own screen experience: prompting for the card, reading it, the PIN, and the confirmation all happen inside that UI, not yours. That's why most of the charge callbacks never fire on MIGO_LINK: you get the result (onVoucherDataResponse) but not the step-by-step.

If you're coming from MIGO_PAY, this is the biggest difference between the two: there you do build every screen of the charge yourself. :::

Connection and initialization​

CallbackProviderWhen it fires
onServiceConnected(terminalData)BothConnected. Carries activeTerminal and mPosParameters
onDeviceIdResponse(deviceId)BothUnique device identifier
onCouldNotConnectService(reason, code)BothCould not reach the platform
onConnectingService()MIGO_PAY onlyThe SDK starts connecting
onNewDeviceIdResponse(deviceId)MIGO_PAY onlyA new deviceId was assigned
onCouldNotValidateIntegrity(message)MIGO_PAY onlyThe device is not secure (rooted or modified OS)
GeneralSecurityException(exception)MIGO_PAY onlyA security validation failed β€” see GeneralSecurityMigoException

Authentication travels separately, in AuthSDKCallbacks, and applies to both:

interface AuthSDKCallbacks {
fun onAuthError(reason: String, description: String)
}

Card-present charge​

The ones marked MIGO_PAY only are those MIGO_LINK resolves inside the reader's UI.

CallbackProviderWhen it fires
onCreateTerminalPaymentResponse(response)BothThe payment was created in the backend. Save response.data.id
onCreateTerminalPaymentError(msg, raw)BothCreation failed. The charge stops here
onVoucherDataResponse(voucher)BothTransaction response. Check isTransactionApproved
onCreateSettlementResponse(response)BothSettlement created
onCreateSettlementError(msg, raw)BothSettlement failed
onNFCStateOff()BothNFC is off
onGeneralException(exception, message)BothError β€” see GeneralMigoException
onPresentCardRequest(data)MIGO_PAY onlyAsks for the card to be tapped
onReadingCardData()MIGO_PAY onlyReading the card
onUserCardPinRequest()MIGO_PAY onlyThe cardholder's PIN is required
onUserCardPinCanceled()MIGO_PAY onlyThe user cancelled PIN entry
onReturnCurrentTransactionInfo(info, mode)MIGO_PAY onlyCard read. You must call transactionConfirmation()
onTransactionConfirmationResult(confirmed, mode)MIGO_PAY onlyConfirmation result
onSendingTransactionAuthorization()MIGO_PAY onlySending for authorization
onTransactionCancelled()MIGO_PAY onlyThe transaction was cancelled
onStoringOfflineAuthorizedTransaction()MIGO_PAY onlyConnection lost: the transaction was stored locally
onSettlementResponse(success, message)MIGO_PAY onlyBatch-close response (sendSettlement)
onVoucherSent()MIGO_PAY onlyThe voucher was sent
onProcessingCommand()MIGO_PAY onlyThe SDK is busy: don't send another command
onGPSNeeded()MIGO_PAY onlyGPS location is required
onFinishTransactionResponse(data)β€”Response to closing the transaction

The callbacks onSendingRefundTransactionAuthorization, onSendingCheckIn*, onSendingCheckOut*, onSignUpUserResponse, and the onROB* family belong to legacy or internal flows that current integrations don't use. Implement them empty.

Cardholder signature​

MIGO_LINK only. See Capture the cardholder signature.

CallbackWhen it fires
onSignatureRequired(voucher)The transaction requires a signature. Mutually exclusive with onVoucherDataResponse
onSignatureListenerResponse(reason, code)The reader stored the signature (reason == null) or could not
onSignatureUploaded(url)The signature was uploaded and attached to the charge
onSignatureUploadError(msg, code)Upload failed. Does not affect the charge

The last three have empty default implementations: implement them only if you capture signatures.

History​

Both providers β€” they resolve over REST.

CallbackWhen it fires
onHistoryTransactionsResponse(history, terminalId)History retrieved. May come back empty
onGetSingleTransactionResponse(item)Transaction detail as a HistoryMigoItem
onGetSingleTransactionError(msg, raw)Error retrieving the detail

Reversal​

Both providers. All with empty default implementations β€” implement them anyway: without them an ineligible reversal reports nothing. Usage lives in Reverse an authorized charge.

CallbackWhen it fires
onReversalPreviewSuccess(preview)The charge is reversible. The SDK continues automatically
onReversalPreviewError(reason, msg, preview)Could not start. The card is not touched
onReversalConfirmed(reversalId)The reversal completed
onReversalConfirmError(reason, message)Confirmation failed on the server
onReversalCompensated(reversalId)The processor declined and the amount was credited back
onReversalCompensationError(reason, message)Compensation failed
onReversalPending(reversalId)Left pending; it will resolve later

Ineligibility reasons that reason can carry: outsideSameDayWindow, notLiquidated, settlementNotFound, insufficientBalance, balanceUnavailable.

Enums​

TransactionConfirmationMigoMode​

ValueBehavior
USER_CONFIRMATIONThe flow pauses at onReturnCurrentTransactionInfo until you call transactionConfirmation()
AUTOMATIC_CONFIRMATIONThe SDK proceeds to authorization without pausing

AuthorizationMigoType​

NONE, SALE, REFUND, CHECKIN, CHECKIN_REAUTHORIZATION, CHECKOUT, VOID.

A card-present charge reports SALE; a void reports VOID.

MigoProvider​

ValueCurrencyCountry
MIGO_PAYGTQGuatemala
MIGO_LINK_GTQGTQGuatemala
MIGO_LINK_HNLHNLHonduras
MIGO_LINK_USDUSDEl Salvador

GeneralMigoException​

Arrives in onGeneralException(exception, message). The enum has more than 60 values; these are the ones you'll see most often:

ValueMeaning
STATE_TRANSACTION_CANCELLED_BY_USERThe transaction was cancelled with stopTransaction()
STATE_NFC_DISABLEDNFC is off
NO_NETWORK_AVAILABLENo connectivity
NO_GPS_AVAILABLENo location available
STATE_READING_CARD_ERRORError reading the card
STATE_CAN_NOT_READ_THE_CARDThe card could not be read
STATE_READING_CARD_TIME_OUTCard read timed out
STATE_PLEASE_TAP_CARD_AGAINAsk the customer to tap again
STATE_PLEASE_USE_ANOTHER_CARDThe card can't be used for this charge
STATE_CONTACTLESS_APPLICATION_NOT_ALLOWEDThe card's contactless application is not allowed
STATE_TRANSACTION_OFFLINE_DECLINEDDeclined offline
STATE_ESSENTIAL_PERMISSIONS_NOT_GRANTED_YETAndroid permissions are missing
INVALID_TRANSACTION_CURRENCYThe currency sent is not valid
INVALID_MERCHANT_IDThe merchant identifier is not valid
COULD_NOT_SEND_VOID_FOR_A_VOIDED_TRANSACTIONIt was already voided

GeneralSecurityMigoException​

Arrives in 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.

Entities​

TerminalMigoData​

Arrives in onServiceConnected. The fields you'll use:

FieldTypeWhat it's for
activeTerminalBoolean?Must be true to charge
mPosParametersList<MerchantMigoDetail>?Merchant configuration: the charge ids come from here
mPosUserName / mPosUserEmailString?Terminal user details
dashboardUrlString?URL of the associated dashboard
externalIdString?Your external identifier, if configured

MerchantMigoDetail​

Each element of mPosParameters:

FieldTypeWhat it's for
idString?The merchantDetailId in doTransaction
terminalIdString?The merchantTerminalId in doTransaction
currencyInfoListList<CurrencyMigoInfo>?Enabled currencies; the first is the terminal's
countryCodeString?Country of the affiliation
cardAcqIdString?Acquirer identifier

CurrencyMigoInfo​

CurrencyMigoInfo(
currencyCode: String?, // "320"
currencyDescription: String?, // "Quetzal"
currencyCode3: String? // "GTQ"
)

Take it from mPosParameters[0].currencyInfoList[0] rather than building it by hand: that way it always matches the terminal's configuration.

CurrentTransactionMigoInfo​

Arrives in onReturnCurrentTransactionInfo, for the confirmation screen: transactionAmount, transactionCurrencyCode3, cardHolderName, cardObfPan, cardLabel, cardAID, authorizationMigoType, quotas, baseAmount, taxAmount, dateTimeTransaction.

VoucherMigoData​

Arrives in onVoucherDataResponse. The fields that drive the flow:

FieldTypeWhat it's for
isTransactionApprovedBoolean?Check this first. If it isn't true, don't finalize
authorizationMigoTypeAuthorizationMigoType?SALE β†’ "approved"; VOID β†’ "reversed"
authorizationIdString?Authorization code, required by doFinishTransaction
responseCodeString?Processor code ("14" on a VOID means the reversal failed)
responseCodeDescription / reasonTextString?Human-readable decline detail
isSignatureNeededBoolean?The transaction requires a signature
isTransactionOfflineApprovedBoolean?Approved offline

For the printed voucher: cardObfPAN, cardholderName, cardLabel, transactionAuthorizedAmount, transactionCurrencyCode3, transactionDateTime, referenceNumber, systemTrace, batchNumber, terminalId, cardAcquirerName.

HistoryMigoItem​

Each transaction in history. SDK-specific fields:

FieldTypeWhat it's for
_internalIdIntThe terminalPaymentId when voiding from history
_signatureUrlString?Location of the stored signature, if any
_signatureDataString?The signature itself, to redraw it