Juspay Developer Guide

Welcome to the Juspay Developer Guide. You'll find comprehensive guides and documentation to help you start working with Juspay Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

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:

KeyDescriptionRequiredDefault
merchant_idIdentifies the merchant. Eg. merchId
Type : String
Yes
order_idOrderID generated by the merchant.
Type: String
Yes
client_idClientID is merchantId_ios Eg. 'merchId_ios'
Type : String
Yes
customer_idUnique identifier of the customer
Type : String
Yes
amountAmount of the transaction
Type : String
Yes
environmentCan be either prod or sandbox
Type : String
Yes
customer_emailCustomer's email address
Type : String
No
customer_phone_numberCustomer's phone number. Ensure the mobile number is mapped to the customerID is Juspay systems.
Type : String
No (mandatory for Simpl wallet)

Service Params

  1. Juspay Safe (in.juspay.godel)
KeyDescriptionRequiredDefault
serviceThe type of service, client wants to invoke. In.juspay.godel in this case
Type : String
Yes
end_urlsArray 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
urlStart URL for payment
Type : String
Yes
post_dataPOST parameters that must be passed to the URL
Type: String (Query String)
No
  1. Express Checkout (in.juspay.ec)
KeyDescriptionRequiredDefault
serviceThe type of service, client wants to invoke. In.juspay.ec in this case
Type : String
Yes
session_tokenThe client_auth_token obtained from Juspay Servers
Type : String
Yes
end_urlsArray 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
payloadJSON 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)

FieldTypeDescription
opName*StringMust be getPaymentMethods

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

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
"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)

FieldTypeDescription
opName*StringMust be cardTxn
paymentMethodType*StringMust be Card
paymentMethodStringCan be either VISA/MASTERCARD or any cardbrand. When authtype = ATMPIN and card details are not passed, mandatory to list the supported bank.
authTypeStringDefault is null.
ATMPIN for DebitCard authentication through ATM PIN (if enabled).
cardToken*StringMandatory for Saved cards transactions. Please ensure to get token from List card or Payment Methods every time.
cardNumber*StringMandatory for fresh card transaction. 16-19 digit card number.
cardExpMonth*StringMandatory for fresh card transaction
cardExpYear*StringMandatory for fresh card transaction
nameOnCardStringName present on card
cardSecurityCode*StringCVV 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"
isEmiStringDefault is set to "false"
emiBankStringRepresents the Card Issuing Bank
emiTenureStringTenure of EMI in months
emiTypeStringType of EMI ie, STANDARD_EMI or NO_COST_EMI

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be nbTxn
paymentMethodType*StringMust be NB
paymentMethod*StringActual method selected by the user.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be walletTxn
paymentMethodType*StringMust be Wallet
paymentMethod*StringName of Wallet select by user
directWalletTokenStringWallet token for direct debit transactions
sdkPresentStringName of SDK in Merchant App for SDK transactions
walletMobileNumberStringMobile 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.

  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>
  1. 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)
}
  1. 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>
  1. 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)
}
  1. Before loading the payment page, please make sure to call the refreshWallet operation to check for balance if the wallet is already linked.

  2. 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.

  3. 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"
    }
  1. 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:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be upiTxn
paymentMethodType*StringMust be UPI
paymentMethod*StringMust be UPI
currencyStringDefault is INR
custVpa*StringFor webcollect transactions. Collect request would be sent to this vpa.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*Stringmust be createWallet
walletName*StringName of the wallet
sdkWalletIdentifierStringAny 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:

FieldTypeValue
codeStringSUCCESS
payloadJSONotpPageEnabled = false
{walletID:: String ,wallet :: String linked :: Boolean}{ wallet:: String, token:: String, linked:: Boolean,walletId :: String,currentBalance:: Number, lastRefreshed:: String,}

Link Wallet

(opName : linkWallet)

FieldTypeDescription
opName*Stringmust be linkWallet
walletId*StringWalletID of the particular wallet
otp*StringOTP 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:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
wallet:: String,
token:: String,
linked:: Boolean,
walletId:: String,
object:: String,
currentBalance:: Number,
lastRefreshed:: String
}

Delink Wallet

(opName = delinkWallet)

FieldTypeDescription
opNameStringmust be delinkWallet
walletIdStringWalletID of the particular wallet
walletNameStringName of the wallet.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJson

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.

FieldTypeDescription
opName*Stringmust be refreshWallet
walletId*StringWalletID given by Juspay. Not required for Wallet SDK Integration
sdkWalletIdentifierStringAny specific identifier for SDK wallet Integration.
Eg. AmazonPay SellerID
walletName*StringWallet name. Mandatory for Wallet SDK Integration

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
walletId :: String,
object :: String,
wallet :: String,
token ::String,
currentBalance :: Number,
linked :: Boolean,
lastRefreshed :: String
}

Tokenize Card

(opName : tokenizeCard)

FieldTypeDescription
opName*StringMust be tokenizeCard
cardNumber*String16-19 digit card number.
cardExpYear*StringExpiry year on card
cardExpMonth*StringExpiry Month on card
cardSecurityCode*StringCVV of the card.
If CVV not present on card, send an empty string.
nameOnCardStringName on card.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMuse be cardInfo
cardBin*StringFirst 6 digits of card number
checkAtmPinAuthSupportBooleanNon Mandatory. If passed as TRUE, the ATM PIN support for the BIN will be checked.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMuse be deleteCard
cardToken*StringThis is a one time use token specific to a saved card that can be retrieved from List Stored Cards call

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be authWallet
walletId*StringId of wallet.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be refreshWalletBalances
sdkWalletIdentifierStringAny specific identifier for SDK wallet Integration.
Eg. AmazonPay SellerID

Response:

FieldTypeValue
codeStringSUCCESS
payloadJSON{
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)

FieldTypeDescription
opName*StringMust be getWallet
walletId*StringId of wallet.

Response:

FieldTypeValue
codeStringSUCCESS
payloadJson{
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)

FieldTypeDescription
opName*StringMust be eligibility

Response:

FieldTypeValue
codeStringSUCCESS
payloadJson{
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:

  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.

Updated about a month ago


iOS


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.