Native iOS

Juspay provides an SDK to simplify the integration & enhance the customer experience during checkout.

Installation

You can use one of the two strategies outline below to install the SDK into your application.

The recommended installation mechanism for ExpressCheckout is via CocoaPods. CocoaPods is an Objective-C library dependency manager (Link). Add pod "ExpressCheckout" to your podfile.

pod 'ExpressCheckout'

Run pod install. You should now be able to add SDK to any of your target's source files and begin using ExpressCheckout SDK.

2. Static linking

We strongly recommend that you use CocoaPods for integrating the library. However, if for some reason, you are unable to use it, you may link the SDK directly which is available at the below url

https://s3-ap-southeast-1.amazonaws.com/ec-release/ios/stable/ExpressCheckout-1.0.9.zip (Link)


To add the above libraries into your project, follow the steps provided here:

  1. In the project editor, select the target (the application which gets deployed to app store) to which you want to add.
  2. Click Build Phases at the top of the project editor.
  3. Open the Link Binary With Libraries section.
  4. Click the Add button (+) to add a library or framework.

The following libraries are required as dependency.

  • CoreTelephony.framework
  • JavaScriptCore.framework
  • SystemConfiguration.framework

Add a Bridging header

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.

#import <ExpressCheckout/ExpressCheckout.h>

Intialize Framework

Go to your ViewController where the payment has to be started. You must import the framework first, to use it. Then, create a property for Express Checkout.

Import Framework

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

Create a property for ExpressCheckout.

//Objective-C
@property (nonatomic, strong) ExpressCheckout *checkout;

//Swift
let checkout: ExpressCheckout = ExpressCheckout()

Initialize the property before using it. Typically, the property is initialized in viewDidLoad of the view controller where payment will start.

//Objective-C
- (void) viewDidLoad {
    self.checkout = [[ExpressCheckout alloc] init];
}

Starting payment flow

You are ready to start the payment as soon as your server has called JusPay API to create order. The following parameters are available to you now:

Name Description Required Default
environment One of SANDBOX, PRODUCTION Yes PRODUCTION
merchantId Your merchantId with JusPay Yes
orderId Order ID for the transaction Yes
endUrlRegexes Regular expressions to match the final return URL Yes
paymentInstruments List of options that should be enabled for the customer. If you pass null, then all the options will be made available No @[@"card",@"nb",@"wallet"]

Before you start the payment, you must also pass a callback function as a parameter. If the URL matches any of the patterns defined in endUrlRegexes, then the library will invoke callback function. Ideally, this indicates that the payment has completed or failed.

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
cookies Cookies need to be set in WebView Array of dictionaries
customActivityIndicator Activity indicator to show on merchant page View
confirmationAlertContents Contents of confirmation alert view to show while cancelling the transaction Array

See the example below:

self.checkout.shouldLoadEndURL = TRUE
self.checkout.shouldNotPopOnEndURL = TRUE
self.checkout.shouldNotPopAfterPayment = TRUE

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

UIView *activityIndicator = [[UIView alloc] ...];
...
//Adding subviews and customizing activityIndicator
...
self.checkout.customActivityIndicator = activityIndicator;
self.checkout.confirmationAlertContents = @[@"<title>",
                                            @"<message>",
                                            @"<other_button_title>",
                                            @"<cancel_button_title>"];
self.checkout.shouldLoadEndURL = true
self.checkout.shouldNotPopOnEndURL = true
self.checkout.shouldNotPopAfterPayment = true

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

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

MobileWeb Checkout

This mode of checkout opens a mobile optimized web page within the iOS app to take the payment input from the customer. This is the most straightforward integration. If you wish to disallow certain payment options, you have to explicitly remove the option from the array.

//Objective-C
[self.checkout environment:PRODUCTION merchantId:@"YOUR_MERCHANT_ID" orderId:@"YOUR_ORDER_ID" instrumentOptions:@[] endUrlRegexes:@[@"https:\\/\\/www.test.com\\/.*"]];

[self.checkout startPaymentInView:self.view callback:^(BOOL status, NSError *error, id info) {
    if (error) {
        NSLog(@"Error - %@",[error localizedDescription]);
        if ([error userInfo]) {
            NSLog(@"Error Detail - %@",[error userInfo]);
        }
    }else{
        NSLog(@"What is this::%@",info);
    }
}];

//Swift
checkout.environment(PRODUCTION, merchantId: "YOUR_MERCHANT_ID", orderId: "YOUR_ORDER_ID", instrumentOptions:[],  endUrlRegexes: ["https:\\/\\/www.test.com\\/.*"])

checkout.startPaymentInView(self.view) { (status, error, info) in
    if (error != nil) {
        print("Error - \(error.localizedDescription)")
        if !error.userInfo.isEmpty {
            print("Error Detail - \(error.userInfo)")
        }
    } else {
        print("What is this - \(info)")
    }
}

Native Checkout

If you have already built screens to accept card & netbanking options, then you can directly use our Java code to initiate a payment with the customer's choice.

For all payments, the orderId and merchantId must be set.

Direct Card Transactions

For card payments required params : Card Number, Card Expiry Year(Min Last 2), Card Expiry Month , Card Security Code

//Objective-C
[self.checkout environment:PRODUCTION merchantId:@"YOUR_MERCHANT_ID" orderId:@"YOUR_ORDER_ID" cardNumber:@"CARD_NUMBER" cardExpiryYear:@"CARD_EXPIRY_YEAR" cardExpiryMonth:@"CARD_EXPIRY_MONTH" cardSecurityCode:@"CARD_SECURITY_CODE" nameOnCard:@"NAME_ON_CARD" saveToLocker:YES endUrlRegexes:@[@"https:\\/\\/www.test.com\\/.*"]];

//Swift
checkout.environment(PRODUCTION, merchantId: "YOUR_MERCHANT_ID", orderId: "YOUR_ORDER_ID", cardNumber: "CARD_NUMBER", cardExpiryYear: "CARD_EXPIRY_YEAR", cardExpiryMonth: "CARD_EXPIRY_MONTH", cardSecurityCode: "CARD_SECURITY_CODE", nameOnCard: "NAME_ON_CARD", saveToLocker:true, endUrlRegexes: ["https:\\/\\/www.test.com\\/.*"])

Direct Wallet Transactions

For wallet payments required params : wallet

//Objective-C
[self.checkout environment:PRODUCTION merchantId:@"YOUR_MERCHANT_ID" orderId:@"YOUR_ORDER_ID" wallet:@"WALLET" endUrlRegexes:@[@"https:\\/\\/www.test.com\\/.*"]];

//Swift
checkout.environment(PRODUCTION, merchantId: "YOUR_MERCHANT_ID", orderId: "YOUR_ORDER_ID", wallet: "OLAMONEY", endUrlRegexes: ["https:\\/\\/www.test.com\\/.*"])

WALLET can be one of the supported wallets such as PAYTM, MOBIKWIK, FREECHARGE, OLAMONEY, etc.

Direct Net Banking Transactions

For net banking payments required params : netbankingBank

//Objective-C
[self.checkout environment:PRODUCTION merchantId:@"YOUR_MERCHANT_ID" orderId:@"YOUR_ORDER_ID" netbankingBank:@"NB_HDFC" endUrlRegexes:@[@"https:\\/\\/www.merchant.com\\/.*"]];

//Swift
checkout.environment(PRODUCTION, merchantId: "YOUR_MERCHANT_ID", orderId: "YOUR_ORDER_ID", netbankingBank: "NB_HDFC", endUrlRegexes: ["https:\\/\\/www.merchant.com\\/.*"])

Start the transaction

Express Checkout SDK integrates with JusPay Safe to offer a seamless payment flow to customers. When the payment is initiated, the authentication URL is handled by the JusPay Safe SDK. See the example code snippet below:

//Objective-C
[self.checkout startPaymentInView:self.view callback:^(BOOL status, NSError *error, id info) {
    if (error) {
        NSLog(@"Error - %@",[error localizedDescription]);
        if ([error userInfo]) {
            NSLog(@"Error Detail - %@",[error userInfo]);
        }
    } else {
        NSLog(@"Payment finished with info::%@",info);
    }
}];

//Swift
checkout.startPaymentInView(self.view) { (status, error, info) in
    if (error != nil) {
        print("Error - \(error.localizedDescription)")
        if !error.userInfo.isEmpty {
            print("Error Detail - \(error.userInfo)")
        }
    } else {
        print("Payment finished with info - \(info)")
    }
}

JusPay will not provide the payment status in the callback function, because it is a security issue. You will have to check with your server and retrieve the status from JusPay using /order/status API.

Back button handling (Required)

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.checkout.browser backButtonPressed];
    return self.checkout.browser.isControllerAllowedToPop;
}
override func navigationShouldPopOnBackButton() -> Bool {
    self.checkout.browser.backButtonPressed()
    return self.checkout.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;
}

Help & Support

If you notice any errors or issues with the integration, please reach out to us at support@juspay.in. You may also search our Knowledge base to see if the issue has already been addressed by our team.