Tap to Pay on Android

Set up app through Google Play

When distributing the application through Google Play, we recommend limiting the store listing visibility to devices that pass strong integrity checks.

Google Play can verify that devices pass integrity checks before the store listing is made visible to users. Enable this feature to limit your app's distribution to unreliable or unknown devices. This will not affect the app's Google Play discoverability or search ranking.

1. Log in to Google Play Console
2. Navigate to Release > App Integrity > Store listing visibility
3. Enable Strong integrity checks

This process prevents installation on compromised devices that could pose security risks.

Register application

Applications must be registered with Moov to be authorized to use our Tap to Pay SDK. The process for application registration is as follows:

1. Create a terminal application via the POST terminal application endpoint.

curl -X POST "https://api.moov.io/terminal-applications" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  --data '{
    "platform": "android",
    "packageName": "com.example.app",
    "sha256Digest": "AA:BB:CC:DD:EE:FF:AA:BB:CC:DD:EE:FF:AA:BB:CC:DD:AA:BB:CC:DD:EE:FF:AA:BB:CC:DD:EE:FF:AA:BB:CC:DD",
    "versionCode": "20332277"
}'

2. The application will move from pending to enabled once approved. You can subscribe to the terminalAppRegistration.updated webhook to be notified of the status updates.

3. Once the application is enabled, you must link the app's terminalApplicationID to a merchant account via the link POST terminal application endpoint.

curl -X POST "https://api.moov.io/accounts/{accountID}/terminal-applications" \
  -H "Authorization: Bearer {token}" \
  --data '{
    "terminalApplicationID": "string"
  }'

4. When a new version of the application is published to Google Play, register this version via the terminal applications version endpoint POST /terminal-applications/{terminalApplicationID}/versions.

See the Android developer docs for more information on app versioning.

curl -X POST "https://api.moov.io/terminal-applications/{terminalApplicationID}/versions" \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "version": "20440059"
  }'

Add the SDK to your project

The Android SDK is published to Maven Central as io.moov:android-sdk. It depends on MyPinPad's terminal and EMV libraries, which are hosted in MyPinPad's private Maven repository. Gradle cannot resolve the SDK until the private Maven repository and its credentials are configured.

Contact Moov support at support@moov.io to obtain a username and access token for MyPinPad's Maven repository.

1. Store the credentials outside your source tree, either in ~/.gradle/gradle.properties or as the MPP_PACKAGES_USERNAME and MPP_PACKAGES_TOKEN environment variables. Do not commit them to version control.

# ~/.gradle/gradle.properties
mppPackagesUsername=<username from Moov support>
mppPackagesToken=<token from Moov support>

2. Declare MyPinPad's repository alongside Google and Maven Central in settings.gradle.kts.

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven {
      url = uri("https://maven.pkg.github.com/myPinPad/*")
      credentials {
        username = providers.gradleProperty("mppPackagesUsername")
          .orElse(providers.environmentVariable("MPP_PACKAGES_USERNAME"))
          .get()
        password = providers.gradleProperty("mppPackagesToken")
          .orElse(providers.environmentVariable("MPP_PACKAGES_TOKEN"))
          .get()
      }
    }
  }
}

3. Add the SDK to your app module's build.gradle.kts using the latest version from Maven Central. The SDK uses types such as MID from Moov's Kotlin SDK in its public API, but does not declare that dependency, so you will need to add it. Android SDK 0.26.2 is built against Kotlin SDK 0.8.0.

android {
  defaultConfig {
    minSdk = 29
  }
}

dependencies {
  implementation("io.moov:android-sdk:<version>")
  implementation("io.moov:kotlin-sdk:0.8.0")
}

Initialize SDK

SDK initialization requires MoovSDK.onApplicationCreated to be called in the app's Application.onCreate method. Additionally, MoovSDK.isApplicationProcess should be used to determine whether or not the app should proceed with any initialization logic in its onCreate method.

onApplicationCreated takes an SDKLogger, which receives log lines for debugging failed taps. These lines never contain PCI or PII data. Include them when reporting production tap issues to Moov support.

class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()

    // initialize the Moov SDK
    MoovSDK.onApplicationCreated(this, SDKLogger { line -> Log.d("MoovSDK", line) })

    // return if not being called from the main process
    if (!MoovSDK.isApplicationProcess()) {
      return
    }

    // proceed to initialize the app
  }
}

Create terminal

The main entry point is a factory method: MoovSDK.createTerminal. This initializes a terminal instance which ensures a secure environment. This method should be called as early in the application's lifecycle as is practical, as it may take a significant amount of time to complete the device attestation.

Pass it the terminal configuration returned by the get terminal application configuration endpoint. Fetch the configuration from your backend. createTerminal returns a TerminalCreationResult. On success, TerminalCreationResult.Created holds the Terminal. Other results describe why creation failed, such as a failed device attestation.

val terminalConfig = fetchTerminalConfig() // fetch the terminal config from your backend
val terminal = when (val result = MoovSDK.createTerminal(applicationContext, terminalConfig)) {
  is TerminalCreationResult.Created -> result.terminal
  else -> return // handle the failure
}

Call terminal.dispose() when the app no longer needs the terminal, for example when the user leaves the area of the app that accepts taps. You do not need to dispose of the terminal when the app moves to the background.

Refresh the terminal configuration

Terminal configurations expire. Fetch a fresh configuration rather than caching one indefinitely.

If the configuration has expired, createTerminal returns TerminalCreationResult.TerminalConfigurationExpired. Fetch a new configuration and call createTerminal again.

To refresh before that happens, read Terminal.configurationExpiresAt while the terminal is idle. It is null for sandbox terminals, in which configurations do not expire.

val expiresAt = terminal.configurationExpiresAt
if (expiresAt != null && Instant.now().isAfter(expiresAt.minus(Duration.ofHours(2)))) {
  // refresh during a quiet moment rather than with a customer waiting
}

If the configuration expires while the app is running, createTapAuthorization and createTapTransfer emit TapAuthorizationError.ConfigurationExpired without reading a card. The terminal cannot be reused. Dispose of it, create a new terminal from a fresh configuration, and authorize again. Creating a terminal repeats device attestation, so refreshing ahead of time keeps a customer from waiting on it.

The SDK holds the configuration in memory only. After process death, or a long period in the background, call createTerminal again.

Accept a payment

Creating an EMV authorization will grab exclusive access to the device's NFC reader, allowing tap of an EMV card. Both paths below return a Kotlin Flow of events. UiMessageEvent values, such as PresentCard and RemoveCard, tell you what to display to the customer during the tap.

Amounts are a TapAmount in the smallest currency unit. For example, 100uL is $1.00 USD. To record a tip or surcharge, set TapAmount.tip or TapAmount.surcharge. Both are portions of amount, not additions to it, and together they cannot exceed amount. A surcharge requires the merchant to be enabled for surcharging, otherwise the flow emits TapAuthorizationError.SurchargeNotEnabled.

TapAmount(
  amount = 1150uL, // 1000 base + 100 tip + 50 surcharge
  currency = Currency.getInstance("USD"),
  tip = 100uL,
  surcharge = 50uL,
)

There are two main paths to accept EMV payments:

• Directly create a transfer from the SDK
• Create an authorization via the SDK and create the transfer separately

lifecycleScope.launch {
  terminal.createTapTransfer(
    CreateTapTransferParams(
      tapAuthorizationParams = TapAuthorizationParams(
        tapAmount = TapAmount(
          amount = 100uL,
          currency = Currency.getInstance("USD"),
        ),
        customerAccountId = MID("962aa592-5993-49d6-ae54-d6d6ab917c66"),
      ),
      partnerAccountId = MID("fd35bc72-fa52-4fef-a0f5-f99fa1280aeb"),
      merchantAccountId = MID("3c1a3d1e-0f3c-4a5e-9a3e-6c2f0b7c5d11"),
      destinationPaymentMethodId = MID("19a76ccb-be73-4394-a9ca-701c0a20fd8a"),
      description = "Moov T-shirt",
    )
  ).collect { event ->
    when (event) {
      is UiMessageEvent -> showMessage(event)
      is CreateTransferEvent.Success -> Log.d("MoovSDK", "Transfer created: ${event.transfer}")
      else -> Log.d("MoovSDK", "Event: $event")
    }
  }
}

lifecycleScope.launch {
  terminal.createTapAuthorization(
    TapAuthorizationParams(
      tapAmount = TapAmount(
        amount = 100uL,
        currency = Currency.getInstance("USD"),
      ),
      customerAccountId = MID("962aa592-5993-49d6-ae54-d6d6ab917c66"),
    )
  ).collect { event ->
    when (event) {
      is UiMessageEvent -> showMessage(event)
      is AuthorizationResultEvent.TransactionAuthorized -> {
        // now, create the transfer externally using event.token as the source
      }
      else -> Log.d("MoovSDK", "Event: $event")
    }
  }
}