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 provisions | What it's for in the SDK |
|---|---|
| Migo account (tenant / merchant) | Your account inside the Migo platform |
| User | The authenticated user who owns the terminal β its id is the authUserId you pass to the SDK |
| Business | The business that operates the charges |
| Branch | Where terminals are registered β its id is the branchId you pass to the SDK |
merchantId and signature | The credentials the SDK authenticates with against the platform on every call |
| SDK repository credentials | JSON 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:
| Flavor | Environment | Base URL |
|---|---|---|
sandbox | QA / testing | https://api-qa.ali.app/rest |
prod | Production | https://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
minSdkmust be 29 or higher. compileSdkmust be 36 or higher β the SDK is compiled against that level and Gradle refuses to consume a library built with a highercompileSdkthan 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β
| Field | Type | Required | Notes |
|---|---|---|---|
mActivity | Activity | Yes | The Activity the SDK operates from |
uiMigoCallback | MigoSDKCallbacks | Yes | Receives every lifecycle event β see SDK Reference |
supportMcMaestro | Boolean | Yes | Enables Mastercard Maestro support |
sdkProvider | MigoProvider | Yes | Provider and currency for the integration β see table below |
merchantId | String | Yes | Business identifier used to authenticate against the platform |
signature | String | Yes | Secret signature that authenticates the requests |
authMigoCallback | AuthSDKCallbacks | Yes | Receives onAuthError(reason, description) if authentication fails |
authUserId | Int? | No* | Id of the user who owns the terminal β required to register/activate the terminal |
branchId | Int? | No* | Id of the branch the terminal is registered under β required to register/activate the terminal and to upload signatures |
onlyRestServices | Boolean | No | Defaults 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 |
appVersion | String? | No | Your 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:
| Value | Currency | Country |
|---|---|---|
MIGO_PAY | GTQ β Quetzal | Guatemala |
MIGO_LINK_GTQ | GTQ β Quetzal | Guatemala |
MIGO_LINK_HNL | HNL β Honduran lempira | Honduras |
MIGO_LINK_USD | USD β US dollar | El 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 theactiveTerminalflag and, when active,mPosParameterswith 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:
| Callback | What happened | What to do |
|---|---|---|
onAuthError(reason, description) | Invalid merchantId or signature. Arrives via authMigoCallback | Fix the credentials and call initService again. The SDK stays inoperative |
onCouldNotConnectService(reason, code) | Could not reach the platform | Retry; check connectivity |
onCouldNotValidateIntegrity(message) | The device is not secure (rooted or modified OS) | Block charging on that device |
onGeneralException(exception, message) | Unexpected error | See 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:
- It looks up the terminal by device β
GET /devices/users/{authUserId}/terminals/{deviceId}. - If it doesn't exist (
404), it creates it βPOST /devices/users/{authUserId}/terminalswith{ deviceId, branchId, notifyZendesk: true }. notifyZendesk: trueopens 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
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()
Relatedβ
- Process a Terminal Payment β run a card-present charge and settle it.
- SDK Reference β every method and callback, with their parameters.
- Overview β hardware topology, card scenarios, and PCI scope.