SDK Integration Best Practices

Use a Single SDK Initialization

Initialize the SDK only once during your app lifecycle. Re-initializing or integrating the SDK multiple times can lead to unexpected behaviour or runtime errors.

Match Swift & iOS Compatibility

The SDK is built in Swift 5. Ensure your app's Swift version matches or is compatible (Swift 5 or later) to avoid compile-time or runtime issues.

Keep your iOS deployment target up-to-date so that all required frameworks work without build errors.

Network & Security Configuration

If network calls fail in testing (e.g., due to SSL or Apple ATS), allowlist required domains and configure App Transport Security (ATS) properly to prevent blocked requests.

This is a common issue when testing in restricted environments like simulators or corporate networks.

Handle API Keys Securely

Do not hardcode API keys in the app bundle. Generate and supply keys securely from your backend.

This reduces exposure of sensitive keys and prevents misuse.

Keep SDK Updated

Regularly update to the latest SDK version can be easily done by right clicking on the package name and clicking on Update Package.

This includes security updates, new payment methods, and compatibility fixes.

Start the SDK from a fully presented, visible view controller that is part of your app's normal navigation flow.

Trigger the SDK launch via a user-initiated action, such as tapping a "Pay Now" button.

Once launched, the SDK manages its entire internal navigation using its own navigation stack.

Ideal Entry Points

The SDK should be started from:

Checkout screen
Order summary screen
Payment selection screen

What to Avoid

Do not start the SDK from:

Alerts (UIAlertController)
Bottom sheets or half sheets (.pageSheet)
Popups or transient modals
Views that are already being presented or dismissed

Launching the SDK from incorrect contexts can cause:

Presentation warnings
Broken navigation transitions
Improper SDK dismissal
Unexpected runtime behavior

Merchant App Responsibility

The merchant app is responsible only for presenting the SDK.

SDK Internal Handling

Creates its own navigation controller
Pushes all SDK screens
Handles retry and error flows
Dismisses itself when the flow ends

1

Initialize and launch the SDK only once per payment attempt.
2

Ensure a valid order token is available before starting the SDK.
3

Avoid multiple parallel SDK launches.

SDK Integration Best Practice

Key Best Practices