SDK Integration

Introduction

Welcome to Payments SDK Integration Documentation for iOS!
JusPay Payments SDK helps the merchant to communicate with Juspay servers directly from the client. Application using simple operations and manage Mobile App payments until completion.

In Mobile apps, the integration is through an SDK that can be easily embedded in your app code. With PaymentsSDK, merchants will be able to provide a pleasing payment experience on top of the existing 3D secure infrastructure.

This document explains how to integrate the Payments SDK in your iOS Mobile App for the payment flow.

Getting Started

The recommended installation mechanism for Payments SDK is via CocoaPods.
Add pod 'HyperSDK', '0.2.102' to your Podfile.

In case there is an error Unable to find a specification for HyperSDK, the local pod repo needs to be updated. You will need to run:
pod repo update

Before creating the release build, please review the Merchant Checklist once.

📘

Note: Minimum supported OS version is 9.0.

PreFetching Juspay Assets

Since the SDK uses a Micro Service architecture on top of iOS, it is highly recommended to call the preFetch API. Highly recommend calling this function in AppDelegate’s didFinishLaunchingWithOptions.

//Objective-C
Hyper *hyper = [[Hyper alloc] init];
[hyper preFetch:clientId];

//Swift
Hyper().preFetch(clientId)

Initializing Parameters

Since the SDK is an enhanced Payments Orchestrator, the input is typically a bunch of basic Payments payload.
The parameters are divided into two major components:

1. Base parameters
2. Service parameters

Base Parameters

Clients must make sure to add these required metrics while invoking Juspay SDK for payments. These metrics are crucial for the transaction to complete and for users to have a seamless experience. Find below the set of parameters which needs to be passed to us:

Service Params

1. Juspay Safe (in.juspay.godel)

2. Express Checkout (in.juspay.ec)

Making Payment on Express Checkout

Applicable only for the service "in.juspay.ec".
The payloads are passed as stringified JSON. This payload determines the action to be performed by the SDK. Please ensure that the correct payload is passed based on your existing configuration with Juspay and User action.

Sample request code

Objective-C

NSMutableDictionary *paymentParams = [[NSMutableDictionary alloc] init];
//Base Parameters
paymentParams[@"merchant_id"] = merchantId;
paymentParams[@"client_id"] = clientId;
paymentParams[@"customer_id"] = customerId;
paymentParams[@"customer_email"] = customerEmail;
paymentParams[@"customer_phone_number"] = mobileNumber;
paymentParams[@"environment"] = @"prod" | @"sandbox";
paymentParams[@"session_token"] = sessionToken;
//Payment Parameters
paymentParams[@"service"] = @"in.juspay.ec";
paymentParams[@"end_urls"] = @[returnUrl1, returnUrl2, ..];
paymentParams[@"order_id"] = orderId;
paymentParams[@"amount"] = amount;
//Payload
NSMutableDictionary *payload = [[NSMutableDictionary alloc] init];
[payload setObject:@"nbTxn" forKey:@"opName"];
[payload setObject:@"NB" forKey:@"paymentMethodType"];
[payload setObject:bankCode forKey:@"paymentMethod"];
[payload setObject:@"true" forKey:@"redirectAfterPayment"];
paymentParams[@"payload"] = [self dictionaryToString:payload];
//Starting the service
Hyper *hyper = [[Hyper alloc] init];
//Show loader
[hyper startViewController:self data:paymentParams callback:^(int status, id
responseData, NSError *error) {
    //Hide loader
    if (responseData) {
        //JSON Response
    } else {
        //Error
    }
}];

...

- (NSString *)dictionaryToString:(id)dict {
    if (!dict || ![NSJSONSerialization isValidJSONObject:dict]) {
        return @"{}";
    }
    NSString *data = [[NSString alloc] initWithData:[NSJSONSerialization
dataWithJSONObject:dict options:0 error:nil] encoding:NSUTF8StringEncoding];
    return data;
}

Swift

let paymentParams = NSMutableDictionary()
//Base Parameters
paymentParams["merchant_id"] = merchantId
paymentParams["client_id"] = clientId
paymentParams["customer_id"] = customerId
paymentParams["customer_email"] = customerEmail
paymentParams["customer_phone_number"] = mobileNumber
paymentParams["environment"] = "prod" | "sandbox"
paymentParams["session_token"] = sessionToken
//Payment Parameters
paymentParams["service"] = "in.juspay.ec";
paymentParams["end_urls"] = [returnUrl1, returnUrl2, ..]
paymentParams["order_id"] = orderId
paymentParams["amount"] = amount
//Payload
let payload = NSMutableDictionary()
payload["opName"] = "nbTxn"
payload["paymentMethodType"] = "NB"
payload["paymentMethod"] = bankCode
paymentParams["payload"] = self.dictionary(toString: payload)
//Starting the service
//Show loader
Hyper().start(self, data: paymentParams as! [AnyHashable : Any]) { (status,
responseData, error) in
    //Hide loader
    if ((responseData) != nil) {
        //JSON Response
    } else {
        //Error
    }
}

...

func dictionary(toString dict: Any?) -> String? {
    if let aDict = dict {
        if dict == nil || !JSONSerialization.isValidJSONObject(aDict) {
            return "{}"
        }
    }
    var data: String? = nil
    if let aDict = dict, let anError = try?
JSONSerialization.data(withJSONObject: aDict, options: []) {
        data = String(data: anError, encoding: .utf8)
    }
    return data
}

Payment Methods

(opName : getPaymentMethods)

Gives the list of all the payment methods available for your account.

Response:

Response Code = SUCCESS means the API response was successful. Please check with Juspay server through your server before marking an order as SUCCESS.

https://developer.juspay.in/reference#payment-methods

Card Transaction

(opName : cardTxn)

Response:

Response Code = SUCCESS means the API response was successful. Please check with Juspay server through your server before marking an order as SUCCESS.
https://developer.juspay.in/reference#credit-debit-card-transaction

NetBanking Transaction

(opName : nbTxn)

Response:

Response Code = SUCCESS means the API response was successful. Please check with Juspay server through your server before marking an order as SUCCESS.
https://developer.juspay.in/reference#netbanking-payment

Wallet Transaction

(opName : walletTxn)

The directWalletToken is required for wallets enabled for direct debit through Juspay and if the user has already linked the wallet. For wallets which the customer is not linked, the wallet should first be linked through createWallet operation and then allowed to make payment.

The sdkPresent param is used when wallet SDK are integrated into your app and Juspay is required to call the appropriate SDK for payment. For GooglePay, pass sdkPresent as IOS_GOOGLEPAY and for Simpl, pass sdkPresent as IOS_SIMPL.
Please check for SDK name as applicable.

AmazonPay / PayPal Redirection Flow

For AmazonPay / PayPal redirection flow, please follow the below steps for integrations.

1. Add the following properties in your app's Info.plist file:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>juspay-$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        </array>
    </dict>
</array>

2. Add the following code in the AppDelegate's 'application:openUrl:options' function:

//Objective-C

NSRegularExpression *juspayRegex = [NSRegularExpression regularExpressionWithPattern:@"juspay-.*" options:0 error:nil];
    
if ([juspayRegex numberOfMatchesInString:[url absoluteString] options:0 range:NSMakeRange(0, [[url absoluteString] length])] > 0) {
        
       return [Hyper handleRedirectURL:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

//Swift

let juspayRegex = try? NSRegularExpression(pattern: "juspay-.*", options: [])
        
if (juspayRegex?.numberOfMatches(in: url.absoluteString, options: [], range: NSRange(location: 0, length: url.absoluteString.count)) ?? 0) > 0 {
            
     return Hyper.handleRedirectURL(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

3. If user chooses to pay via AmazonPay / PayPal, call the walletTxn operation with the following payload data.

AmazonPay:
    
        {
        "opName" : "walletTxn",
        "paymentMethodType" : "Wallet",
        "paymentMethod" : "AMAZONPAY",
        "sdkPresent" : "IOS_AMAZONPAY_NONTOKENIZED"
    }


PayPal:
    
        {
        "opName" : "walletTxn",
        "paymentMethodType" : "Wallet",
        "paymentMethod" : "PAYPAL",
        "sdkPresent" : "IOS_PAYPAL"
    }

Please make sure to pass all the required parameters in the request as per the documentation.

📘

Note*

createWallet is not required for Paypal. For Paypal RT flow, linking happens via wallet transaction with shouldLInk:true only.
For Paypal Link and Pay flow, linking happens via wallet transaction with shouldLInk:true only along with metadata.PAYPAL:direct_wallet_version:v2 passed in Juspay Order Create request. Please refer to https://developer.juspay.in/reference#create-order-1 for specific parameters related to Paypal Link and Pay.

AmazonPay SDK Flow

For AmazonPay SDK flow, please follow the below steps for integrations.

1. Add your AmazonPay API key with the key name 'APIKey' and the following properties in your app's Info.plist file.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>amzn-$(PRODUCT_BUNDLE_IDENTIFIER)</string>
        </array>
    </dict>
</array>

2. Add the following code in the AppDelegate's 'application:openUrl:options' function:

//Objective-C

NSRegularExpression *amazonRegex = [NSRegularExpression regularExpressionWithPattern:@"amzn-.*" options:0 error:nil];
    
if ([amazonRegex numberOfMatchesInString:[url absoluteString] options:0 range:NSMakeRange(0, [[url absoluteString] length])] > 0) {
        
        return [Hyper handleRedirectURL:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

//Swift

let amazonRegex = try? NSRegularExpression(pattern: "amzn-.*", options: [])
        
if (amazonRegex?.numberOfMatches(in: url.absoluteString, options: [], range: NSRange(location: 0, length: url.absoluteString.count)) ?? 0) > 0 {
            
     return Hyper.handleRedirectURL(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

3. Before loading the payment page, please make sure to call the refreshWallet operation to check for balance if the wallet is already linked.

4. If user chooses to link AmazonPay wallet, call the createWallet operation (You have to pass your Amazon seller ID with the key named sdkWalletIdentifier in the payload). You will get AmazonPay linked status and the balance in the response.

5. If user chooses to pay via AmazonPay after linking, call the walletTxn operation with the following payload data.

{
        "opName" : "walletTxn",
        "paymentMethodType" : "Wallet",
        "paymentMethod" : "AMAZONPAY",
        "sdkPresent" : "IOS_AMAZONPAY_TOKENIZED"
    }

6. If user chooses to delink AmazonPay wallet, call the delinkWallet operation with appropriate payloads.

Please make sure to pass all the required parameters in the request as per the documentation.

When both directWalletToken and sdkPresent are null, the transaction is considered as a wallet Redirection transaction. The redirection URL will be loaded on the browser.

API reference: https://developer.juspay.in/reference#wallet-payment

Response:

Response Code = SUCCESS means the API response was successful. Please check with Juspay server through your server before marking an order as SUCCESS.

UPI Transaction

(opName : upiTxn)

Response:

Response Code = SUCCESS means the API response was successful. Please check with Juspay server through your server before marking an order as SUCCESS.

API reference: https://developer.juspay.in/reference#upi-payment

Create Wallet

(opName : createWallet)

This operation is called when a user tries to trigger OTP to link a wallet. An OTP is sent to the mobile no. linked with the Customer during Customer creation. Please ensure to pass the customer’s mobile number while creating the customer entity on Express Checkout.
The merchant should allow user to enter the OTP received and once the user submits the OTP, the linkWallet operation should be called. For resending OTP, authWallet operation needs to be called.

API reference: https://developer.juspay.in/reference#create

For AmazonPay SDK, please check the steps given in Wallet Transaction section

Response:

Link Wallet

(opName : linkWallet)

This operation is called after the user submits the OTP. The walletId can be found as a response parameter in the createWallet operation called earlier.

Response:

Delink Wallet

(opName = delinkWallet)

Response:

If wallet is delinked successfully, the linked will be “false” and token, currentBalance, lastRefreshed will be null.

Refresh Wallet

(opName : refreshWallet)

This operation can be used to get updated wallet balance and generate new wallet token.
In such cases, you need not call this operation. It is advisable to call this operation upfront from your server before coming to the payment page, to avoid latency on payment page. This wallet balance can be retrieved based on customer and does not require order creation.

Response:

Tokenize Card

(opName : tokenizeCard)

Response:

This operation is required only if Merchants plan to tokenize the card before initiating a payment under specific scenarios. Please note that a token is valid for only 15 minutes. The CVV is not needed on the following cardTxn operation using token since the token already captures CVV.

Card Info

(opName : cardInfo)

Response:

The cardInfo operation can be used to check the details of the card based on cardBin and ensure that the card is enabled for direct ATM PIN authentication support.

https://developer.juspay.in/reference#card-info

Delete Card

(opName : deleteCard)

Response:

This operation is used to delete a previously saved card from the user account.
https://developer.juspay.in/reference#delete-card

Authenticate Wallet

(opName : authWallet)

Response:

The authenticateWallet operation can be used to link a previously delinked wallet using the same wallet Id.

https://developer.juspay.in/reference#authenticate

List Wallets with Balances

(opName : refreshWalletBalances)

Response:

This operation needs to be called before loading the payment page to get the details of the wallets of the user. This operations gives list of linked wallets and their balances for the passed customerId.

Get Wallet

(opName : getWallet)

Response:

The getWallet operation helps to generate a new wallet token for initiating a wallet direct debit transaction. Please note that the balance will not be refreshed during this call. You will need to call refreshWallet operation to get updated Balance and also generate a new token.

https://developer.juspay.in/reference#get

Eligibility

(opName : eligibility)

Response:

Note: Order_id or amount should be passed in base params to check the eligibility.

Merchant Checklist

Please ensure that the following items are checked off before release to have a cleaner integration:

1. Ensure that correct value is sent for merchant_id and client_id to identify the Merchant.
2. Send a unique order_id to cross-check data with Juspay.
3. Ensure that session_token for in.juspay.ec are sent to SDK obtained from the Juspay server.
4. Get the final build tested by Juspay's QA team to check the functionalities.