SDK Integration Best Practice
Learn the best practices to follow before beginning with the SDK integration.
Key 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.
Recommended Way to Start the SDK
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
Navigation Ownership
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
SDK Initialization Rules
-
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.