Android Payment Interface

This page describes the current card-payment boundary in the Android POS app. The app no longer selects a provider-specific PaymentInterface implementation from a (GatewayName, DeviceType) factory. It consumes a terminal payment configuration, activates the Gateway SDK, and exposes that SDK through GatewayPaymentRuntime.

Runtime flow

management-api payment configuration
        │
        ▼
terminal-api configuration and Gateway SDK activation
        │
        ▼
ProvisioningManager → PaymentInterfaceConfig
        │
        ▼
PaymentViewModel → createPeakGatewayPaymentRuntime(...)
        │
        ├─ CASH_ONLY or incomplete configuration → operator-visible unavailable runtime
        └─ PEAK_GATEWAY + accepted device link + activation + Activity
             → LazyGatewaySdkPaymentRuntime
             → GatewaySdkPaymentRuntime
             → gateway-sdk-android / gateway-sdk-android-nearpay

The source boundaries are:

Boundary	Current owner	Source
Gateway and device enums	Android	apps/android/app/src/main/java/com/myriad/pinpointpos/payment/PaymentInterfaces.kt
Configuration fetch and SDK activation	Android	apps/android/app/src/main/java/com/myriad/pinpointpos/network/ProvisioningManager.kt
Runtime contract	Android	apps/android/app/src/main/java/com/myriad/pinpointpos/payment/GatewayPaymentRuntime.kt
Managed SDK runtime	Android	apps/android/app/src/main/java/com/myriad/pinpointpos/payment/gateway/GatewaySdkPaymentRuntime.kt
SDK credential and device-source mapping	Android	apps/android/app/src/main/java/com/myriad/pinpointpos/payment/gateway/GatewaySdkTransitionalSources.kt
Configuration validation and normalization	management-api	apps/microservices/management-api/src/main/java/com/myriad/management_api/service/TerminalGatewayConfigSupport.kt
SDK activation, credential storage, and revocation	terminal-api	apps/microservices/terminal-api/src/main/java/com/myriad/terminal_api/service/GatewaySdkActivationService.kt

GatewayName has two values: PEAK_GATEWAY and CASH_ONLY. DeviceType currently accepts Nexgo, Landi, Android, IOS, N62, N92, and TapToPay. A device type identifies the payment-device arrangement; it is separate from Android's peripheral DevicePlatform detection for printers, scanners, card readers, and cash drawers.

Supported payment-device arrangements

management-api normalizes the operator's selection before Android receives it.

Configured device	Current card-present arrangement	Required boundary
Nexgo, N62, or N92	Nexgo Smart POS on the same Android terminal, using the SDK intent_request path	A terminal serial number is required. Native Tap to Pay options are rejected.
Landi or Android	NearPay native Tap to Pay by default	Gateway SDK activation and an Android Activity host are required.
Landi or Android with Nexgo pairing	External Nexgo Smart POS over TCP	Pairing mode, paired Nexgo serial, and valid Smart Connect network options are required.
TapToPay	Native NearPay unless explicitly configured as an external Nexgo pairing	Smart Connect options are rejected for the native arrangement.
IOS	External Nexgo Smart POS only	The shared server schema accepts this for iOS clients; native iOS Tap to Pay is not exposed by this Android runtime.
CASH_ONLY	No card runtime	Card attempts return an operator-facing unavailable result; cash checkout remains available.

Do not infer transport from DeviceType alone. The normalized options (paymentSource, paymentDeviceClass, paymentDeviceKind, paymentDeviceConnectionMode, pairing values, and serial values) are the authoritative arrangement. PaymentDeviceLinkState and withPaymentDeviceLinkAdmission prevent a configured terminal from taking payments through a missing or mismatched link.

Runtime capabilities

A ready GatewaySdkPaymentRuntime owns the Gateway reporting side of card effects and implements:

• sale, authorization, and refund through the managed card-present app;
• tip adjustment and void, including a Gateway lookup when the void result is uncertain;
• manual keyed sale and reconciliation when the activation is authorized and a Gateway location is present;
• delayed-payment recovery, pending-operation recovery, and offline-server replay acknowledgement;
• device-scoped keyed-sale idempotency; and
• runtime status and recovery snapshots for operator support surfaces.

Batch listing and close are not SDK runtime operations. Android uses Terminal API batch endpoints through BatchViewModel; settlement authority remains behind Terminal API and Gateway.

The Android app also records the POS transaction through its backend boundary. A processor approval is not treated as sufficient POS persistence evidence: unresolved effects and replay work remain visible until the local/backend and Gateway records are reconciled.

Configuration and activation

PaymentInterfaceConfig carries gatewayName, deviceType, environment, and normalized options. Although compatibility fields such as apiKey and appIdentifier remain in the DTO, the managed runtime uses short-lived Gateway SDK device credentials obtained through terminal mTLS activation. Do not introduce a long-lived credential in app resources, logs, screenshots, documentation, or support tickets.

Activation requires all of the following:

1. The terminal has a valid PEAK_GATEWAY payment configuration.
2. The store is operationally bound to Gateway.
3. The payment-device link is accepted.
4. Android completes the activation challenge/attestation flow through Terminal API.
5. The runtime has an Activity host.

The runtime remains unavailable, with an actionable reason, when any gate is missing. A missing or unrecognized gatewayName is deliberately parsed as CASH_ONLY with paymentConfigurationMissing diagnostics; this keeps cash usable but is not a silent card fallback. Activation or device-link failures also do not fall back to an older direct Smart Connect implementation.

Nexgo activation may use Nexgo-specific terminal attestation. Other Android devices use the Gateway Android attestation provider selected by ProvisioningManager. Firebase App Check is a separate application-auth boundary and must not be substituted for Gateway SDK activation.

Change checklist

When adding or changing a payment-device arrangement:

1. Update the shared server DTO and TerminalGatewayConfigSupport validation/normalization first.

2. Update Android parsing, device-link derivation, and SDK source mapping together.

3. Preserve CASH_ONLY, missing-configuration, activation-failure, and mismatch behavior.

4. Add contract coverage for the normalized arrangement and for runtime recovery/idempotency behavior.

5. Validate with focused Bazel targets, for example:

   bazel test \
     //apps/android/app/src/test:gateway_sdk_transitional_sources_test \
     //apps/android/app/src/test:gateway_status_test \
     //apps/android/app/src/test:payment_test \
     //apps/android/app/src/test:gateway_sdk_activation_models_test

6. Build the applicable release APK and perform the hardware-specific card smoke before declaring a device arrangement supported. JVM tests prove mapping and recovery contracts; they do not prove a processor, NearPay, Nexgo, or physical terminal transaction.