Skip to main content
Migo Docs

SDK Install

Tap to Phone ships as an Android SDK that your app embeds. The SDK uses the phone's NFC reader to read the card present, talks to the Migo platform to create and settle the charge, and exposes the whole transaction lifecycle through callbacks β€” no dedicated POS hardware required. The entry point is the migoSDK object (package com.migo.sdkmigo.presentation).

:::info Device requirements The SDK is Android only (minSdk 29). An iOS version is not available yet. The device must have NFC and must not be rooted β€” the SDK validates integrity on initialization. :::

In four steps​

1. Add the repository and the dependency Gradle
2. Declare the permissions AndroidManifest.xml
3. Initialize with migoSDK.initService(...) merchantId + signature
4. Wait for terminal activation activeTerminal = true ──► ready to charge

Prerequisites​

Card-present charging relies on a hierarchy Migo provisions with you before you integrate. You don't register these entities via API; your commercial contact defines them:

What Migo provisionsWhat it's for in the SDK
Migo account (tenant / merchant)Your account inside the Migo platform
UserThe authenticated user who owns the terminal β€” its id is the authUserId you pass to the SDK
BusinessThe business that operates the charges
BranchWhere terminals are registered β€” its id is the branchId you pass to the SDK
merchantId and signatureThe credentials the SDK authenticates with against the platform on every call
SDK repository credentialsJSON key to download the SDK and its dependencies

The terminal itself is not provisioned up front: the SDK registers it automatically the first time it initializes on a new device (see Terminal registration and activation).

:::caution merchantId and signature are secrets The signature authenticates your business against the platform. Treat it as a credential: don't publish it in the repository or hardcode it. Load it from your build configuration (for example local.properties or a CI environment variable) or from your backend. :::

1. Add the repository and the SDK​

Migo gives you the SDK library and a JSON key with access to the private Maven repository that hosts its dependencies. Declare the repository in your Gradle build:

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 // the JSON key Migo gives you, base64-encoded
}
authentication {
basic(BasicAuthentication)
}
}
mavenCentral()
google()
}

Then add the Migo SDK library (com.migo.sdkmigo) as Migo distributes it for your integration.

Environment flavors​

The SDK publishes flavors that pin the platform base URL:

FlavorEnvironmentBase URL
sandboxQA / testinghttps://api-qa.ali.app/rest
prodProductionhttps://api.ali.app/rest

Use sandbox while integrating and switch to prod to go live.

Required build configuration​

# gradle.properties
android.enableJetifier=true

android.enableJetifier=true is mandatory: without it the Visa dependencies the SDK uses won't resolve and the build fails.

In addition:

  • Your app's minSdk must be 29 or higher.
  • compileSdk must be 36 or higher β€” the SDK is compiled against that level and Gradle refuses to consume a library built with a higher compileSdk than the app's.
  • Java compatibility is 1.8 (sourceCompatibility / targetCompatibility / jvmTarget).

:::note Your app identifier must match Your application's package name and version must be the same ones you registered with Migo when the SDK project was created. If they don't match, authentication fails and the SDK won't connect. :::

2. Permissions​

The SDK needs these permissions in your AndroidManifest.xml (NFC is the critical one for card present):

<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" />

The SDK does not request runtime permissions: request them yourself from your app before initializing. POST_NOTIFICATIONS in particular is left to you β€” the SDK never asks for it.

3. Initialize the SDK​

Initialize the SDK once, passing an InitServiceParams with your credentials, your MigoSDKCallbacks implementation (the transaction lifecycle events), and your AuthSDKCallbacks implementation (authentication errors).

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, // your Activity
uiMigoCallback = migoCallbacks, // your MigoSDKCallbacks implementation
supportMcMaestro = true,
sdkProvider = MigoProvider.MIGO_PAY,
merchantId = MIGO_MERCHANT_ID, // credential provided by Migo
signature = MIGO_SIGNATURE, // credential provided by Migo
authMigoCallback = object : AuthSDKCallbacks {
override fun onAuthError(reason: String, description: String) {
// invalid credentials or expired signature β€” the SDK stays inoperative
}
},
authUserId = userId, // id of the provisioned user
branchId = branchId, // id of the provisioned branch
appVersion = BuildConfig.VERSION_NAME
)
)

initService returns no value: every result arrives through callbacks.

InitServiceParams fields​

FieldTypeRequiredNotes
mActivityActivityYesThe Activity the SDK operates from
uiMigoCallbackMigoSDKCallbacksYesReceives every lifecycle event β€” see SDK Reference
supportMcMaestroBooleanYesEnables Mastercard Maestro support
sdkProviderMigoProviderYesProvider and currency for the integration β€” see table below
merchantIdStringYesBusiness identifier used to authenticate against the platform
signatureStringYesSecret signature that authenticates the requests
authMigoCallbackAuthSDKCallbacksYesReceives onAuthError(reason, description) if authentication fails
authUserIdInt?No*Id of the user who owns the terminal β€” required to register/activate the terminal
branchIdInt?No*Id of the branch the terminal is registered under β€” required to register/activate the terminal and to upload signatures
onlyRestServicesBooleanNoDefaults to false. When true it initializes only the REST layer and skips the native payment provider: useful if your integration doesn't use NFC/card present
appVersionString?NoYour app's version (for example "1.4.0"). Attached to reconciliation tickets to identify which version made the transaction

* They are optional in the signature, but if they are missing (or <= 0) the SDK cannot create or activate a new terminal, and handwritten signatures are not uploaded. Always pass them for card-present charges.

MigoProvider values​

sdkProvider defines which native provider is used and which currency the integration operates in:

ValueCurrencyCountry
MIGO_PAYGTQ β€” QuetzalGuatemala
MIGO_LINK_GTQGTQ β€” QuetzalGuatemala
MIGO_LINK_HNLHNL β€” Honduran lempiraHonduras
MIGO_LINK_USDUSD β€” US dollarEl Salvador

Your Migo contact tells you which one matches your integration.

What arrives after initializing​

During initialization your MigoSDKCallbacks receives, in order:

  • onConnectingService() β€” the SDK starts connecting to the platform. Show a loading indicator.
  • onServiceConnected(terminalData) β€” connected. terminalData (TerminalMigoData) carries the terminal configuration, including the activeTerminal flag and, when active, mPosParameters with the merchant and terminal identifiers you'll use to charge.
  • onDeviceIdResponse(deviceId) β€” unique identifier of the device (the physical terminal).
private var terminal: TerminalMigoData? = null

override fun onServiceConnected(terminalData: TerminalMigoData?) {
terminal = terminalData
if (terminalData?.activeTerminal == true) {
// ready to charge: mPosParameters carries merchantDetailId and merchantTerminalId
} else {
// activation pending β€” cannot charge yet
}
}

:::warning Only charge when the terminal is active Don't call doTransaction until onServiceConnected delivers terminalData.activeTerminal == true. Save the whole terminalData: the identifiers the charge needs come from it. :::

Failure flows during initialization:

CallbackWhat happenedWhat to do
onAuthError(reason, description)Invalid merchantId or signature. Arrives via authMigoCallbackFix the credentials and call initService again. The SDK stays inoperative
onCouldNotConnectService(reason, code)Could not reach the platformRetry; check connectivity
onCouldNotValidateIntegrity(message)The device is not secure (rooted or modified OS)Block charging on that device
onGeneralException(exception, message)Unexpected errorSee the catalog in SDK Reference

4. Terminal registration and activation​

The terminal is not provisioned up front. When the SDK connects and detects that this device's terminal is new or inactive (terminalData.activeTerminal == false), and it has valid authUserId and branchId, it registers it automatically:

  1. It looks up the terminal by device β€” GET /devices/users/{authUserId}/terminals/{deviceId}.
  2. If it doesn't exist (404), it creates it β€” POST /devices/users/{authUserId}/terminals with { deviceId, branchId, notifyZendesk: true }.
  3. notifyZendesk: true opens a support ticket requesting activation of the terminal (in Guatemala, via Zendesk).

While the ticket is pending, the terminal exists but cannot take card-present charges. Once Migo activates it, on the next connection terminalData.activeTerminal arrives as true and mPosParameters carries the merchant id and terminalId the charge needs.

initService()
└─ onServiceConnected(terminalData)
β”œβ”€ activeTerminal == true ──► ready to charge (see Process a Terminal Payment)
└─ activeTerminal == false ──► the SDK creates the terminal (notifyZendesk=true)
└─ activation ticket (Guatemala) ──► Migo activates ──► ready to charge
note

The settlement vehicle for charges (card, bank account, or balance) is defined with your commercial contact when the terminal is activated. See Settlement.

Multiple terminals per branch​

A branch can run more than one terminal. Each Android device has its own deviceId and therefore its own terminal under the same branchId. Install the SDK on additional devices and each one registers and activates separately.

Unlinking the device​

migoSDK.deactivate() unlinks the device from the native payment provider. Use it on sign-out or when decommissioning the device; after calling it you must initialize again to charge.

:::caution MIGO_LINK only deactivate() is only implemented on MIGO_LINK_* integrations. On MIGO_PAY the call does nothing. :::

migoSDK.deactivate()