mobile_reader_sdk library
Unified Flutter façade for the EasyMerchant mobile reader SDKs.
This is the new, contract-first public surface. The legacy entry
point package:easymerchant_reader_sdk/magteksdk.dart continues to work for
existing callers; this library exists alongside it.
See docs/architecture/flutter-contract.md and
docs/architecture/multi-reader-support.md for the contract
design.
Classes
- ArqcPayload
- EMV ARQC payload emitted for chip / contactless transactions.
- CardSummary
- Safe-to-display summary of a card.
- CertificatePinningConfig
- Configuration for optional TLS certificate pinning.
- CertificatePinningValidator
- Validates a CertificatePinningConfig.
- DefaultGatewayClient
- Default GatewayClient implementation backed by a provider-neutral GatewayTransport.
- DefaultGatewayClientFactory
- Default GatewayClientFactory that wraps the supplied transport in a DefaultGatewayClient. POS apps that need custom routing can provide their own factory.
- EncryptedReaderPayload
- Encrypted card-data payload emitted by the reader after a successful read.
- FakeGatewayClient
-
In-memory GatewayClient for the rare test that wants to
substitute the entire client (e.g. asserting that the SDK
gates on
notConfiguredbefore calling the client). - FakeGatewayClientFactory
- GatewayClientFactory that builds FakeGatewayClient instances. Useful when a test wants to inject a specific client into the gateway orchestrator.
- FakeGatewayResponses
- Pre-canned response builders for tests.
- FakeGatewayTransport
- In-memory GatewayTransport for unit / integration tests.
- GatewayClient
- Provider-neutral interface the SDK calls when it has an encrypted payload to hand off to the merchant backend.
- GatewayClientFactory
-
Factory the POS supplies in
gatewayHandoffmode. - GatewayConfig
- POS-supplied configuration for the gateway handoff layer.
- GatewayHandoffEvent
- Single event on the gateway-handoff stream.
- GatewayHandoffOrchestrator
-
Orchestrator that owns the gateway-handoff state machine
for one
MobileReaderSdkinstance. - GatewayHandoffResponse
- Provider-neutral response carried back from the merchant's gateway client.
- GatewayRetryPolicy
- Retry policy for handoff calls.
- GatewayTransactionRequest
- Normalized request the SDK hands to a GatewayClient when forwarding an encrypted payload to the merchant backend.
- GatewayTransactionRequestBuilder
- Helper that builds a GatewayTransactionRequest from the already-validated inputs the controller has at hand, enforcing the reader-metadata allow-list at construction time. Lives next to the model so the safe-fields contract is auditable in one file.
- GatewayTransactionResponse
- Response from the gateway (via em-api) for a single transaction attempt.
- GatewayTransport
- Provider-neutral HTTP transport interface used by the gateway-handoff layer.
- GatewayTransportRequest
- Single outbound HTTP request. Carries the encrypted payload in its body; the transport adapter MUST forward the body verbatim.
- GatewayTransportResponse
-
Result of a single transport call.
statusCodeis the HTTP status (200..599 typical); the gateway layer classifies the status into approve / decline / failure. - MethodChannelMobileReaderSdk
- Method-channel + event-channel backed implementation of MobileReaderSdk.
- MobileReaderChannels
- Platform-channel name and method-name constants used by the Dart-side adapter.
- MobileReaderSdk
- Unified Flutter façade for the EasyMerchant mobile card readers.
- NativeCoordinatorAdapter
- Adapter that routes transaction orchestration to the native Android/iOS runtime coordinator when available.
- ReaderCapability
- Capability flags describing what a reader / driver can actually do.
- ReaderConfig
-
Immutable configuration supplied by the POS app to
initialize(). - ReaderDevice
- A discovered or connected card reader.
- ReaderEvent
- A single event on the unified MobileReaderSdk.events stream.
- ReaderProfile
- Static description of a reader / driver combination.
- ReaderStatus
- Snapshot of the current SDK / reader state, returned by MobileReaderSdk.getStatus.
- RetryQueueStatus
- RuntimeHealthCheck
- RuntimeLogEvent
- SdkLogEntry
- SdkLogger
- SdkLogRedactor
- TransactionCoordinator
-
Bridges the Dart
MobileReaderSdk.startTransactionflow to the gateway-handoff contract. - TransactionCoordinatorConfig
- Configuration the POS supplies to a TransactionCoordinator.
- TransactionCoordinatorOutcome
- Outcome of one TransactionCoordinator.runTransaction call.
- TransactionRequest
- Immutable request describing one transaction to run on the reader.
- TransactionResult
-
Terminal result of one
startTransactioninvocation. - UnimplementedMobileReaderSdk
- Placeholder implementation used until the platform channels land.
- ValidationSession
Enums
- CardBrand
- Card brand reported by the reader / gateway. Lowercase short codes.
- EncryptedPayloadFormat
- Wire identifier for the format of the encrypted blob carried inside an EncryptedReaderPayload.
- EntryMode
- How a card was presented to the reader.
- GatewayErrorCode
- Stable wire identifiers for gateway-handoff failures.
- GatewayHandoffEventType
- Additive event-type identifiers for the gateway handoff layer.
- GatewayHandoffStatus
- Canonical gateway-handoff outcome, as observed by the SDK.
- GatewayMode
- Mode that controls how the SDK delivers an encrypted card payload to the merchant's backend.
- GatewayTokenScope
-
Discriminator the SDK passes to
GatewayConfig.authTokenProvider so the POS can vend the
right token for the right call. Today there is one scope
(
transactionHandoff); follow-up branches that add other backend interactions will extend this enum. - ReaderConnectionState
- Lifecycle state of the reader connection.
- ReaderConnectionType
-
Coarse-grained transport hint, retained for backwards
compatibility. New code should prefer the more granular
ReaderTransportcarried onReaderDevice.transport. - ReaderEnvironment
- Which em-api environment the SDK is talking to.
- ReaderErrorCode
- Stable, enum-like error codes for the unified reader contract.
- ReaderEventType
- Discriminator for ReaderEvent.
- ReaderLogLevel
- Log verbosity for the SDK's own log output.
- ReaderTransport
- Physical transport used to talk to the reader.
- ReaderVendor
- Vendor of a card-reader device.
- ReconnectState
- Reconnect lifecycle state surfaced through ReaderStatus.
- RuntimeHealthState
- SdkLogCategory
- SdkLogLevel
- TransactionCoordinatorOutcomeKind
- What kind of outcome the TransactionCoordinator produced.
- TransactionResultStatus
- Canonical outcome status of a transaction attempt.
- TransactionType
- Type of transaction to run against the gateway.
Constants
-
knownReaderProfiles
→ const List<
ReaderProfile> - Static registry of reader profiles the contract recognizes today.
Functions
-
profileForDriverId(
String driverId) → ReaderProfile? -
Look up a profile by
driverId. Returnsnullwhen no static profile maps to that driver - the POS may still attempt a generic flow against the rawReaderDevicefields. -
profileForVendorAndModelCode(
ReaderVendor vendor, String? modelCode) → ReaderProfile? -
Look up a profile by
vendor+modelCode. Useful when the driver id was not reported but the device announced its vendor and model. -
profilesForVendor(
ReaderVendor vendor) → List< ReaderProfile> - All known profiles for a given vendor (zero or more).
Typedefs
- ReaderEntryMode = EntryMode
- Provider-neutral entry mode the consumer presented the card with.
Exceptions / Errors
- GatewayError
- Structured error from the gateway-handoff layer.
- GatewayTransportError
- Transport-layer failure. Distinct from GatewayError because the latter is the gateway layer's canonical surface; this exception is what the transport adapter throws and what the gateway layer translates.
- ReaderError
- A structured error surfaced by the unified reader SDK.