First integration

• Xcode 16 and iOS 18 SDK or higher
• iOS 13.0+ deployment target

1. Drag and drop OPPWAMobile.xcframework & ipworks3ds_sdk.xcframework to the "Frameworks" folder of your project.
Make sure "Copy items if needed" is checked.


2. Check "Frameworks, Libraries, and Embedded Content" section under the general settings tab of your application's target. Ensure the Embed dropdown has Embed and Sign selected for the framework.

You can now import the framework with:

#import <OPPWAMobile/OPPWAMobile.h>

#import <OPPWAMobile/OPPWAMobile.h>

There are two versions of the ipworks3ds_sdk.xcframework included: one to be used for development and one for production. The production version includes more strict security measures that would not allow for common development processes to occur, including running with attached debuggers or using simulators/emulators. The deployment version includes _deploy in the filename.
If you integrate SDK to the Swift app, please see the Apple guide Importing Objective-C into Swift to check how to import Objective-C headers correctly.

To start working with our SDK, you should expose two APIs on your backend for your iOS app to communicate with:

NSURLRequest *merchantServerRequest = [[NSURLRequest alloc] initWithURL:[NSURL URLWithString:@"https://YOUR_URL/?amount=100&currency=EUR&paymentType=DB"]];
[[[NSURLSession sharedSession] dataTaskWithRequest:merchantServerRequest completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
    // TODO: Handle errors
    NSDictionary *JSON = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:nil];
    self.checkoutID = JSON[@"checkoutId"];
}] resume];

let merchantServerRequest = NSURLRequest(url: URL(string: "https://YOUR_URL/?amount=100&currency=EUR&paymentType=DB")!)
URLSession.shared.dataTask(with: merchantServerRequest as URLRequest) { (data, response, error) in
    // TODO: Handle errors
    if let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
        let checkoutID = json?["checkoutId"] as? String
    }
}.resume()

1. Initialize Payment Provider with test mode

self.provider = [OPPPaymentProvider paymentProviderWithMode:OPPProviderModeTest];

let provider = OPPPaymentProvider(mode: OPPProviderMode.test)

2. Configure the Checkout Settings

Define the settings for the checkout screen. Initialize OPPCheckoutSettings, it controls the information that is shown to the shopper.
For the first integration we recommend you to enable only synchronous payment methods, other payment brands need additional configuration.

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];

// Set available payment brands for your shop
checkoutSettings.paymentBrands = @[@"VISA", @"DIRECTDEBIT_SEPA"];

// Set shopper result URL
checkoutSettings.shopperResultURL = @"com.companyname.appname.payments://result";

let checkoutSettings = OPPCheckoutSettings()

// Set available payment brands for your shop
checkoutSettings.paymentBrands = ["VISA", "DIRECTDEBIT_SEPA"]

// Set shopper result URL
checkoutSettings.shopperResultURL = "com.companyname.appname.payments://result"

NOTE: In order to make sure that the Mobile SDK seamlessly supports every payment method, setting shopperResultUrl is mandatory. To learn more, see Asynchronous Payments guide.

3. Present the Checkout Page

Initialize OPPCheckoutProvider with the received checkout ID and created settings.

NOTE: Create the OPPCheckoutProvider object at the class level to ensure its not released during the payment process.

OPPCheckoutProvider *checkoutProvider = [OPPCheckoutProvider checkoutProviderWithPaymentProvider:provider
                                                                                      checkoutID:checkoutID
                                                                                        settings:checkoutSettings];

let checkoutProvider = OPPCheckoutProvider(paymentProvider: provider, checkoutID: checkoutID!, settings: checkoutSettings)

Then, open the payment page and implement the callbacks.

// Since version 2.13.0
[checkoutProvider presentCheckoutForSubmittingTransactionCompletionHandler:^(OPPTransaction * _Nullable transaction, NSError * _Nullable error) {
   if (transaction.type == OPPTransactionTypeSynchronous)  {
       // Send request to your server to obtain the status of the synchronous transaction
       // You can use transaction.resourcePath or just checkout id to do it
       // Error is no more an decisive factor for transaction termination
       if (transaction.resourcePath) {
             // get the payment status using the resourcePath
       }
    } else {
        // The SDK opens transaction.redirectUrl in a browser
        // See 'Asynchronous Payments' guide for more details
    }
} cancelHandler:^{
    // Executed if the shopper closes the payment page prematurely
}];

// Since version 2.13.0
checkoutProvider?.presentCheckout(forSubmittingTransactionCompletionHandler: { (transaction, error) in
   if transaction.type == .synchronous {
        // If a transaction is synchronous, just request the payment status
        // You can use transaction.resourcePath or just checkout ID to do it
        // Error is no more an decisive factor for transaction termination
        if transaction.resourcePath {
           // get the payment status using the resourcePath
        }
    } else if transaction.type == .asynchronous {
        // The SDK opens transaction.redirectUrl in a browser
        // See 'Asynchronous Payments' guide for more details
    } 
}, cancelHandler: { 
    // Executed if the shopper closes the payment page prematurely
})

For versions 2.12.0 and earlier use another method to open the checkout page.
Note there is an additional callback paymentBrandSelectedHandler which allows you to create and pass to the SDK new checkout ID. In newer versions this callback is moved to OPPCheckoutProviderDelegate. You may need this feature to send additional parameters at 1st step for specific payment brands. Otherwise set callback to nil.

[checkoutProvider presentCheckoutForSubmittingTransactionCompletionHandler:^(OPPTransaction * _Nullable transaction, NSError * _Nullable error) {
    // Handle transaction submitting result as shown in previous sample
} paymentBrandSelectedHandler:nil cancelHandler:^{
    // Executed if the shopper closes the payment page prematurely
}];

checkoutProvider?.presentCheckout(forSubmittingTransactionCompletionHandler: { (transaction, error) in
    // Handle transaction submitting result as shown in previous sample
}, paymentBrandSelectedHandler:nil, cancelHandler: { 
    // Executed if the shopper closes the payment page prematurely
})

[Optional] 4. Security. Disable third party keyboards.

A malicious third party keyboard may perform key-logging and transmit the logged information to an attacker’s server. It's recommended to disable the usage of third party keyboards entirely in your application. Note that this may degrade the user experience of your application.

- (BOOL)application:(UIApplication *)application shouldAllowExtensionPointIdentifier:(UIApplicationExtensionPointIdentifier)extensionPointIdentifier {
    if (extensionPointIdentifier == UIApplicationKeyboardExtensionPointIdentifier) {
        return NO;
    }
    return YES;
}

func application(_ application: UIApplication, shouldAllowExtensionPointIdentifier extensionPointIdentifier: UIApplicationExtensionPointIdentifier) -> Bool {
    if (extensionPointIdentifier == UIApplicationExtensionPointIdentifier.keyboard) {
        return false
    }
    return true
}

NSString *URL = [NSString stringWithFormat:@"https://YOUR_URL/paymentStatus?resourcePath=%@", [transaction.resourcePath stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]];
NSURLRequest *merchantServerRequest = [[NSURLRequest alloc] initWithURL:[NSURL URLWithString:URL]];
[[[NSURLSession sharedSession] dataTaskWithRequest:merchantServerRequest completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
    // handle error
    NSDictionary *result = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:nil];
    BOOL status = [result[@"paymentResult"] boolValue];
}] resume];

let url = String(format: "https://YOUR_URL/paymentStatus?resourcePath=%@", transaction.resourcePath!.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!)
let merchantServerRequest = NSURLRequest(url: URL(string: url)!)
URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data, let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
        let transactionStatus = json?["paymentResult"] as? Bool
    }
}.resume()

self.provider = [OPPPaymentProvider paymentProviderWithMode:OPPProviderModeLive];

let provider = OPPPaymentProvider(mode: OPPProviderMode.live)