Skip to main content

Gateway Android SDK

Overview

gateway-sdk-android has three package tiers:

  • com.myriad.gateway.sdk.android Standard Android wrapper for the plain Gateway admin/pay HTTP clients.
  • com.myriad.gateway.sdk.android.host The primary terminal/runtime SDK surface for apps that need to support both Nexgo and Tap to Pay without caring that SmartConnect exists internally.
  • com.myriad.gateway.sdk.android.referencehost Optional managed-host tooling for registration, heartbeat shaping, workspace snapshots, and operator-facing device-management flows.

Everything under com.myriad.gateway.sdk.android.smartconnect is internal implementation detail and should not be imported by app code.

Choose Your Path

HTTP-only Android app

Use:

  • GatewayAndroidConfig
  • GatewayAndroidClient

This is just the Android-friendly shell around the core Kotlin SDK.

Embedded terminal app

Use:

  • GatewayAndroidApp
  • GatewayAndroidHostRuntimeConfig
  • GatewayAndroidDeviceRuntimeConfig
  • GatewayAndroidHostState
  • GatewayAndroidUiState

This is the default integration path for a POS app that needs one API surface for both Nexgo and Tap to Pay.

Managed host / device-management app

Use referencehost only if the app also needs:

  • device registration payloads
  • heartbeat payloads
  • workspace snapshots
  • command or operator-facing host tooling

Primary types:

  • GatewayAndroidReferenceHost
  • GatewayAndroidReferenceHostLauncher
  • GatewayAndroidReferenceHostApp
  • GatewayAndroidDeviceManagementSurface

Core Concepts

GatewayAndroidHostRuntimeConfig

This is the base runtime wiring:

  • filesDir
  • transport
  • storage location strategy
  • terminal platform info collector
  • recovery backfill client
  • clock / operation id hooks
  • gateway name

The default terminalPlatformInfoCollector best-effort gathers Android device metadata for device-management payloads, so apps do not need to hand-build the full terminal profile just to register a device or send heartbeats.

GatewayAndroidDeviceRuntimeConfig

This is how the app declares device family:

  • GatewayAndroidDeviceFamily.NEXGO
  • GatewayAndroidDeviceFamily.TTP

That config resolves into GatewayAndroidDeviceRuntimeSelection, which keeps the selected runtime label and gateway name consistent.

GatewayAndroidApp

This is the main product surface.

It owns:

  • startup / reload
  • transaction execution
  • pending-operation recovery
  • offline server replay queue management
  • app snapshot/state projection

GatewayAndroidAppSnapshot

This is the “what should the app render right now?” model.

It includes:

  • runtime readiness
  • selected device family/runtime
  • recovery inspection
  • replay backlog state
  • terminal-device snapshot
  • device-management snapshot when applicable

GatewayAndroidTerminalPlatformInfo

This is now primarily an override model, not a required full payload.

The SDK auto-collects best-effort Android metadata for registration, heartbeat, and managed-host snapshots:

  • manufacturer
  • model
  • Android version
  • screen resolution
  • timezone
  • battery / charging status when available
  • network type when available

If the app wants to override specific fields, pass only those fields in GatewayAndroidTerminalPlatformInfo; the SDK merges them on top of the collected metadata.

GatewayAndroidHostState and GatewayAndroidUiState

Use these for app rendering:

  • GatewayAndroidHostState runtime truth: lifecycle, pending recovery, replay backlog, attention level
  • GatewayAndroidUiState app-facing banner and actionable recovery items

Storage and Key Material

The public bootstrap primitives are now real GatewayAndroid* types:

  • GatewayAndroidStoreLocationStrategy
  • GatewayAndroidDefaultStoreLocationStrategy
  • GatewayAndroidStoragePaths
  • GatewayAndroidKeyProvider
  • GatewayAndroidRootKeySource
  • GatewayAndroidDerivedKeyProvider
  • GatewayAndroidInitializer

That means app code no longer has to import SmartConnect-branded bootstrap types just to configure local storage or encryption keys. The static key/root-key fixtures live in the unpublished :gateway-sdk-android-testing library and are not part of the AAR; production key material is the Keystore-backed provider the managed entry point wires by default.

Managed Production Runtime Setup

Production hosts integrate through one approved entry point: GatewayAndroidApp.withManagedRuntime(...). Gateway Cloud selects the runtime family (NEXGO, TTP_NATIVE, TTP_NEARPAY); the SDK owns device enrollment (Play Integrity + Android Keystore proof-of-possession), credential storage/refresh, key material, and client authorization. The host never branches on the device family and never handles raw credential tokens.

import com.myriad.gateway.sdk.android.cardpresent.deviceauth.GatewayAndroidManagedCredentialConfig
import com.myriad.gateway.sdk.android.cardpresent.deviceauth.GatewayAndroidPlayIntegrityConfig
import com.myriad.gateway.sdk.android.host.GatewayAndroidApp
import com.myriad.gateway.sdk.android.host.GatewayAndroidHostCapabilities

// withManagedRuntime and ensureStarted are suspend functions — call them from a
// coroutine (e.g. lifecycleScope.launch { ... } at app start).
suspend fun startGateway(): GatewayAndroidApp {
    val app =
        GatewayAndroidApp.withManagedRuntime(
            host = GatewayAndroidHostCapabilities(applicationContext) { currentActivity },
            gatewayClient = gatewayClient, // backend-vended bearer tokenProvider
            credentialConfig =
                GatewayAndroidManagedCredentialConfig(
                    organizationId = "org_...",
                    playIntegrity =
                        GatewayAndroidPlayIntegrityConfig(
                            providerCloudProjectNumber =
                                BuildConfig.GATEWAY_SDK_PLAY_INTEGRITY_PROJECT_NUMBER,
                        ),
                ),
        ) // NearPay deployments just bundle gateway-sdk-android-nearpay — the SDK
        //   discovers its runtime module automatically when Gateway Cloud selects it

    val started = app.ensureStarted()
    if (started.canTakePayment) {
        // Render payment-ready UI.
    }
    return app
}

providerCloudProjectNumber is the public numeric project identifier for the Gateway SDK provider's Play Integrity project, not the consumer application's Firebase/Google Cloud project. The default GatewayAndroidPlayIntegrityConfig() is intentionally unset: NEXGO terminal attestation can still construct the managed runtime, while platform attestation fails closed until Gateway publishes this provider value. Do not read it from the host app's google-services.json, and do not put service-account keys or decoder credentials in the app.

canTakePayment reflects whether the current reader/runtime is available for a new attempt. Pending confirmation, reconciliation, and server-replay records remain visible through the recovery state and banners, but they do not lock an unrelated payment. A deterministic pre-dispatch failure is recorded as terminal; only an ambiguous failure after dispatch remains pending for reconciliation.

The SDK does not currently persist PAN, CVV, track data, or keyed-entry payloads for offline authorization. Encrypted post-approval server replay is not the same as offline card-data capture. Offline keyed-entry store-and-forward remains disabled until its PCI scope, acquirer authorization, retention, fraud controls, and certified UI contract are approved.

Managed Host Example

Managed-host tooling wraps an existing managed app — it is not a second way to construct a runtime:

import com.myriad.gateway.sdk.android.host.GatewayAndroidTerminalPlatformInfo
import com.myriad.gateway.sdk.android.referencehost.asReferenceHost

val referenceHost = app.asReferenceHost() // app from GatewayAndroidApp.withManagedRuntime(...)

val started = referenceHost.ensureStarted()
val registration = started.registrationRequest(deviceId = "device-123")

val managedHost =
    started.managedHostSnapshot(
        deviceId = "device-123",
        platformInfo = GatewayAndroidTerminalPlatformInfo(deviceName = "Front Counter"),
    )

Recovery Model

The Android runtime supports two operational recovery concepts:

  • pending-operation recovery
  • offline server replay queue flushing

It does not expose a fake offline terminal authorization mode. The public API is intentionally explicit about that boundary.

Key public types:

  • GatewayAndroidPendingOperation
  • GatewayAndroidRecoveryInspection
  • GatewayAndroidRecoveryResolution
  • GatewayAndroidRecoveryItem

Consumer dependencies

Choose one consumer path; do not combine these dependencies. JVM consumers use only gateway-sdk-core-kmp. Android consumers use gateway-sdk-android instead, and must not add gateway-sdk-core-kmp, because the self-contained Android AAR would duplicate com.myriad.gateway classes.

Android-core and SoftPOS implementation classes are embedded in gateway-sdk-android and must not be added separately. NearPay is optional: include gateway-sdk-android-nearpay only alongside the base Android artifact for the NearPay rail. Managed runtime discovery finds it when Gateway selects TTP_NEARPAY; do not add a separate NearPay repository.

Device authorization and readiness

Use the managed runtime's device credential provider. Never pass a device token as GatewayConfig.accessToken, persist raw tokens in host storage, substitute static test keys, or bypass platform attestation. Exposed runtime support does not establish network certification or account activation.

For a Gateway-managed NEXGO terminal, enrollment requires the exact organization, location, and enrolled terminal serial binding. A terminal bound elsewhere or an inactive/missing binding is not corrected by changing the request's identity. Escalate rejected enrollment to the authorized device-onboarding owner.

canTakePayment describes reader/runtime availability for a new attempt; pending confirmation and replay remain visible for reconciliation. It is not proof that an earlier transaction failed or permission to repeat it.

Gateway owns payment execution, device credentials and recovery state. Your app owns cart/order state, tender selection, receipts, localization, and displaying the returned readiness/recovery information. Do not import host.internal or smartconnect implementation classes. For a cloud terminal, see Android Bolt.