iOS Custom Browser

Simplified Integration:

Integrating custom browser should not take more than 10 minutes of time if the merchant has payment post parameters ready. Merchant will be using PayU's view controller PUCBWebVC for making payment. This view controller creates a UIWebView or WKWebview based on configuration and loads it to facilitate payment.

Integrating Custom Browser in your app

Using Cocoapods:

1. Add following line to Podfile: 'PayUIndia-Custom-Browser'

2. Run: pod install

It is recommended that you integrate the latest version of Custom Browser. To check the latest version, see releases page.

If above steps installs older version of the CB's pod. Use following steps to reinstall CB with latest release.

1. Uninstall older CB:

   • Remove the line 'PayUIndia-Custom-Browser' from your pod file.
   • Run: pod install

2. Update pods local repo

   • Run: pod repo update

3. Clean pods cache

   • Run: pod cache clean --all

4. Add following line to Podfile: 'PayUIndia-Custom-Browser'

5. Run: pod install

Manual Integration:

1. Download latest custom browser zip from github and Unzip it.
2. From the downloaded content, drag and drop PayUCustomBrowser.framework into your project.
3. Add libz.tbd libraries into your project target's Build Phases.
4. Add SystemConfiguration framework into your project target's Build Phases.
5. Add -ObjC in Other Linker Flags in Project Build Settings.
6. Add PayUCustomBrowser.framework in Embedded Binaries in Genral Settings.

Now that Custom Browser library is added to your project, you can go ahead and use it to make payments.

Initiating Payment

You just need to pass few parameters to initialize PUCBWebVC controller which will initiate the payment process.

• postParam: A string containing payment related information. For info on how to create it, please refer SDK Wiki
• URL: This is the first URL loaded in the webView. postParam will be posted here. For example In case of PayU (production server), it will be https://secure.payu.in/_payment.
• merchantKey: Key provided to you by PayU. This is required to provide tech support to merchants for live transactions.

NSError *err = nil;
PUCBWebVC *webVC = [[PUCBWebVC alloc] initWithPostParam:postParam
                                                     url:URL
                                             merchantKey:@"YourMerchantKey"
                                                   error:&err]; 
webVC.cbWebVCDelegate = self; 

if (!err) {
   [self.navigationController pushViewController:webVC animated:true];
}

Handling Payment Response

To get the response of payment (success/failure/error), you need to conform to protocol ‘PUCBWebVCDelegate’. The class in which you create PUCBWebVC object would generally be the delegate.

Following methods need to be implemented for response handling:

// Following methods give the response from your server's Success URL/ Failure URL. These are recommended to receive the response in your app after the transaction. 
// First parameter contains PayU's response. The second parameter contains response that your server has posted 
// to your app
- (void)PayUSuccessResponse:(id) payUResponse SURLResponse:(id) surlResponse;
- (void)PayUFailureResponse:(id) payUResponse FURLResponse:(id) furlResponse;

// Following methods give response from PayU to your app. The above methods are preferred over these methods 
// to mitigate data tampering risk. 
- (void)PayUSuccessResponse:(id)response; 
- (void)PayUFailureResponse:(id)response;

// General callbacks in case of ongoing transaction getting issues
- (void)PayUConnectionError:(NSDictionary *)notification;
- (void)PayUTransactionCancel;
- (void)shouldDismissVCOnBackPress; // This is an optional method which gets invoked if user presses back button. If you override it, 

Custom Browser Customizations: (Optional but highly recommended)

Ok, now as the basic payment collection is done, let see how CB can improve success rates and provide great user experience. There are many features that are provided along with CB. To use them, you need to create PUCBConfiguration object.

    PUCBConfiguration *cbConfig = [PUCBConfiguration getSingletonInstance];                    

In this object, you can let CB know which feature you would want to use. Please make sure to create configuration object before creating PUCBWebVC object!

1. Review Order (RO): (Available on v5.5+)

With Review Order merchant can display an ongoing transaction’s information to the user on bank page.

You have two options by which transaction information can be displayed using RO:

With PayU’s Default UI: You pass the data to be displayed. We create a UIView with your information and show it at appropriate times to the user.
CB needs an NSArray to create the UI. Each element of NSArray needs to be an NSDictionary. Let us assume you create arrOfDictForReviewOrder with following info:

 NSMutableArray *arrOfDictForReviewOrder = [[NSMutableArray alloc]init];

 [arrOfDictForReviewOrder addObject:[NSDictionary dictionaryWithObject:@"xyz123" forKey:@"Booking-ID"]];
 [arrOfDictForReviewOrder addObject:[NSDictionary dictionaryWithObject:@"October 31 '17 " forKey:@"Date"]];
 [arrOfDictForReviewOrder addObject:[NSDictionary dictionaryWithObject:@"Gurgaon" forKey:@"Place"]];

Each Dict object in above array will contain key value pair. These key value pairs will be displayed in Review Order’s default UI screen.
Go ahead and create an object of PUCBReviewOrderConfig with above array.

 NSError *err;
 PUCBReviewOrderConfig *reviewOrderConfig = [[PUCBReviewOrderConfig alloc] initWithArrForReviewOrder:arrOfDictForReviewOrder
                                                                                               error:&err]; 

 if (err) { 
     NSLog(@"%@",err.description);  
 } else {
     cbConfig.reviewOrderConfig = reviewOrderConfig;
}

With Custom UI: You pass us an object of UIView. You design the UIView and fill information in it. We display the view as-is at appropriate times to the user.

Create a view as per your design which contain the data you want to display. Make sure your view is either UIView or any of its subclass. //Assume its name is vwRO

Your view will be displayed with height of 227 points. If you intend to show more information that cannot be displayed with view of height 227, make a scroll view/table view, but keep height to 227. Otherwise, information may be lost as only top 227 points of your view will be visible on bank page.

Create an object of PUCBReviewOrderConfig as below.

PUCBReviewOrderConfig *reviewOrderConfig = [[PUCBReviewOrderConfig alloc] initWithCustomView:vwRO error:&err]; 

NSError *err;
PUCBReviewOrderConfig *reviewOrderConfig = [[PUCBReviewOrderConfig alloc] initWithCustomView:vwRO
                                                                                              error:&err];


if (err) { 
     NSLog(@"%@",err.description);  
 } else {
     cbConfig.reviewOrderConfig = reviewOrderConfig;
}

2. SurePay:

Surepay prevents the transaction from failing in case of internet failures.

In cases when SurePay count is not set by merchant or it has been set as 0, Magic-Retry will work (if MagicRetry flag is set to 'YES')

Note: For SurePay to work, merchant needs to provide postParams and paymentURL to cbConfig object.

How to enable SurePay.

In PUCBConfig’s object, set

cbConfig.surePayCount = x (integer value, >= 0 and <=3) ;
cbConfig.paymentPostParam = postParam; (string of postParams being sent to webview)
cbConfig.paymentURL = [request.URL absoluteString];  (first URL loaded in webview)

3. Miscellaneous configurations:

You need to make an instance of PUCBConfiguration. This is a singleton class.

• Following configurations are available to be customized for Custom Browser:
  • merchantResponseTimeout: Value in seconds. This is maximum time for which CB waits for your success URL (surl)/ failure URL (furl) to give the response back to CB. Its default value is 5. CB forwards this response to your app immediately. If CB does not get any response within time stipulated by merchantResponseTimeout then it sends nil as response in the callbacks.
  • enableWKWebView: It is 'NO' by default. If set to use, CB internally uses WKWebView to carry out the transaction. It is recommended to set it to 'YES' as its memory footprint is far less than UIWebView.
  • merchantKey: It the merchant identifier (key) given to you by PayU
  • transactionId: Set the id of your current transaction
  • isMagicRetry: It is ‘YES' by default. You can choose to disable it. The is flag which if set yes, tries to increase the success rate of a transaction if internet connection was lost while making payment.
  • isAutoOTPSelect: It is ‘NO’ by default. You can choose to select it if you want to always select OTP as method of authentication on bank page.

Sample Code:

cbConfig.merchantResponseTimeout = 30;
cbConfig.enableWKWebView = 'YES';
cbConfig.merchantKey = @”gtKFFx”   //your merchant key here
cbConfig.transactionId = self.paymentParam.transactionID;   //give transaction id to cbConfig
cbConfig.isMagicRetry = YES;
cbConfig.isAutoOTPSelect = NO;

Distributing your app (App Store / Ad-hoc)

What you get by default is a fat framework that allows you to test your app seamlessely on device as well as simulator. But before archiving your app, you need to remove simulator slices from the framework. Please see the following doc which assists in archieving your app with CB integrated