Check Tap to Pay feature boundaries
Do not assume that every gateway or reader feature is supported by the phone acceptance flow.
Compare supported operations
Capability iPhone / Android Tap to Pay Customer Vault tokenization Not supported by the documented Tap to Pay feature tables. Credential-on-file flags Not supported. Merchant-defined fields Not supported. Tipping Pass enabled TipAmount through the integration. Android online PIN Supported by default. Android linked refunds Use SaleReference; CardEaseReference is unsupported.
Configure before starting
Phone-only setup enables TapToMobilePOI and disables PaymentDevicePOI. A dual configuration exposes both choices but defaults to the external device. The source sequence diagrams separate those configurations; your app must select the intended POI for the attempt.
Follow the callback sequence
Initialize and set properties, observe configurationUpdate, wait for connectAndConfigureFinished readiness, then start the transaction. Observe transaction progress and final result. Android adds an Activity callback before its NFC prompt; iOS does not use Android Activity types. Show userNotification without a continuation request, and answer signature/application-selection callbacks only when requested.
Preserve registration and lifecycle state
Initial connection creates a POS identity; wiping app storage can register it again. getStatus exposes health; getTransactionInformation recovers an attempt; dispose releases resources and requires a fresh initialize. Do not infer payment outcome from registration or connectivity state.