Start the browser

Pre-requisites

Before being able to start the browser, you have to create the following

  1. Setup a mechanism to tell when the payment ends
  2. Create the parameters bundle to initialize the browser correctly
  3. Start the browser in a new view controller
  4. Override back button is compulsory.

Note: Minimum supported OS version is 8.0

The below sections explain how to achieve these steps.

Starting the browser

Import Framework

#import <JuspaySafeBrowser/JuspaySafeBrowser.h>

Create a property for JuspaySafeBrowser.

@property (nonatomic, strong) JuspaySafeBrowser *browser;
var browser:JuspaySafeBrowser = JuspaySafeBrowser()

Initialize the property before using.

//add the below code to viewDidLoad of view controller where payment will start.
self.browser = [[JuspaySafeBrowser alloc]init];

For ex : In viewDidLoad of the view controller where payment will start.

Back button handling (Required)

You can easily use the SDK with swift using Objective-C Bridging Header. Apple has some nice documentation on subject.
To begin, create a new file (File > New > File > iOS > Source > Header File) and name it YourProjectName-Bridging-Header.h. Open the file and import Juspaysafe BackButtonHandler.

We need access to the back button for the view controller where payment will start which can not be done if you have interactive Pop gesture enabled. To disable it for current view controller.

//Add to viewDidAppear 
if ([self.navigationController respondsToSelector:@selector(interactivePopGestureRecognizer)]) {
    self.navigationController.interactivePopGestureRecognizer.enabled = NO;
}
//Add to viewDidAppear 
if((self.navigationController?.respondsToSelector(Selector("interactivePopGestureRecognizer"))) != nil) {
    self.navigationController?.interactivePopGestureRecognizer?.enabled = false;
}

Add the navigationShouldPopOnBackButton method somewhere to check if controller is allowed to pop.

- (BOOL)navigationShouldPopOnBackButton{
    [self.browser backButtonPressed];
    return self.browser.isControllerAllowedToPop;
}
override func navigationShouldPopOnBackButton() -> Bool {
    self.browser.backButtonPressed()
    return self.browser.isControllerAllowedToPop;
}

To renable interactive pop gesture.

//Add to viewWillDisappear 
if ([self.navigationController respondsToSelector:@selector(interactivePopGestureRecognizer)]) {
    self.navigationController.interactivePopGestureRecognizer.enabled = YES;
}
//Add to viewWillDisappear 
if((self.navigationController?.respondsToSelector(Selector("interactivePopGestureRecognizer"))) != nil) {
    self.navigationController?.interactivePopGestureRecognizer?.enabled = true;
}

Create BrowserParams Object

BrowserParams class provides an easy-to-use interface to add all the parameters that must be sent to JusPay Safe browser. Create an instance of the class to get started:

BrowserParams *browserParams = [[BrowserParams alloc] init];
let browserParams:BrowserParams = BrowserParams()

Find below the set of parameters which must be sent:

Variable Description Type Required
url Start URL for payment String Yes
postData POST parameters that must be passed to the URL String No
merchantId Identifies the merchant. Eg. 'merchant' String Yes
clientId merchantId followed by platform name. Eg. 'merchant_ios' String Yes
transactionId Represents the current transactionId String Yes
orderId Represents the order number assigned by the merchant String Yes
amount Amount of the transaction String Yes
customerId Unique identifier of the customer String No
customerEmail Email address of the customer String Yes
customerPhoneNumber Mobile number of the customer String No
displayNote Short note about transaction shown to the customer. ex. 'Paying INR 200 for Order 123456' String No
remarks Remarks about transaction. This will be automatically filled up in the bank page. String No
cookies Cookies need to be set in WebView Array of dictionaries No
customActivityIndicator Activity indicator to show on merchant page View No
confirmationAlertContents Contents of confirmation alert view to show while cancelling the transaction Array No

See the example below:

//Array of endURLs to be checked for completion of transaction.
NSArray *endUrlRegexes = @[@"<Regex_of_your_choice>"];
browserParams.endUrlRegexes = endUrlRegexes;

// client identification
browserParams.clientId = @"<client_id>";
browserParams.merchantId = @"<merchant_id>";
browserParams.transactionId = @"<transaction_id>";

// customer identification
browserParams.customerId = @"<customer_id>";
browserParams.customerEmail = @"<customer_email>";
browserParams.customerPhoneNumber = @"<customer_phone_number>";

// order meta information
browserParams.displayNote = @"<Dispay_note_of_your_choice>";
browserParams.remarks = @"<desired_remarks>";

// authentication data
browserParams.url = @"<url>";
browserParams.postData = @"<post_data>";

// cookies
NSDictionary *cookieProperties1 = [NSDictionary dictionaryWithObjectsAndKeys:
                                      @"<cookie_name>", NSHTTPCookieName,
                                      @"<cookie_value>", NSHTTPCookieValue,
                                      @"<cookie_domain>", NSHTTPCookieDomain,
                                      @"<cookie_path>", NSHTTPCookiePath,
                                      <cookie_expires>, NSHTTPCookieExpires, nil];
browserParams.cookies = @[cookieProperties];

// UX customization
NSMutableDictionary *customParameters = [[NSMutableDictionary alloc] init];
[customParameters setValue:@"<custom_value>" forKey:@"<custom_key>"];
browserParams.customParameters = customParameters;

UIView *activityIndicator = [[UIView alloc] ...];
...
//Adding subviews and customizing activityIndicator
...
browserParams.customActivityIndicator = activityIndicator;
browserParams.confirmationAlertContents = @[@"<title>",
                                            @"<message>",
                                            @"<other_button_title>",
                                            @"<cancel_button_title>"];
//Array of endURLs to be checked for completion of transaction.
let endUrlRegexes = ["<Regex_of_your_choice>"]
browserParams.endUrlRegexes = endUrlRegexes

// Client identification
browserParams.clientId = "<client_id>"
browserParams.merchantId = "<merchant_id>"
browserParams.transactionId = "<transaction_id>"

// customer identification
browserParams.customerId = "<customer_id>"
browserParams.customerEmail = "<customer_email>"
browserParams.customerPhoneNumber = "<customer_phone_number>"

// order meta information
browserParams.displayNote = "<Dispay_note_of_your_choice>"
browserParams.remarks = "<desired_remarks>"

// authentication data
browserParams.url = netBankingURL
browserParams.postData = netBankingPostData

// cookies
let cookieProperties : NSDictionary = [
            NSHTTPCookieName : "<cookie_name>",
            NSHTTPCookieValue : "<cookie_value>",
            NSHTTPCookieDomain : "<cookie_domain>",
            NSHTTPCookiePath : "<cookie_path>",
            NSHTTPCookieExpires : <cookie_expires>
]
browserParams.cookies = [cookieProperties]

// UX customization
let customParameters = NSMutableDictionary()
customParameters.setValue("<custom_value>", forKey: "<custom_key>")
browserParams.customParameters = customParameters as [NSObject : AnyObject]

let activityIndicator = UIView(...)
...
//Adding subviews and customizing activityIndicator
...
browserParams.customActivityIndicator = activityIndicator
browserParams.confirmationAlertContents = ["<title>",
                                          "<message>",
                                          "<other_button_title>",
                                          "<cancel_button_title>"]

All values in postData should be URL encoded before setting browserParams.postData = postData;. If you do not URL encode the values, then your gateway/aggregator will show error message in the browser.

Browser Properties (Optional)

Variable Description Type
shouldLoadEndURL Set it as true if EndURL should be loaded Boolean
shouldNotPopOnEndURL Set it as true if the browser should not be popped when EndURL is reached Boolean
shouldNotPopAfterPayment Set it as true if the browser should not be popped after payment completion Boolean
webviewCallback Callback which gives Webview as a parameter None

See the example below:

self.browser.shouldLoadEndURL = TRUE
self.browser.shouldNotPopOnEndURL = TRUE
self.browser.shouldNotPopAfterPayment = TRUE
self.browser.webviewCallback = ^(WKWebView * _Nullable webView) {

};
self.browser.shouldLoadEndURL = true
self.browser.shouldNotPopOnEndURL = true
self.browser.shouldNotPopAfterPayment = true
self.browser.webviewCallback = {(webView: WKWebView) -> Void in

}

Browser Delegate

JuspaySafeBrowserDelegate protocol gives url loading status. Setup delegate using jpBrowserDelegate property.

See the example below:

self.browser.jpBrowserDelegate = self

Optional delegation methods in JuspaySafeBrowserDelegate:

//To check if url should be loaded. Return true if url should be loaded, else false.
- (BOOL)browserShouldStartLoadingUrl:(NSURL * _Nullable)url;

//Indicates start of a url loading.
- (void)browserDidStartLoadingUrl:(NSURL * _Nullable)url;

//Indicates finish of a url loading.
- (void)browserDidFinishLoadUrl:(NSURL * _Nullable)url;

//Indicates failure of a url loading.
- (void)browserDidFailLoadingUrl:(NSURL* _Nullable)url withError:(NSError *_Nullable)error;
//To check if url should be loaded. Return true if url should be loaded, else false.
func browserShouldStartLoadingUrl(url: NSURL?) -> Bool

//Indicates start of a url loading.
func browserDidStartLoadingUrl(url: NSURL?)

//Indicates finish of a url loading.
func browserDidFinishLoadUrl(url: NSURL?)

//Indicates failure of a url loading.
func browserDidFailLoadingUrl(url: NSURL?, withError error: NSError?)

Start the Payment process

Now, start the browser and wait for it to complete. This starts the payment process and gives the callback when aborted or successful.

// Calling startPayment
[self.browser startpaymentWithJuspayInView:self.view 
              withParameters:browserParams 
              callback:^(BOOL status, NSError *error, id info) {

}];
// Calling startPayment
self.browser.startpaymentWithJuspayInView(self.view, withParameters: browserParams) { (status:Bool, error:NSError!, info:AnyObject!) in

}


view is the view in which payment will start.
browserParams is the browser parameters object for this request.
callback is callback which you receive when the trasaction has reached endURL or cancelled by user.
staus is true if transaction has reached one of the endURLRegex else false;
error shows the reason for failure. For list of error codes check Error Codes
info is a NSDictionary which contains all the info like EndUrl , TransactionID (passed in browser params), etc.

Instantiate BrowserCallback

Callback will be invoked when a user completes the payment or cancels it midway. Whenever a payment is completed (successfully or not), the aggregator/gateway will send the user back to your website. Usually, you would pass single return_url or multiple URLs to aggregator to represent success, failure or cancel.

JusPay Browser expects endUrlRegexes as an input. The input technique will be explained in the section below. This variable represents an array of String which are regular expressions to match the final return URL. You can send as many URLs as you want here. If the return flow (from gateway to merchant) uses webView: shouldStartLoadWithRequest: is used to check if the URL matches the regex. If matched, then endUrlReached is invoked by the browser. You will now have control of the user session.