Overview

For client apps, we recommend integrating the native SDK from our risk service providers (Checkout & Forter). This ensures the collection of high-quality device data in complex app environments, improving the accuracy of risk detection. Native integration eliminates the latency and complexity introduced by intermediate forwarding, enhancing the overall payment experience while meeting strict requirements for data reliability, independence, and compliance. This offers merchants a safer, more efficient risk management solution.

Integration steps

1.Add OSLPayRiskSDK.xcframework

1. Drag the OSLPayRiskSDK.xcframework file into your Xcode project (it is recommended to place it in the Frameworks folder).
2. In the dialog that appears, check Copy items if needed, and select all targets for the project.

2.Configure Frameworks, Libraries, and Embedded Content

1. Open your project’s TARGETSsection, locate Frameworks, Libraries, and Embedded Contentand set theOSLPayRiskSDKEmbed option to Embed & Sign。

3.Configure dependencies

OSLPayRiskSDK relies on the following third-party libraries. Ensure that these dependencies are included in your main project's Podfile:

  pod 'Alamofire', '5.10.2'
  pod 'Risk', '3.0.4'
  pod 'ForterSDK', :git => 'https://bitbucket.org/forter-mobile/forter-ios-sdk.git', :tag => '3.0.4'
  pod 'DeviceKit', '5.7.0'
  pod 'FingerprintJS', '1.6.0'
  pod 'MMKV', '1.2.11'
  pod 'SwiftyJSON', '5.0.2'
  pod 'DeviceKit', '5.7.0'

Add the following to the bottom of your Podfile:

post_install do |installer|
  installer.generated_projects.each do |project|
      project.targets.each do |target|
          target.build_configurations.each do |config|
              config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '14.0'
              config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = true
          end
      end
  end
end

Execute the following command to install the dependencies:

pod install

Usage instructions

1.Import the header file In the files where you need to use the SDK, import the following header file:

import OSLPayRiskSDK // Swift

#import <OSLPayRiskSDK/OSLPayRiskSDK.h> // Objective-C

2.Initialize the SDK The SDK internally relies on 3 risk-control SDKs, each of which must be initialized first, and each has a different initialization method. For example, Checkout initializes asynchronously and takes around 2 seconds to complete. We recommend initializing the SDK in the AppDelegate in advance, rather than initializing it at the moment of use.

// Default production environment
OSLPayRiskSDK.setup()
// Enable sandbox mode for debugging; disable sandbox mode when going live
OSLPayRiskSDK.setup(openSandBoxEnv: true)

Example code:

import OSLPayRiskSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
        
    OSLPayRiskSDK.setup()

    return true
}

3.Risk data reporting

// Swift
import OSLPayRiskSDK

OSLPayRiskSDK.collect { clientInfoToken in
  // Reporting succeeded, clientInfoToken received
} onError: { err in
  // Reporting failed
}

// Objective-C
#import <OSLPayRiskSDK/OSLPayRiskSDK.h>
[OSLPayRiskSDK collectWithComplete:^(NSString * _Nullable clientInfoToken) {
  // Reporting succeeded, clientInfoToken received
} onError:^(NSError * _Nullable error) {
   // Reporting failed
}];

4.Collect device information The collect method automatically gathers the following device information:

Notes

1. Initialize the SDK in advance The SDK integrates multiple risk-control SDKs to collect risk parameters. Among them, Checkout has the longest initialization path. In sandbox testing, Checkout takes around 2 seconds to initialize asynchronously. Risk parameters can only be collected after Checkout is fully initialized, which takes about 400ms. Therefore, we recommend initializing the SDK in your Application early, rather than initializing it at the moment of use.
2. Manage the validity of clientInfoToken Each call to the SDK’s getClientInfoToken method returns a new clientInfoToken. On the server side, however, the token is valid for 30 minutes. Make sure not to use it after it expires.
3. Reuse clientInfoToken reasonably within its validity Since obtaining a clientInfoToken depends on Checkout collecting risk parameters (which takes about 400ms in sandbox testing), callers can reuse the token within its validity period according to their business scenario to avoid unnecessary delays.

Reference files

1. Risk SDK for Web
2. Checkout iOS SDK
3. Fingerprint iOS SDK
4. Forter's iOS SDK
5. OSL Pay Risk SDK Demo - iOS Github