First integration

iOS

Requirements

• Xcode 11 and iOS 13 SDK
• iOS 10.0+ deployment target

Install the SDK

1. Drag and drop OPPWAMobile.framework & OPPWAMobile-Resources.bundle to the "Frameworks" folder of your project.
Make sure "Copy items if needed" is checked.


2. Check "Build Phases" section of your Xcode project settings. Make sure:
• .framework file is in "Link Binaries with Libraries",
• .bundle file is in "Copy Bundle Resources".





3. Confirm that these two Build Settings are both enabled:
• Enable Modules (C and Objective-C)
• Link Frameworks Automatically


4. [Optional] SDK extensions
   You do not have to import additional frameworks to your project, unless you are going to use the following features:
   • Credit card scanning (OPPWAMobile-CardIO.framework)
   • Alipay native SDK (OPPWAMobile-Alipay.framework)
   • Iovation FraudForce SDK (FraudForce.framework)
   Follow the links to know how to integrate these extensions.

You can now import the framework with:

#import <OPPWAMobile/OPPWAMobile.h>

#import <OPPWAMobile/OPPWAMobile.h>

Set Up Your Server

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

• Endpoint 1: Creating a checkout ID,
• Endpoint 2: Getting result of payment.

See detailed instruction in our guide "Set Up Your Server".

Request Checkout ID

Your app should request a checkout ID from your server. This example uses our sample integration server; please adapt it to use your own backend API.

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()

Present Checkout UI

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: To learn more about shopper result url refer to Asynchronous Payments guide.

3. Present the Checkout Page

Initialize OPPCheckoutProvider with the received checkout ID and created settings.

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 (error) {
        // Executed in case of failure of the transaction for any reason
    } else 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
    } 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
    guard let transaction = transaction else {
        // Handle invalid transaction, check error
        return
    }
    
    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
    } else if transaction.type == .asynchronous {
        // The SDK opens transaction.redirectUrl in a browser
        // See 'Asynchronous Payments' guide for more details
    } else {
        // Executed in case of failure of the transaction for any reason
    }
}, 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
}

Request Payment Status

Finally your app should request the payment status from your server (again, adapt this example to your own setup).

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()

Testing

The sandbox environment only accepts test payment parameters.

You can find test values for credit cards and bank accounts in our Testing Guide.

Go to Production

1. Talk to your account manager to get the live credentials.

2. Adjust the server type to LIVE in your initialization of OPPPaymentProvider.

self.provider = [OPPPaymentProvider paymentProviderWithMode:OPPProviderModeLive];

let provider = OPPPaymentProvider(mode: OPPProviderMode.live)

3. Change your backend to use the correct API endpoints and credentials.