Gateway SDK Capability Matrix

This page maps the Gateway SDK artifacts to their current monorepo consumers and ownership boundaries. It intentionally does not copy a release number: GATEWAY_SDK_CORE_VERSION, GATEWAY_SDK_VERSION, and GATEWAY_SDK_IOS_VERSION in MODULE.bazel are the dependency source of truth.

Published artifacts

Artifact	Current monorepo use	Version source
com.myriad.gateway:gateway-sdk-core-kmp	Typed admin/pay clients, models, webhooks, Gateway errors, and shared server/KMP contracts	GATEWAY_SDK_CORE_VERSION in MODULE.bazel
com.myriad.gateway:gateway-sdk-android	Managed Android card-present runtime and activation/device-credential APIs	GATEWAY_SDK_VERSION in MODULE.bazel
com.myriad.gateway:gateway-sdk-android-nearpay	NearPay implementation used by Android native Tap to Pay	GATEWAY_SDK_VERSION in MODULE.bazel
Gateway Apple/XCFramework package	iOS application integration	GATEWAY_SDK_IOS_VERSION and the iOS lane validator

The Maven repository and lock file are declared in MODULE.bazel; Android aliases are in apps/android/app/src/main/BUILD.bazel. The app must depend on both Android artifacts when NearPay is enabled. Server services use the core KMP artifact and must not depend on the Android artifact.

Snapshot/dev identifiers may intentionally differ between core and Android artifacts. Update the constants, lock file, activation request constant, and mobile/iOS lane contracts as one reviewed dependency change. Documentation is never the place to pin or advance the version.

Service ownership

There is no platform-wide fallback or "house" Gateway client. libs/microservices/gateway-client resolves GatewayAdminClient and GatewayPayClient from the owning root agent's credential tree. Missing org/store/merchant attribution or credentials is a hard error, not permission to use another tenant's client.

Capability	Current owner	Primary implementation
Root-agent credential resolution and per-org/per-agent client construction	Shared server library; credentials administered by management-api	libs/microservices/gateway-client, management-api/.../gateway/AgentGatewayClientResolver.kt
Agent hierarchy, app authorization, organization and location administration	management-api	GatewayAgentDirectory.kt, GatewayOrganizationService.kt, GatewayLocationAssignmentService.kt
Store-to-Gateway binding lifecycle	management-api	GatewayStoreBindingService.kt, GatewayStoreBindingLifecycleCoordinator.kt
Gateway provisioning jobs and settlement configuration	management-api	ManagementGatewayService.kt, Gateway provisioning/settlement controllers
Card-present device claim/provision/revocation and hosted manual charge/refund support	management-api	GatewayCardPresentDeviceClient.kt, GatewayCardPresentDeviceProvisioningService.kt, GatewayHostedManualChargeService.kt, GatewayRefundClient.kt
Product twin synchronization	merchant-api	gateway/product/GatewayProductApi.kt, GatewayTwinSyncSupport.kt
Store tax configuration and tax calculation	merchant-api	TaxConfigService.kt, TaxCalculationService.kt
Merchant checkout sessions, gift cards, portal token exchange, and unified Gateway transaction reads	merchant-api	GatewayCheckoutSessionClient.kt, CheckoutGiftCardGatewayClient.kt, gateway/portaltoken, gateway/joinlayer
Public checkout-session and wallet/gift-card reads	customer-api	GatewayCheckoutSessionClient.kt, WalletGiftCardResolver.kt
Terminal SDK activation and device enrollment	terminal-api	GatewaySdkActivationService.kt, gateway/activation/GatewayDeviceEnrollmentClient.kt
Terminal gift cards, transaction validation/sync, refunds, and batch settlement reads/close	terminal-api	GatewayGiftCardsClient.kt, GatewayTransactionValidationService.kt, gateway/sync/GatewaySyncService.kt, GatewayBatchService.kt
Batch export and Gateway/POS correlation checks	tx-bundler	GatewayBatchExportClient.kt, GatewayCorrelationIntegrityService.kt
Card-present sale/auth/refund, tip adjust, void, keyed entry, and recovery	Android POS	payment/gateway/GatewaySdkPaymentRuntime.kt

Controllers and portals expose Peak-owned DTOs. Gateway SDK model types stay behind service clients and adapters rather than becoming the public API contract.

Client and capability matrix

Client surface	Admin client	Pay client	Android managed runtime
Organizations, locations, agents, credentials, provisioning, settlements	Yes	No	No
Store-scoped tax configuration	Yes, resolved from owning Gateway merchant/location	No	No
Product administration/synchronization	Yes, through the merchant-owned facade	No	No
Checkout sessions, gift cards, transactions, keyed payment reconciliation	No	Yes	Some operations also exposed through the runtime as described below
Card-present device activation/claim/enrollment	Admin/control-plane APIs	Device-authorized pay client after activation	Yes
Card-present sale, authorization, refund, tip adjust, and void	No direct terminal effect	Used for transaction lookup/reconciliation	Yes
Offline/pending card recovery and replay acknowledgement	No	Transaction lookup where required	Yes
Webhook signature/model handling	Core SDK where the event is modeled	N/A	N/A

The Android runtime requires a valid payment-device link, terminal mTLS activation, managed device credentials, and an Activity host. It supports same-device Nexgo Smart POS, native Android NearPay, and paired external Nexgo arrangements according to normalized terminal configuration. See Android Payment Interface for the device matrix and fallback behavior.

Known boundaries

• Gateway owns processor/card effects. POS services own authorization, commerce context, local transaction state, receipt behavior, and reconciliation visibility.
• Gateway transaction success does not by itself prove that the POS transaction was persisted. Android and the backend retain recovery/idempotency evidence until both sides are reconciled.
• Terminal batch close goes through terminal-api; Android does not settle a batch directly through the SDK runtime.
• The store binding selects the owning agent credential context. Never substitute a root or merchant credential because it happens to authenticate.
• Supported webhook event classes use the SDK verifier/model. Agent and app-authorization event payloads that are not in the SDK's sealed event hierarchy use the explicit management adapter and HMAC contract; do not force-deserialize them as a supported SDK event.
• SDK device credentials, OAuth client secrets, activation tokens, attestation material, PAN/CVV, and webhook secrets must not be logged or copied into documentation. Keyed-entry card data is passed only to the authorized runtime call and must not cross the normal application telemetry boundary.
• apiKey/appIdentifier compatibility fields in terminal payment DTOs are not a license to restore long-lived app credentials.

Dependency and contract verification

Use Bazel so tests consume the same resolved artifacts as applications:

bazel test //libs/sdks:generated_sdk_contract_drift_test
bazel test \
  //apps/microservices/management-api:core_test \
  //apps/microservices/merchant-api:core_test \
  //apps/microservices/customer-api:core_test \
  //apps/microservices/terminal-api:core_test \
  //apps/microservices/tx-bundler:core_test
bazel test \
  //apps/android/app/src/test:gateway_sdk_transitional_sources_test \
  //apps/android/app/src/test:gateway_sdk_payment_runtime_cancellation_test \
  //apps/android/app/src/test:gateway_pending_recovery_test

Run only the targets affected by a focused change; a dependency release should run the full matrix above plus the applicable APK/XCFramework build and real device/payment smoke. Compilation proves API compatibility, not live processor authorization, device activation, or hardware behavior.

If Artifact Registry returns 401/403, load the approved Gateway Maven credentials with scripts/gateway-maven-credentials.sh and retry. Do not put repository credentials in .bazelrc, source files, command output, or this page.