--- title: SDK Integration Best Practice slug: sdks/integration-best-practices excerpt: Learn the best practices to follow before beginning with the SDK integration. hidden: false sidebar_order: 2 metadata: title: SDK Best Practices – Pine Labs Online Payments description: >- Learn SDK integration best practices for Pine Labs Online payment solutions. Improve security, performance, reliability, and user experience across web, Android, and iOS payment integrations. --- [block:html] { "html": "" } [/block] ## Key Best Practices [block:html] { "html": "
\n \n \n
\n
\n \n
\n
\n
\n \n \n \n \n
\n
\n

Use a Single SDK Initialization

\n
\n

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.

\n
\n
\n
\n
\n\n \n
\n
\n
\n \n \n \n \n
\n
\n

Match Swift & iOS Compatibility

\n
\n

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.

\n

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

\n
\n
\n
\n
\n\n \n
\n
\n
\n \n \n \n \n \n \n
\n
\n

Network & Security Configuration

\n
\n

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.

\n

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

\n
\n
\n
\n
\n\n \n
\n
\n
\n \n \n \n \n
\n
\n

Handle API Keys Securely

\n
\n

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

\n

This reduces exposure of sensitive keys and prevents misuse.

\n
\n
\n
\n
\n\n \n
\n
\n
\n \n \n \n \n
\n
\n

Keep SDK Updated

\n
\n

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

\n

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

\n
\n
\n
\n
\n
\n
\n
\n " } [/block] ## Recommended Way to Start the SDK [block:html] { "html": "
\n\n\n
\n
\n

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

\n

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

\n

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

\n
\n\n \n
\n
\n
\n \n \n \n \n

Ideal Entry Points

\n
\n

The SDK should be started from:

\n
    \n
  • \n \n \n \n \n Checkout screen\n
    • \n
  • \n \n \n \n \n Order summary screen\n
    • \n
  • \n \n \n \n \n Payment selection screen\n
    • \n
\n

\n These screens are stable, full-screen, and suitable for presenting the SDK.\n

\n
\n\n
\n
\n \n \n \n \n \n

What to Avoid

\n
\n

Do not start the SDK from:

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

\n Launching the SDK from incorrect contexts can cause:\n

\n
    \n
  • \n \n Presentation warnings\n
    • \n
  • \n \n Broken navigation transitions\n
    • \n
  • \n \n Improper SDK dismissal\n
    • \n
  • \n \n Unexpected runtime behavior\n
    • \n
\n
\n
\n
\n
\n\t\t\t\t
" } [/block] ## Navigation Ownership [block:html] { "html": "
\n\n \n
\n
\n
\n
\n

Merchant App Responsibility

\n

The merchant app is responsible only for presenting the SDK.

\n
\n
\n

SDK Internal Handling

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

\n Important: Merchants should not push SDK screens or attempt to control SDK navigation.\n

\n
\n
\n
\n
" } [/block] ## SDK Initialization Rules [block:html] { "html": "
\n\n\n
\n
\n
    \n
  • \n
    1
    \n

    Initialize and launch the SDK only once per payment attempt.

    \n
    • \n
  • \n
    2
    \n

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

    \n
    • \n
  • \n
    3
    \n

    Avoid multiple parallel SDK launches.

    \n
    • \n
\n
\n
\n
\n" } [/block]