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.
| Method | Provider | Result callback |
|---|---|---|
initService | Both | onConnectingService β onServiceConnected β onDeviceIdResponse |
doTransaction | Both | onCreateTerminalPaymentResponse β β¦ β onVoucherDataResponse |
transactionConfirmation | MIGO_PAY only | onTransactionConfirmationResult β onSendingTransactionAuthorization |
doFinishTransaction | Both | onCreateSettlementResponse / onCreateSettlementError |
stopTransaction | MIGO_PAY only | onTransactionCancelled + onGeneralException(STATE_TRANSACTION_CANCELLED_BY_USER). Never while the card is being read |
sendTransactionAnnulment | Both | onReversalPreviewSuccess β onReversalConfirmed / onReversalCompensated / onReversalPending. Don't finalize with doFinishTransaction |
doSignatureTransaction | MIGO_LINK only | onSignatureListenerResponse β onSignatureUploaded / onSignatureUploadError |
getHistoryTransactions | Both* | onHistoryTransactionsResponse |
getSingleTerminalTransaction | Both | onGetSingleTransactionResponse / onGetSingleTransactionError |
getDeviceId | Both | onDeviceIdResponse |
sendSettlement | MIGO_PAY only | onSettlementResponse |
deactivate | MIGO_LINK only | Unlinks 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_PAY | MIGO_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β
| Callback | Provider | When it fires |
|---|---|---|
onServiceConnected(terminalData) | Both | Connected. Carries activeTerminal and mPosParameters |
onDeviceIdResponse(deviceId) | Both | Unique device identifier |
onCouldNotConnectService(reason, code) | Both | Could not reach the platform |
onConnectingService() | MIGO_PAY only | The SDK starts connecting |
onNewDeviceIdResponse(deviceId) | MIGO_PAY only | A new deviceId was assigned |
onCouldNotValidateIntegrity(message) | MIGO_PAY only | The device is not secure (rooted or modified OS) |
GeneralSecurityException(exception) | MIGO_PAY only | A 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.
| Callback | Provider | When it fires |
|---|---|---|
onCreateTerminalPaymentResponse(response) | Both | The payment was created in the backend. Save response.data.id |
onCreateTerminalPaymentError(msg, raw) | Both | Creation failed. The charge stops here |
onVoucherDataResponse(voucher) | Both | Transaction response. Check isTransactionApproved |
onCreateSettlementResponse(response) | Both | Settlement created |
onCreateSettlementError(msg, raw) | Both | Settlement failed |
onNFCStateOff() | Both | NFC is off |
onGeneralException(exception, message) | Both | Error β see GeneralMigoException |
onPresentCardRequest(data) | MIGO_PAY only | Asks for the card to be tapped |
onReadingCardData() | MIGO_PAY only | Reading the card |
onUserCardPinRequest() | MIGO_PAY only | The cardholder's PIN is required |
onUserCardPinCanceled() | MIGO_PAY only | The user cancelled PIN entry |
onReturnCurrentTransactionInfo(info, mode) | MIGO_PAY only | Card read. You must call transactionConfirmation() |
onTransactionConfirmationResult(confirmed, mode) | MIGO_PAY only | Confirmation result |
onSendingTransactionAuthorization() | MIGO_PAY only | Sending for authorization |
onTransactionCancelled() | MIGO_PAY only | The transaction was cancelled |
onStoringOfflineAuthorizedTransaction() | MIGO_PAY only | Connection lost: the transaction was stored locally |
onSettlementResponse(success, message) | MIGO_PAY only | Batch-close response (sendSettlement) |
onVoucherSent() | MIGO_PAY only | The voucher was sent |
onProcessingCommand() | MIGO_PAY only | The SDK is busy: don't send another command |
onGPSNeeded() | MIGO_PAY only | GPS 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.
| Callback | When 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.
| Callback | When 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.
| Callback | When 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β
| Value | Behavior |
|---|---|
USER_CONFIRMATION | The flow pauses at onReturnCurrentTransactionInfo until you call transactionConfirmation() |
AUTOMATIC_CONFIRMATION | The 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β
| Value | Currency | Country |
|---|---|---|
MIGO_PAY | GTQ | Guatemala |
MIGO_LINK_GTQ | GTQ | Guatemala |
MIGO_LINK_HNL | HNL | Honduras |
MIGO_LINK_USD | USD | El Salvador |
GeneralMigoExceptionβ
Arrives in onGeneralException(exception, message). The enum has more than 60 values; these are the ones you'll see most often:
| Value | Meaning |
|---|---|
STATE_TRANSACTION_CANCELLED_BY_USER | The transaction was cancelled with stopTransaction() |
STATE_NFC_DISABLED | NFC is off |
NO_NETWORK_AVAILABLE | No connectivity |
NO_GPS_AVAILABLE | No location available |
STATE_READING_CARD_ERROR | Error reading the card |
STATE_CAN_NOT_READ_THE_CARD | The card could not be read |
STATE_READING_CARD_TIME_OUT | Card read timed out |
STATE_PLEASE_TAP_CARD_AGAIN | Ask the customer to tap again |
STATE_PLEASE_USE_ANOTHER_CARD | The card can't be used for this charge |
STATE_CONTACTLESS_APPLICATION_NOT_ALLOWED | The card's contactless application is not allowed |
STATE_TRANSACTION_OFFLINE_DECLINED | Declined offline |
STATE_ESSENTIAL_PERMISSIONS_NOT_GRANTED_YET | Android permissions are missing |
INVALID_TRANSACTION_CURRENCY | The currency sent is not valid |
INVALID_MERCHANT_ID | The merchant identifier is not valid |
COULD_NOT_SEND_VOID_FOR_A_VOIDED_TRANSACTION | It 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:
| Field | Type | What it's for |
|---|---|---|
activeTerminal | Boolean? | Must be true to charge |
mPosParameters | List<MerchantMigoDetail>? | Merchant configuration: the charge ids come from here |
mPosUserName / mPosUserEmail | String? | Terminal user details |
dashboardUrl | String? | URL of the associated dashboard |
externalId | String? | Your external identifier, if configured |
MerchantMigoDetailβ
Each element of mPosParameters:
| Field | Type | What it's for |
|---|---|---|
id | String? | The merchantDetailId in doTransaction |
terminalId | String? | The merchantTerminalId in doTransaction |
currencyInfoList | List<CurrencyMigoInfo>? | Enabled currencies; the first is the terminal's |
countryCode | String? | Country of the affiliation |
cardAcqId | String? | 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:
| Field | Type | What it's for |
|---|---|---|
isTransactionApproved | Boolean? | Check this first. If it isn't true, don't finalize |
authorizationMigoType | AuthorizationMigoType? | SALE β "approved"; VOID β "reversed" |
authorizationId | String? | Authorization code, required by doFinishTransaction |
responseCode | String? | Processor code ("14" on a VOID means the reversal failed) |
responseCodeDescription / reasonText | String? | Human-readable decline detail |
isSignatureNeeded | Boolean? | The transaction requires a signature |
isTransactionOfflineApproved | Boolean? | 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:
| Field | Type | What it's for |
|---|---|---|
_internalId | Int | The terminalPaymentId when voiding from history |
_signatureUrl | String? | Location of the stored signature, if any |
_signatureData | String? | The signature itself, to redraw it |
Relatedβ
- SDK Install β initialization and terminal activation.
- Process a Terminal Payment β the charge step by step.
- Cancel an in-progress charge β abort before authorization.
- Reverse an authorized charge β undo an approved charge.
- Error catalog β Migo backend codes.