iOS SDK Update guide

This section describes the update between different versions of the SDK.

Update from 1.10.x to 1.11.0

Dependency Management
OpenSSL and TrustKit are no longer required dependencies. If you were including them manually in your project, you can now safely remove them.

Simplified Initialization
The initialization method has been simplified. Integrators no longer need to provide mTLS certificates and passcodes manually. The SDK now handles these internally.

Before:

public func initialization(
    environment: Environments,
    certData: String? = nil,
    certPasscode: String? = nil,
    authCertData: String? = nil,
    authCertPasscode: String? = nil,
    appVersion: String? = nil,
    language: TapOnMobileLanguage? = nil
) -> AnyPublisher<Result<Success, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 130 Before

After:

public func initialization(
    environment: Environments,
    appVersion: String? = nil,
    language: TapOnMobileLanguage? = nil
) -> AnyPublisher<Result<Success, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 131 After

Request Location

The requestLocation() method now returns a publisher. This allows the integrator to be notified if the request was successful or if it failed (e.g., due to the SDK not being initialized).

Before:

public func requestLocation() {
    // implementation here
}

Code block 132 Before

After:

public func requestLocation() -> AnyPublisher<Result<Success, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 133 After

Updated Error Handling

The AuthError enum has been removed. All authentication and registration errors are now mapped to SessionError or CommonError for better consistency.

Reference Validation Update

The referenceMaxLength property is no longer used. Integrators must now use the referencePattern (regex) provided in DynamicProperties for client-side validation.

UI Container Removal in APM Refunds
The container and paymentSolutionReceiptHandling parameters have been removed from doQRRefund and doBlikRefund. These methods now operate solely as background processes, and integrators are responsible for managing the UI during these specific refund flows.

Before:

public func doQRRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doBlikRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 134 Before

After:

public func doQRRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doBlikRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 135 After

Update from 1.10.0 to 1.10.1/1.10.2/1.10.3/1.10.4

TransactionHistoryItems model update

The field "cardType" is now an optional string.

Update from 1.9.0 to 1.10.0

Objective-C Compatibility
Version 1.10.0 introduces updates for Objective-C support. If your project is written in Objective-C, you can now use the TapOnMobileSDK_Objc package and update to the most recent changes.

Enhanced Refund Verification

The doRefund method now includes an optional terminalCode parameter. This is required for specific acquirers who have configured secondary verification in the merchant portal.

Expanded Transaction Filtering
The fetchTransactionsDetails method has been upgraded to support filtering by external references and specific terminal IDs.

• Breaking Change: At least one of transactionId or reference must be provided.

MTLS Security Enhancements

The SDK now utilizes Elliptic Curve (EC) certificates for MTLS, providing higher security with smaller key sizes. The internal renewal logic now attempts EC renewal first, falling back to RSA 2048 if necessary. This change is handled internally but ensures better compatibility with modern infrastructure.

Initialization Update (getInfoInit)
The getInfoInit method now requires a mandatory parameter to indicate if the call is being made before or after the user login.

• Old: public func getInfoInit() -> ...
• New: public func getInfoInit(isBeforeLogin: Bool) -> ...

New Error Codes

The CommonError enum has been expanded:

• .invalidPassword: Returned when a secondary verification password (like terminal code) is incorrect.
• .readerBusyWarning: A non-fatal warning indicating the card reader is temporarily busy.
• .missingRequiredFilterParameter: Returned by fetchTransactionsDetails if no identifier is provided.
• .mtlsError: Indicates that the MTLS check failed.

Cleanup of Deprecated Methods
The method getLastPrepareDeviceCompleted() has been removed. Developers should use the PrepareDeviceListener (introduced in 1.9.0) to track the exact completion time and state of device preparation.

Update from 1.8.0 to 1.9.0

Dependency Migration (SPM)

Version 1.9.0 consolidates all libraries via Swift Package Manager.

• Action: Remove manually linked .xcframework files for Lottie, MastercardSonic, VisaSensoryBranding, and TapOnMobileSDKLogger.
• Action: Add the TapOnMobileSDKDependencies package to your project targets.

Architectural Change: prepareDevice
The prepareDevice functionality has transitioned from a Combine Publisher to a Listener-based pattern.

• Result change: public func prepareDevice() now returns void.
• New requirement: Implement the PrepareDeviceListener protocol.

For more information, review dedicated section for [Prepare Device]111).

Initialization & Language Updates

The SDK now supports localized UI strings during initialization and at runtime.

• Initialization: initialize(...) now includes an optional language: TapOnMobileLanguage parameter.
• Runtime: Use updateLanguage(language: TapOnMobileLanguage) to change the SDK's UI language without re-initializing.

New Functionalities

• Support Number: Use loadSupportNumber() to retrieve the environment-specific support phone number.
• Transaction Counts: Use fetchTransactionsCount(...) for paginated transaction metadata.
• Enhanced Filtering: All history methods now support a filterPaymentMethod: [String] parameter to isolate Card, QR, or BLIK transactions.

API Breaking Changes

• `getTerminalID()`: Return type updated to AnyPublisher<Result<String, TapOnMobileError>, Never>. It now explicitly fails if the device is not registered.

Update from 1.7.0 to 1.8.0

Visa sensory branding update

If integration is not made via SPM, update the Visa Sensory branding framework with the provided framework.

Update from 1.6 to 1.7

Backend to backend migration (Old methods to be removed in 1.8 version

The backend-to-backend activation flow now consists of three SDK calls: verifyRegistrationToken, beginTokenRegistration, and endTokenRegistration, each designed for improved granularity and security.

Step-by-Step Terminal Registration & Activation

• Verify Registration Code: Begin the process by calling verifyRegistrationToken(code:) from your app to validate the registration code (provided by your backend or portal).
• Begin Token Registration: If the code is valid, initiate token registration using beginTokenRegistration(registrationToken:).
• End Token Registration: To finalize registration and activate the terminal, call endTokenRegistration(registrationToken:pin:) supplying the registration code and a secret secure code(if required).

Changes from Previous Flow

• The previous flow using initTerminal and activateTerminal is deprecated (to be eliminated in V1.8) and replaced by a more granular, token-based registration flow.
• Terminal activation is now achieved exclusively by calling the three-step method sequence.
• Each method provides finer control and clearer error messages.
• Your backend is still required for secure registration code provisioning and verifying authentication.

Migration Note:
If you are using the older initTerminal/activateTerminal flow, you MUST update your codebase and backend implementation to use the new registration token-based sequence.

Reference limit control

The maximum length of the transaction reference is now determined by the referenceMaxLength value provided in the terminal information dynamics properties (default: 30 characters). During both transaction process and validation, the SDK verifies that the reference string does not exceed this limit. If it does, the SDK returns TapOnMobileError.common(.referenceFieldTooLong).

Update from 1.5 to 1.6

Only for non SPM integration New required dependency:

New external dependencies are required to update to this version. These dependencies can be integrated by following the same process as TapOnMobileSDK.xcframework:

New external dependencies are required to update to this version. These dependencies can be integrated by following the same process as TapOnMobileSDK.xcframework:

• MastercardSonic.xcframework
• VisaSensoryBranding.xcframework

Integrating the new Transactions UI feature

Introduction

From this version integrators can choose to use the provided UI to handle and display the transaction information during the payment or refund process. This flow covers the following steps during the process:

• Card reader display.
• Progress screen.
• Dynamic currency change selector screen.
• Transaction result screen.
• Transaction detail screen.
• Transaction receipts.
• Alternative Payment Methods screens.
• Card Brands animations.
• Auditory and haptic feedback.

Changes to the Code

Now opting for SDK UI is as easy as indicating a UIViewController from which will be used as UIHostingController to display the SDK views as modal views using full screen presentation style.

If it's preferred to skip the SDK transaction result screen, the field 'paymentSolutionReceiptHandling' can be set to false and the SDK will dismiss it's modal view after displaying the card brand animation or the sensory feedback.

Below are the code modifications required to integrate these changes:

Before

public func doPayment(
    currency: String,
    requestedAmount: Int,
    reference: String?,
    tipAmount: Int? = nil
) -> AnyPublisher<Result<TransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}
public func doRefund(
    currency: String,
    requestedAmount: Int,
    transactionId: String,
    reference: String?
) -> AnyPublisher<Result<TransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doQRPayment(
    requestedAmount: Int,
    tipAmount: Int?,
    reference: String?
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doQRRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 136 Before

After

public func doPayment(
    currency: String,
    requestedAmount: Int,
    reference: String?,
    tipAmount: Int? = nil,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<TransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doRefund(
    currency: String,
    requestedAmount: Int,
    transactionId: String,
    reference: String?,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<TransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doQRPayment(
    requestedAmount: Int,
    tipAmount: Int?,
    reference: String?,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

public func doQRRefund(
    refundedTransactionId: String,
    refundAmount: Int,
    reference: String?,
    container: UIViewController? = nil,
    paymentSolutionReceiptHandling: Bool = true
) -> AnyPublisher<Result<APMTransactionProcessEvent, TapOnMobileError>, Never> {
    // implementation returns a publisher
}

Code block 137 After

Once the transaction is finished the SDK will return the following event TransactionProcessEvent.completed(TransactionDetail) or APMTransactionProcessEvent.completed(TransactionDetail) to indicate that the transaction is completed and the result of the transaction.

In case of any errors the SDK will return the publisher TapOnMobileError.

Change log

Version	Date	What's new
0.1	22.12.2023	Alpha version
1.0	01.03.2024	Initial version
1.1	22.04.2024	- Added success return TransactionProcessEvent to doPayment and doRefund. - Added Get TerminalInfo function. - Added Card Testing Feature. - Added Privacy Manifest. - Added Transaction History Feature. - Added Tipping to Payments. - Added new sessionError.terminalUnregistered.
1.2	10.05.2024	- Added Transaction Statistics. - Added Backoffice registration. - Added Digital Ticket. - Added Validate Transaction. - Added Alternative Payment Method with QR payments. - Added payment methods to filter in fetchTransactions. - Added public inits to all models to ease Testing. - Added integration with Swift Package Manager. - External dependencies are no longer needed to setup the SDK. - Bug fixes and improvements. - Added Payone environments.
1.3	09.10.2024	- Added Transaction Detail. - Added Session Expiration. - Added DCC Transactions. - Added mandatory parameter "country" to doLoginIntoBackoffice. - Analytics log improvements. - Fixes and improvements.
1.4	18.02.2025	- Improved documentation based on feedback. - Updated Environments table. - Added Get TapOnMobile SDK library. - Added TapOnMobile SDK into your Xcode project. - Added a new parameter appVersion to SDK Initialization. - Updated Backend-to-backend terminal activation. - Updated Merchant portal terminal activation. - Updated Backoffice registration. - Updated Login and Logout descriptions. - Updated PrepareDevice. - Updated Transactions with Is Mandatory column in Transaction Detail. - Updated QR Payment example and parameters. - Added QR Refunds. - Updated DCC Transactions. - Added diagram. - Updated Other core functionalities. - Added Section Formatted Receipt to Digital Receipt. - Added Update secret code feature. - Updated Helper Functionalities. - Added Session Expired Notification.
1.5	06.06.2025	- Added Swift Package Manager local integration. - Fixed iPhone 16 models unknown device issue in portal. - Updated MTLS handling: Removed required MTLS certificates in initialization. - Added expired internal MTLS certificates unregister Notification. - Added external dependency "OpenSSL". - Improved logging and error handling. - Added relinkAccount to re-sign Apple’s Tap to Pay on iPhone T&C. - Added country selection for backoffice registration.
1.6	20.05.2025	- Added UI to the transaction flow. - Renaming of doAPMRefunds to doQRRefunds. - Fixes and improvements.
1.6.1	11.07.2025	- Added OPP environments. - Fixes and improvements.
1.6.2	24.07.2025	- Fixes and improvements.
1.7	14.08.2025	- Terminal Id feature. - New Backend-to-backend feature. OLD METHODS TO BE REMOVED IN 1.8 VERSION. - Reference limit checks. - Accessibility improvements. - New environments added. - Removed backoffice registration method. - Fixes and improvements.
1.8.0	01.10.2025	- Response code update. - CAWL transaction retry feature. - Improved logging. - Added MBank environments. - Removed deprecated Backend-to-Backend functionality. - Updated Visa branding. - Fixes and improvements.
1.9.0	21.11.2025	- Added Quick Start. - Annex: Date Formatting. - Changed prepare device functionality. - Fixes on usage of location services. - Add support service number. - Add new calls for the transactions. - Added language handling for SDK UI.
1.10.0	06.03.2026	- Rollback for fetchTransactions result. - Added error handling in documentation. - Added container management section in documentation. - Updated fetchTransactionDetails in documentation. - Fixes and improvements.
1.10.1	20.03.2026	- Fixes and improvements.
1.10.2	20.03.2026	- Set minimum version of the Swift SDK to iOS 13.0.
1.10.3	16.04.2026	- Fixes and improvements.
1.10.4	23.04.2026	- Fixed crash on iOS 16.0 versions due to missing ProximityReader's symbols.
1.11.0	(unspecified)	- Removed MTLS certificate parameters from initialization for simplified setup. - Simplified error model by removing AuthError and consolidation into SessionError. - Updated requestLocation to return a Publisher for better initialization tracking. - Removed OpenSSL and TrustKit as external dependencies. - Allowed getSDKVersion to be called before full initialization. - New look and feel for processing loading bar screen. - New dynamic RegisterOptions property in InfoInit. - Updated dynamic property's in TerminalInfo model. - Removed UI container for QR and BLIK refund transactions. - Improved logging precision for transaction metrics. - Fixes and improvements.
1.12.0+	(future)	- Various refinements and improvements.