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:
- Base parameters
- 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:
Key | Description | Required | Default |
---|---|---|---|
merchant_id | Identifies the merchant. Eg. merchId Type : String | Yes | |
order_id | OrderID generated by the merchant. Type: String | Yes | |
client_id | ClientID is merchantId_ios Eg. 'merchId_ios' Type : String | Yes | |
customer_id | Unique identifier of the customer Type : String | Yes | |
amount | Amount of the transaction Type : String | Yes | |
environment | Can be either prod or sandbox Type : String | Yes | |
customer_email | Customer's email address Type : String | No | |
customer_phone_number | Customer's phone number. Ensure the mobile number is mapped to the customerID is Juspay systems. Type : String | No (mandatory for Simpl wallet) |
Service Params
- Juspay Safe (in.juspay.godel)
Key | Description | Required | Default |
---|---|---|---|
service | The type of service, client wants to invoke. In.juspay.godel in this case Type : String | Yes | |
end_urls | Array of Strings each of which will be interpreted as regular expressions.Every URLloaded (in onPageStarted) by the browser will be matched against each of the array items. If a match is found, then the browser stops further processing and delegates the control back to the app. Type: Array | Yes | |
url | Start URL for payment Type : String | Yes | |
post_data | POST parameters that must be passed to the URL Type: String (Query String) | No |
- Express Checkout (in.juspay.ec)
Key | Description | Required | Default |
---|---|---|---|
service | The type of service, client wants to invoke. In.juspay.ec in this case Type : String | Yes | |
session_token | The client_auth_token obtained from Juspay Servers Type : String | Yes | |
end_urls | Array of Strings each of which will be interpreted as regular expressions.Every URL loaded (in onPageStarted) by the browser will be matched against each of the array items. If a match is found, then the browser stops further processing and delegates the control back to the app. Type: Array | Yes | |
payload | JSON String to be passed. Check Making Payment on Express Checkout section below for more details on the payload. | Yes |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be getPaymentMethods |
Gives the list of all the payment methods available for your account.
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { "payment_methods": [ { "payment_method_type": "CARD", "payment_method": "VISA", "description": "Visa" }, { "payment_method_type": "NB", "payment_method": "NB_HDFC", "description": "HDFC" }, { "payment_method_type": "WALLET", "payment_method": "PAYTM", "description": "Paytm" },... ] } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be cardTxn |
paymentMethodType* | String | Must be Card |
paymentMethod | String | Can be either VISA/MASTERCARD or any cardbrand. When authtype = ATMPIN and card details are not passed, mandatory to list the supported bank. |
authType | String | Default is null. ATMPIN for DebitCard authentication through ATM PIN (if enabled). |
cardToken* | String | Mandatory for Saved cards transactions. Please ensure to get token from List card or Payment Methods every time. |
cardNumber* | String | Mandatory for fresh card transaction. 16-19 digit card number. |
cardExpMonth* | String | Mandatory for fresh card transaction |
cardExpYear* | String | Mandatory for fresh card transaction |
nameOnCard | String | Name present on card |
cardSecurityCode* | String | CVV of the card.If CVV not present on card, send an empty string. |
saveToLocker* | String | "true" if user accepts to save card to locker otherwise "false" |
isEmi | String | Default is set to "false" |
emiBank | String | Represents the Card Issuing Bank |
emiTenure | String | Tenure of EMI in months |
emiType | String | Type of EMI ie, STANDARD_EMI or NO_COST_EMI |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { orderId:: String, status :: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be nbTxn |
paymentMethodType* | String | Must be NB |
paymentMethod* | String | Actual method selected by the user. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { orderId :: String, status :: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be walletTxn |
paymentMethodType* | String | Must be Wallet |
paymentMethod* | String | Name of Wallet select by user |
directWalletToken | String | Wallet token for direct debit transactions |
sdkPresent | String | Name of SDK in Merchant App for SDK transactions |
walletMobileNumber | String | Mobile number to which wallet is linked. Used only for GooglePay |
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.
- 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>
- 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)
}
- 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.
- 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>
- 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)
}
-
Before loading the payment page, please make sure to call the
refreshWallet
operation to check for balance if the wallet is already linked. -
If user chooses to link AmazonPay wallet, call the
createWallet
operation (You have to pass your Amazon seller ID with the key namedsdkWalletIdentifier
in the payload). You will get AmazonPay linked status and the balance in the response. -
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"
}
- 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:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { orderId :: String, status :: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be upiTxn |
paymentMethodType* | String | Must be UPI |
paymentMethod* | String | Must be UPI |
currency | String | Default is INR |
custVpa* | String | For webcollect transactions. Collect request would be sent to this vpa. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { orderId :: String, status :: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | must be createWallet |
walletName* | String | Name of the wallet |
sdkWalletIdentifier | String | Any specific identifier for SDK wallet Integration. Eg. AmazonPay SellerID |
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:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | otpPageEnabled = false |
{walletID:: String ,wallet :: String linked :: Boolean | } | { wallet:: String, token:: String, linked:: Boolean,walletId :: String,currentBalance:: Number, lastRefreshed:: String,} |
Link Wallet
(opName : linkWallet)
Field | Type | Description |
---|---|---|
opName* | String | must be linkWallet |
walletId* | String | WalletID of the particular wallet |
otp* | String | OTP entered by the user |
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:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { wallet:: String, token:: String, linked:: Boolean, walletId:: String, object:: String, currentBalance:: Number, lastRefreshed:: String } |
Delink Wallet
(opName = delinkWallet)
Field | Type | Description |
---|---|---|
opName | String | must be delinkWallet |
walletId | String | WalletID of the particular wallet |
walletName | String | Name of the wallet. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | Json |
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.
Field | Type | Description |
---|---|---|
opName* | String | must be refreshWallet |
walletId* | String | WalletID given by Juspay. Not required for Wallet SDK Integration |
sdkWalletIdentifier | String | Any specific identifier for SDK wallet Integration. Eg. AmazonPay SellerID |
walletName* | String | Wallet name. Mandatory for Wallet SDK Integration |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { walletId :: String, object :: String, wallet :: String, token ::String, currentBalance :: Number, linked :: Boolean, lastRefreshed :: String } |
Tokenize Card
(opName : tokenizeCard)
Field | Type | Description |
---|---|---|
opName* | String | Must be tokenizeCard |
cardNumber* | String | 16-19 digit card number. |
cardExpYear* | String | Expiry year on card |
cardExpMonth* | String | Expiry Month on card |
cardSecurityCode* | String | CVV of the card. If CVV not present on card, send an empty string. |
nameOnCard | String | Name on card. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { cardToken::String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Muse be cardInfo |
cardBin* | String | First 6 digits of card number |
checkAtmPinAuthSupport | Boolean | Non Mandatory. If passed as TRUE, the ATM PIN support for the BIN will be checked. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { cardBin::String, object::String, brand::String, bank::String, country::String, type::String, atmPinAuthSupport:: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Muse be deleteCard |
cardToken* | String | This is a one time use token specific to a saved card that can be retrieved from List Stored Cards call |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { cardToken::String, cardReference::String, deleted::Boolean } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be authWallet |
walletId* | String | Id of wallet. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { walletId :: String, object :: String, wallet :: String, token :: String, currentBalance :: Number, linked :: Boolean, lastRefreshed :: String } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be refreshWalletBalances |
sdkWalletIdentifier | String | Any specific identifier for SDK wallet Integration. Eg. AmazonPay SellerID |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | JSON | { object :: String, offset :: Number list :: [{ walletId :: String, object :: String, wallet :: String, token :: String, currentBalance :: Number, linked :: Boolean, lastRefreshed :: String }, {}, {}], total :: Number, count :: Number } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be getWallet |
walletId* | String | Id of wallet. |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | Json | { wallet:: String, token:: String, linked:: Boolean, walletId :: String, object:: String, currentBalance:: Number, lastRefreshed:: String, } |
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)
Field | Type | Description |
---|---|---|
opName* | String | Must be eligibility |
Response:
Field | Type | Value |
---|---|---|
code | String | SUCCESS |
payload | Json | { paymentMethodsEligibility :: [{ status :: String, isEligible :: Boolean, paymentMethodType :: String, eligibilityStrategy :: String, paymentMethod :: String, description :: String, balance :: Number }] } |
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:
- Ensure that correct value is sent for merchant_id and client_id to identify the Merchant.
- Send a unique order_id to cross-check data with Juspay.
- Ensure that session_token for in.juspay.ec are sent to SDK obtained from the Juspay server.
- Get the final build tested by Juspay's QA team to check the functionalities.
Updated 4 months ago