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

Android

Added sdkwalletidentifier param for amazonpay refreshwallet

ExpressCheckout Module

Introduction

The Express Checkout SDK provides an easier way for merchants to directly call Express Checkout APIs securely from the client Android device. The SDK is an API layer without any UI and simplifies integration effort.

Get the SDK

The Android SDK library can be added as a direct dependency when you use Gradle. Add the following maven repository to the build.gradle. Please make sure that you add it in the project dependency section and NOT the buildScript section.

repositories {
    mavenCentral()
    maven {
       url "https://maven.juspay.in/jp-build-packages/release/"
    }
}

Add the following compile dependency to your project. Once again make sure you don’t accidentally add it to script dependencies.

dependencies {
    compile 'in.juspay:godel-ec:1.0.7.28'
}

PreFetching Juspay Assets

Since the SDK uses a MicroService architecture on top of Android, it is highly recommended to call preFetch. Calling the function before SDK initiation will download the latest code and update it locally. It should be called a good amount of time before SDK initiation as it might take some time to download the assets (the earlier, the better).

PaymentActivity.preFetch(activity, clientId);

πŸ“˜

Note: ClientId is of the format "merchantId_android".

Initializing Bundle Parameters

The parameters are grouped into three major components:

  1. Payments SDK parameters
  2. Service parameters
  3. Custom parameters

Payments SDK Parameters

Clients must make sure to add these required metrics while invoking PaymentsSDK. These parameters are crucial in initiating the SDK and for analytics. Find below the set of parameters which needs to be passed:

VariableDescriptionMandatoryType
PaymentConstants.MERCHANT_IDMerchantId given by Juspay ExpressCheckout while registration.YesString
PaymentConstants.CLIENT_IDClientID is a merchant SDK identifier. Eg. 'merchantId_android'.YesString
PaymentConstants.ORDER_IDMerchant OrderID created at Juspay during create_order server call. Mandatory for initiating PaymentsYesString
PaymentConstants.AMOUNTAmount of the transaction.NoString
PaymentConstants.CUSTOMER_IDUnique identifier of the customer.NoString
PaymentConstants.CUSTOMER_EMAILCustomer's email address.NoString
PaymentConstants.CUSTOMER_MOBILECustomer's phone number.NoString
PaymentConstants.ENVCan be either PaymentConstants.ENVIRONMENT.SANDBOX or PaymentConstants.ENVIRONMENT.PRODUCTIONNoString

Service Parameters

The service Parameters are specific to the type of service being invoked. For accessing the Express Checkout APIs, the following parameters need to be passed in addition to the Payment SDK parameters described above.

VariableDescriptionMandatoryType
PaymentConstants.SERVICEThe type of service, a client wants to invoke. "in.juspay.ec"YesString
PaymentConstants.CLIENT_AUTH_TOKENThe payment session token obtained from Juspay Servers from create_order API callYesString
PaymentConstants.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.YesArrayList
PaymentConstants.PAYLOADJSON string to be passed. This parameter defines the action to be performed by the SDK. Refer Payload section below.YesString

Custom Parameters

Custom Parameters are meant for future use in case we decide to add new parameters for merchant specific requirements and analytical purposes. Custom Parameters are always prefixed with "udf_" and preferred to be a String type value.

VariableDescriptionMandatoryType
udf_Custom FieldNoString
udf_Custom FieldNoString

Sample Code

Below is a sample code for initializing Juspay SDK

Bundle juspayBundle = new Bundle();

// Base Parameters

juspayBundle.putString(PaymentConstants.MERCHANT_ID, getJuspayMerchantID());
juspayBundle.putString(PaymentConstants.CLIENT_ID, getJuspayClientId());
juspayBundle.putString(PaymentConstants.ORDER_ID, getOrderId());
juspayBundle.putString(PaymentConstants.AMOUNT, getOrderAmount());
juspayBundle.putString(PaymentConstants.CUSTOMER_ID, getCustomerId());
juspayBundle.putString(PaymentConstants.CLIENT_EMAIL, getCustomerEmail());
juspayBundle.putString(PaymentConstants.CLIENT_MOBILE_NO, getCustomerMobile());
juspayBundle.putString(PaymentConstants.ENV, PaymentConstants.ENVIRONMENT.PRODUCTION);

// Service Parameters for in.juspay.ec

juspayBundle.putString(PaymentConstants.SERVICE, "in.juspay.ec");
juspayBundle.putString(PaymentConstants.CLIENT_AUTH_TOKEN , getJuspayClientAuthToken());
juspayBundle.putStringArrayList(PaymentConstants.END_URLS, getEndUrls());
juspayBundle.putString(PaymentConstants.PAYLOAD, juspayPayload.toString());

Starting the SDK

SDK can be started as a new activity or attached as a Fragment to the merchant activity.

Activity Based Integration

To start the SDK as an Android Activity, you can use the following snippet:

// Start Payment Activity

Intent juspayIntent = new Intent(this, PaymentActivity.class);
juspayIntent.putExtras(juspayBundle);
startActivityForResult(juspayIntent, JUSPAY_REQUEST_CODE);

Response will be handled in onActivityResult of your calling Activity

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {      
    super.onActivityResult(requestCode, resultCode, data); //mandatory

    if(requestCode == JUSPAY_REQUEST_CODE) {
        if(resultCode == Activity.RESULT_OK) { // Success Response
            Log.d("success_response", data.getStringExtra(PaymentConstants.PAYLOAD));
        } else if (resultCode == Activity.RESULT_CANCELLED) { // Failure or Abort Response
            Log.d("failure_response", data.getStringExtra(PaymentConstants.PAYLOAD));
        }
    }      
 }

Fragment Based Integration

To attach the SDK as a Fragment to your existing activity, you can use the following snippet:

Create a PaymentFragment instance:

PaymentFragment fragment = new PaymentFragment();

Create a Callback Listener to listen for events:

JuspayCallback juspayCallback = new JuspayCallback() {
   @Override
   public void onResult(int requestCode, int resultCode, @Nullable Intent intent) {
       Log.d("MerchantActivity", "onResult: " + requestCode + " resultCode " + resultCode);
       removeFragment(fragment);
       fragment = null;
   }
};
fragment.setJuspayCallback(juspayCallback);

Pass the back pressed event to the fragment:

@Override
public void onBackPressed() {
   if(fragment != null && fragment.isAdded()) {
       fragment.backPressHandler(true);
   } else {
       super.onBackPressed();
   }
}

Pass the onActivityResult to fragment by calling super:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {      
    super.onActivityResult(requestCode, resultCode, data); //mandatory

    ...
    ...
    // Merchant Code
}

Attach the fragment to your Activity:

fragment.setArguments(juspayBundle);
fragment.setJuspayCallback(juspayCallback);
showFragment(fragment);

Attaching custom webviewclient. (during payments)

fragment.setWebViewClient(new SampleWebViewClient(fragment.getWebView(), fragment));

πŸ“˜

Note: Please note that the custom webviewclient should extend JuspayWebViewClient. And set it before attaching it to the activity.

Response handling

Please find below sample success and failure responses for any payment. Please make sure to get the final status checked from Express Checkout server.

Sample Payment Success Response

FieldTypeValue
responsePayloadjson string"{orderId : String, status : String}"
{
  orderId : "order_1234",
  status : "CHARGED"
}

Sample Error Response

FieldTypeValue
responsePayloadjson string"{code : int , status : string, response : json }"
{
  code : 0,
  status : "AUTHENTICATION_FAILED" 
  response : { errorCode: string, errorMessage : String}
}

Payment Payload
This section contains all the possible payloads for the in.juspay.ec service. Upon completion, the β€œonActivityResult” shall be invoked. The payload can be called from intent.getStringExtra(PaymentConstants.PAYLOAD)".

The payload is passed as Stringified JSON in PaymentConstants.PAYLOAD. 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.

The following Operations are used to perform all activities related to Payment from the Mobile Application.

Credit/Debit Card Payment

This operation is called while making a card transaction from the client device. The same operation can be used for both stored cards and new cards with appropriate parameters. The details of the saved cards can be fetched through List stored cards API.

VariableDescriptionMandatoryType
opNameMust be cardTxnYesString
paymentMethodMandatory only for ATMPIN authType, should be from supported banks.YesString
authTypeDefault is null. ATMPIN for DebitCard authentication through ATM PIN (if enabled).Only for ATM PIN transactionsString
cardTokenThis is a one-time use token for paying through a saved card. Can be generated from List Stored Cards operationString
cardNumber16-19 digit card number entered by the user.Only for fresh card transactions.String
cardExpMonthThe expiry month of the card that can be found on the cardMandatory for fresh card transactionString
cardExpYearThe expiry month of the card that can be found on the cardMandatory for fresh card transactionString
nameOnCardName present on cardNoString
cardSecurityCodeCVV of the card. If CVV not present on the card, send an empty string.YesString
saveToLockerFor a new card transaction, determines whether the card needs to be saved for future use. Default is false. True if the user accepts to save the card to the locker.NoBoolean
isEmiDefault is set to FALSENoBoolean
emiBankRepresents the Card Issuing Bank. Refer EMI Support MatrixNoString
emiTenureTenure of EMI in months. Refer EMI Support MatrixNoString
emiTypeType of EMI ie STANDARD_EMI or NO_COST_EMINoString
// STORED CARD TRANSACTION

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","cardTxn");
juspayPayload.put("cardToken",storedCardObject.cardToken);
juspayPayload.put("cardSecurityCode",””);
juspayPayload.put("isEmi",””);
juspayPayload.put("emiBank",””);
juspayPayload.put("emiTenure",””);
juspayPayload.put("emiType",””);
// NEW CARD TRANSACTION

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","cardTxn");
juspayPayload.put("cardNumber","");
juspayPayload.put("cardExpMonth",””);
juspayPayload.put("cardExpYear",””);
juspayPayload.put("nameOnCard",””);
juspayPayload.put("cardSecurityCode",””);
juspayPayload.put("saveToLocker",””);
juspayPayload.put("isEmi",””);
juspayPayload.put("emiBank",””);
juspayPayload.put("emiTenure",””);
juspayPayload.put("emiType",””);

Refer here to understand more about the API.

Netbanking Transaction

The Bank selected by the user needs to be passed in the paymentMethod Parameter. Please ensure to pass the correct string in this Parameter. The list of banks enabled through Juspay can be generated from the List Enabled Payment Methods operation.

VariableDescriptionMandatoryType
opNameMust be nbTxnYesString
paymentMethodBased on the bank selected by the userYesString
// NETBANKING TRANSACTION

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","nbTxn");
juspayPayload.put("paymentMethod",”NB_HDFC”);

Refer here to understand more about the API.

UPI Transaction

UPI transactions can happen through either the webcollect flow (user enters his VPA) or intent flow (user selects one of the UPI enabled Apps on his android phone).

Juspay provides a standalone UPI SDK that supports webcollect and intent flow along with the required UI to enabled seamless UPI payments. However, merchants can also call Juspay with directly with the VPA(webcollect) or Android App package name (intent).

VariableDescriptionMandatoryType
opNameMust be upiTxnYesString
paymentMethodMust be UPIYesString
displayNoteAny message to be displayed on UPI loading page/ Intent PSP UPI ApplicationNoString
upiSdkPresentDepends on UPI Payment Gateway.YesBoolean
custVpaFor webcollect transactions. UPI Collect request would be sent to this VPA.NoString
payWithAppPackage name of UPI app, for direct intent transactionsNoString
// UPI TRANSACTION

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","upiTxn");
juspayPayload.put("paymentMethod","UPI");
juspayPayload.put("displayNote","merch");
juspayPayload.put("upiSdkPresent",true);
juspayPayload.put("custVpa","");
juspayPayload.put("payWithApp","");

πŸ“˜

Reference

  1. Refer here to understand more about UPI web collect API.
  2. Refer here to understand more about UPI intent API.
  3. Please confirm with Juspay support team if UPI SDK is supported for your Payment Gateway

Note: Please confirm with the Juspay team whether your Payment Aggregator is supported for the specific flow before integration.

Wallet Transaction

Juspay supports most wallets in India for both redirection and Link & Pay flows.

In redirection mode, the user is taken to the wallet URL for payment where the user is required to enter his credentials and log in. The user needs to link his wallet every time.

For Link & Pay, the user can link his wallet to the Merchant using a one-time authentication. Post that, the wallet balance can be displayed on the merchant page itself. If sufficient balance is present, the wallet balance can be used for the payment. For insufficient balance, the user will be redirected to add money to the wallet page.

VariableDescriptionMandatoryType
opNameMust be walletTxnYesString
paymentMethodName of Wallet select by userYesString
directWalletTokenWallet token for direct debit transactionsNoString
sdkPresentName of SDK in Merchant App for SDK transactionsNoString
walletMobileNumberMobile number to which wallet is linked. Used only for GooglePayNoString
shouldLinkPass true if wallet needs to be linked. Used only for PayPalNoBoolean
Wallet FlowsdkPresent value
Amazon pay redirectionANDROID_AMAZONPAY_NONTOKENIZED
Amazon link and payANDROID_AMAZONPAY_TOKENIZED
PayPal redirection/automaticANDROID_PAYPAL
PhonePeANDROID_PHONEPE
GooglepayANDROID_GOOGLEPAY
SIMPLANDROID_SIMPL

// WALLET TRANSACTION

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","walletTxn");
juspayPayload.put("paymentMethod","walletObject.walletName");
juspayPayload.put("directWalletToken","walletObject.walletToken");
juspayPayload.put("sdkPresent",""walletObject.walletSdkName"");
juspayPayload.put("walletMobileNumber","walletObject.mobileNumber");
juspayPayload.put("shouldLink","walletObject.shouldLink");

πŸ“˜

Note: Please confirm with Juspay team whether your Payment Aggregator is supported for the specific flow before integration.

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.

πŸ“˜

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.

Refer to https://developer.juspay.in/reference#googlepay-integration for GooglePay Integration.

The sdkPresent Param is used when wallet SDK is integrated into your app and Juspay is required to call the appropriate SDK for payment.

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 and transaction completed.

Refer here to understand more about wallet direct debit API.

Refer here to understand more about wallet redirection API.

Displaying Payment Options

The below operations needs to be called before the payment page is shown to the user. This helps merchants to decide on the payment options to be shown to the user. These details can also be fetched through server calls also through respective APIs. It is not required to create an order for calling these operations.

  1. List wallets with an updated balance
  2. List saved cards
  3. List enabled payment options
  4. Check for device-specific App/SDK

List wallets with an updated balance

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

VariableDescriptionMandatoryType
opNamemust be refreshWalletBalancesYesString
// LIST ALL LINKED WALLETS WITH UPDATED BALANCES

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","refreshWalletBalances");

Response Payload:

Please get the status of the wallet from _"linked" flag in the response.

{
  total::Int,
  offset::Int,
  object::String,
  list::Array
     {
        wallet::String,
        token::String,
        object::String,
        linked::Boolean,
        id::String,
        lastRefreshed::String, 
        currentBalance:: Number, 
        metadata :: Json //  Optional. Example: {"email": "[email protected]","payerId":"abcdef"}
     },
  count::Int
}

{
{
  wallet::  String,
  token::  String,
  linked::  Boolean,
  walletId :: String,  
  currentBalance::  Number,
  lastRefreshed::  String,
},{},{}
}

List saved cards

This operation needs to be called before loading the payment page to get the details of the cards stored by the user.

VariableDescriptionMandatoryType
opNamemust be cardListYesString
// LIST STORED CARDS

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","cardList");

Response Payload:

{
  "customer_id": "guest_user",
  "merchantId": "guest",
  "cards": [
    {
      "card_token": "2ea1fc4d-cbeb-4df7-b03d-97198e5c5e4e",
      "card_reference": "20d67719b2249ccd375f44fd98817a47",
      "card_fingerprint": "f6f6ac14a9438561404e8ec0776d",
      "card_number": "5264-XXXXXXXX-3394",
      "card_isin": "526419",
      "card_exp_year": "2014",
      "card_exp_month": "10",
      "card_type": "DEBIT",
      "card_issuer": "HDFC BANK",
      "card_brand": "MASTERCARD",
      "nickname": "",
      "name_on_card": "Real Card",
      "expired": true
    }
  ]
}

List enabled payment options

This operation gives the details of all eligible payment methods enabled for the merchant via Juspay. Any payment option not shown as part of this operation, must not be sent to Juspay for processing.

VariableDescriptionMandatoryType
opNamemust be getPaymentMethodsYesString
// LIST ENABLED PAYMENT METHODS

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","getPaymentMethods");

Response Payload:

{
   "payment_methods":
  [
    {
      "payment_method_type": "CARD",
      "payment_method": "VISA",
      "description": "Visa"
    },
    {
      "payment_method_type": "CARD",
      "payment_method": "MASTER",
      "description": "Master Card"
    },
    {
      "payment_method_type": "NB",
      "payment_method": "NB_HDFC",
      "description": "HDFC"
    },
    {
      "payment_method_type": "WALLET",
      "payment_method": "PAYTM",
      "description": "Paytm"
    },
  ]
}

Delete Card
This operation is used to delete a previously saved card from the user account.

VariableDescriptionMandatoryType
opNamemust be deletecardYesString
cardTokenThis is a one time use token specific to a saved card that can be retrieved from List Stored Cards callYesString
// CHECK FOR DEVICE SPECIFIC APP/SDK

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","deleteCard");
juspayPayload.put("cardToken","c75a9fca-1121-418e-973c-47d5c4971456");

Response Payload:

The deleted field is a boolean which will confirm if the delete activity was successful. Will be true when the card is deleted.

{
  card_token :: string
  card_reference :: string
  deleted :: boolean, 
} 

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.

Check for device-specific App/SDK

This operation helps the merchant to check for any device-specific App or SDK required before displaying a payment option on the UI or allowing the user to make a payment.

VariableDescriptionMandatoryType
opNamemust be isDeviceReadyYesString
sdkPresentsdk to be checked on the deviceYesString
// CHECK FOR DEVICE SPECIFIC APP/SDK

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","isDeviceReady");
juspayPayload.put("sdkPresent","ANDROID_GOOGLEPAY");

Response Payload:

{
  {
    status : boolean, 
    message : string
  }  
}

Please consider the app/SDK to be present on the Merchant device when the status returns true.

Linking User Wallet

The Juspay SDK supports linking the User Wallet to the merchant account, which enables one-click payment through wallets. The following operations allow merchants to execute the link and Pay flow from client side.

While it is not mandatory to create an order in Juspay Backend for utilizing these operations, the sessionToken needs to be freshly generated using the get_customer_token API. Refer here. (need to add API reference)

Refresh Wallet
The refreshWallet operation can be used to check if a particular wallet is already linked for a customer, update latest balance and generate a new token if already linked. Please note that the token is of one time usage only.

VariableDescriptionMandatoryType
opNamemust be refreshWalletYesString
walletIdWalletID given by Juspay. Not required for Wallet SDK Integration(Ex: AmazonPay)YesString
sdkWalletIdentifierSeller Id only for AmazonPayYesString
walletNameName of the WalletNoString
// REFRESH WALLET

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","refreshWallet");
juspayPayload.put("walletId","walletObject.walletID");
juspayPayload.put("walletName","walletObject.walletName");

Please get the status of the wallet from _"linked" flag in the response.

Response Payload Format:

{
  wallet ::  String,
  token ::  String,
  linked ::  Boolean,
  walletId :: String,  
  currentBalance ::  Number,
  lastRefreshed ::  String
}
FieldTypeWhen wallet is linkedWhen wallet is not linked
walletStringName of the walletName of the wallet
tokenStringOne-time use token to be used for making a direct debit transactionNull
linkedBooleanTRUEFALSE
walletIdStringwalletID generated by Juspay. Unique for a user, merchant, wallet combination. Not present for AMAZONPAYNA
currentBalanceNumberWallet balance of the customerNULL
lastRefreshedStringTimestamp when the balance was last updated in UTC.NULL

Refer here for more on refreshWallet API.

Create Wallet to trigger OTP
The createWallet operation is to be called when the User clicks on Link Account for a specific wallet on the Payment page. An OTP would be triggered to the mobile number linked to the customer_ID on Juspay.

VariableDescriptionMandatoryType
opNamemust be createWalletYesString
walletNameName of the walletYesString
sdkWalletIdentifierAny specific identifier for SDK wallet Integration.NoString
mobileNumberMobileNumber to which wallet needs to be linked. Not required if the same mobile number is previously mapped against customer entityNoString

Refer here for more on createWallet API.

// CREATE WALLET TO TRIGGER OTP

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","createWallet");
juspayPayload.put("walletName",walletObject.walletName);
juspayPayload.put("sdkWalletIdentifier",walletObject.sdkWalletIdentifier);
juspayPayload.put("mobileNumber",walletObject.mobileNumber);

πŸ“˜

Note:

  1. The UI for entering the OTP has to be handled by the Merchant.
  2. sdkWalletIdentifier is required for specific usecases where Merchant has integrated with Wallet SDKs independantly and needs to pass specific parameters to the SDK. eg. AmazonPay SellerId.
  3. The walletId parameter in the response will need to persisted and submitted along with the OTP.
  4. The operation can be called for resend OTP also.

Link Wallet
The linkWallet operation can be used for submitting the OTP entered by the User.

VariableDescriptionMandatoryType
opNamemust be linkWalletYesString
walletIdWalletID of the particular walletYesString
otpOTP entered by the userYesString
// LINK WALLET TO SUBMIT OTP

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","linkWallet");
juspayPayload.put("walletId",walletObject.walletId);
juspayPayload.put("otp",walletObject.otp);

When the OTP is entered correctly, the wallet will be linked and the updated balance will be passed in the response.
For incorrect OTP, appropriate error messages will be passed.

Refer here for more on linkWallet API.

Delink Wallet
This operation helps the user to delink a previously linked wallet.

VariableDescriptionMandatoryType
opNamemust be delinkWalletYesString
walletIdWalletID of the particular walletYesString
walletNameName of the walletYesString
// DELINK WALLET

JSONObject juspayPayload = new JSONObject();
juspayPayload.put("opName","delinkWallet");
juspayPayload.put("walletId",walletObject.walletId);
juspayPayload.put("walletName",walletObject.walletName);

Once delinked, users will have to link their wallet again to make payment.

Refer here for more on delinkWallet API.

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.

Integration 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. Please ensure that customer details are already updated on Juspay backend.
  4. Make sure to pass backpress event onBackPressed and call super.onActivityResult (in case of Fragment Based Integration).
  5. Get the final build tested by Juspay's QA team.

Juspay Safe Module

Introduction

JusPay Safe Browser (codename: Godel) aims to reduce friction in Second Factor Authentication for Cards and Netbanking.

The library provides various convenience and security features for users to be able to complete the transaction quickly. The library also provides much deeper insight into the events occurring in the payment flow. With Godel, you will be able to provide a pleasing payments experience to your Android users.

This documentation explains the steps to integrate the library into your native Android application.

Get the SDK

The Android SDK library can be added as a direct dependency when you use Gradle. Add the following maven repository to the build.gradle. Please make sure that you add it in the project dependency section and NOT the buildScript section.

repositories {
    mavenCentral()
    maven {
       url "https://maven.juspay.in/jp-build-packages/release/"
    }
}

Add the following compile dependency to your project. Once again make sure you don’t accidentally add it to script dependencies.

dependencies {
    compile 'in.juspay:godel-core:1.0.7'
}

πŸ“˜

Brief change log is available here

PreFetching Juspay Assets

Since the SDK uses a Micro Service architecture on top of Android, it is highly recommended to call the preFetch api.

PaymentActivity.preFetch(activity, clientId);

πŸ“˜

Note: ClientId is of the format "merchantId_android".

Initializing Bundle Parameters

Since the SDK is an enhanced Payments Orchestrator, the input is typically a bunch of basic Payments payload, passed via Bundle.

The parameters are grouped into three major components:

  1. Payments SDK parameters
  2. Service parameters
  3. Custom parameters

Payments SDK Parameters

Clients must make sure to add these required metrics while invoking PaymentsSDK. These parameters are crucial in initiating the SDK and for analytical purposes. Find below the set of parameters which needs to be passed:

VariableDescriptionMandatoryType
PaymentConstants.MERCHANT_IDMerchantId is given by JuspayYesString
PaymentConstants.CLIENT_IDClientID created in Merchant Portal. Eg. 'merchant_android'.YesString
PaymentConstants.TRANSACTION_IDRepresents the current transactionId.NoString
PaymentConstants.ORDER_IDOrderID is the alternative to transactionId.NoString
PaymentConstants.AMOUNTAmount of the transaction.YesString
PaymentConstants.CUSTOMER_IDUnique identifier of the customer.NoString
PaymentConstants.CUSTOMER_EMAILCustomer's email address.NoString
PaymentConstants.CUSTOMER_MOBILECustomer's phone number.NoString
PaymentConstants.ENVCan be either PaymentConstants.ENVIRONMENT.SANDBOX or PaymentConstants.ENVIRONMENT.PRODUCTIONNoString

Service Parameters

The service Parameters are specific to the type of service being invoked. For initializing the JuspaySafe Browser, the following parameters need to be passed in addition to the Payment SDK parameters described above.

VariableDescriptionMandatoryType
PaymentConstants.SERVICEThe type of service, client wants to invoke. "in.juspay.godel" for JuspaySafe BrowserYesString
PaymentConstants.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.Yes (For Activity Based Integration)ArrayList
PaymentConstants.URLStart URL for paymentYesString
PaymentConstants.POST_DATAPOST parameters that must be passed to the URLNoString
"clearCookies"If true, we will clear WebView cookies whenever Juspay Webview is initialized. Default will be falseNoBoolean

Custom Parameters

Custom Parameters are meant for future use in case we decide to add new parameters for merchant specific requirements and analytical purposes. Custom Parameters are always prefixed with "udf_" and preferred to be a String type value.

VariableDescriptionMandatoryType
udf_<var1Custom FieldNoString
udf_<var2Custom FieldNoString

Sample Parameters

Below is a sample set of params for starting the SDK:

Bundle juspayBundle = new Bundle();

// Base Parameters

juspayBundle.putString(PaymentConstants.MERCHANT_ID, getJuspayMerchantID());
juspayBundle.putString(PaymentConstants.CLIENT_ID, getJuspayClientId());
juspayBundle.putString(PaymentConstants.ORDER_ID, getOrderId());
juspayBundle.putString(PaymentConstants.AMOUNT, getOrderAmount());
juspayBundle.putString(PaymentConstants.CUSTOMER_ID, getCustomerId());
juspayBundle.putString(PaymentConstants.CLIENT_EMAIL, getCustomerEmail());
juspayBundle.putString(PaymentConstants.CLIENT_MOBILE_NO, getCustomerMobile());
juspayBundle.putString(PaymentConstants.ENV, PaymentConstants.ENVIRONMENT.PRODUCTION);

// Service Parameters for in.juspay.ec

juspayBundle.putString(PaymentConstants.SERVICE, "in.juspay.godel");
juspayBundle.putStringArrayList(PaymentConstants.END_URLS, getEndUrls());
juspayBundle.putString(PaymentConstants.URL, startUrl);

Starting the SDK

SDK can be started as a new activity or attached as a Fragment to the merchant activity.

Activity Based Integration

To start the SDK as an Android Activity, you can use the following snippet:

// Start Payment Activity

Intent juspayIntent = new Intent(this, PaymentActivity.class);
juspayIntent.putExtras(juspayBundle);
startActivityForResult(juspayIntent, JUSPAY_REQUEST_CODE);

Response will be handled in onActivityResult of your calling Activity

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {      
    super.onActivityResult(requestCode, resultCode, data); //mandatory

    if(requestCode == JUSPAY_REQUEST_CODE) {
        if(resultCode == Activity.RESULT_OK) { // Success Response
            Log.d("success_response", data.getStringExtra(PaymentConstants.PAYLOAD));
        } else if (resultCode == Activity.RESULT_CANCELLED) { // Failure or Abort Response
            Log.d("failure_response", data.getStringExtra(PaymentConstants.PAYLOAD));
        }
    }      
 }

Fragment Based Integration

To attach the SDK as a Fragment to your existing activity, you can use the following snippet:

Create a PaymentFragment instance:

PaymentFragment fragment = new PaymentFragment();

Create a Callback Listener to listen for events:

JuspayCallback juspayCallback = new JuspayCallback() {
   @Override
   public void onResult(int requestCode, int resultCode, @Nullable Intent intent) {
       Log.d("MerchantActivity", "onResult: " + requestCode + " resultCode " + resultCode);
       removeFragment(fragment);
       fragment = null;
   }
};
fragment.setJuspayCallback(juspayCallback);

Pass the back pressed event to the fragment:

@Override
public void onBackPressed() {
   if(fragment != null && fragment.isAdded()) {
       fragment.backPressHandler(true);
   } else {
       super.onBackPressed();
   }
}

Pass the onActivityResult to fragment by calling super:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {      
    super.onActivityResult(requestCode, resultCode, data); //mandatory

    ...
    ...
    // Merchant Code
}
Attach the fragment to your Activity:
fragment.setArguments(juspayBundle);
fragment.setJuspayCallback(juspayCallback);
showFragment(fragment);

Attaching custom webviewclient. (during payments)

fragment.setWebViewClient(new SampleWebViewClient(fragment.getWebView(), fragment));

Response Payload Details

The response payload will be sent in data.getStringExtra(PaymentConstants.PAYLOAD). Find below the set of parameters which will be sent:

VariableDescriptionTypeExample
realtimeA JSON Object that has the system metricsJSON{"last_visited_url":"https://www.sampleurl.com/success","backPressed":"true", "otp_detected":"true","otp_approved":"auto","sms_permission":"true" }
urlThe url at which transaction was completedString"https://www.sampleurl.com/success"

Send Payment Status

As soon as the payment is over, send us the notification on the status of the payment. These responses are crucial in order to track transaction success/failure metrics.

GodelTracker.getInstance().trackPaymentStatus(:transactionId,
        GodelTracker.SUCCESS);

Payment status can be one of: SUCCESS, FAILURE or CANCELLED.

POSTing from Server

To minimize the chances of missing payment status, we would recommend you to POST this information to our servers directly using the following call. This could be in addition to the call on GodelTracker in the client.

POST https://logs.juspay.in/godel/analytics

HTTP/1.1
Content-Type: application/json

{
    "data": [{
        "merchant_id": "your_merchant_id",
        "client_id": "your_client_id",
        "order_id": "ORD141231112205308",
        "transaction_id": "ORD141231112205308",
        "payment_status": "SUCCESS"
    }]
}

In the above, we recommend that you send both order_id and transaction_id if you are initializing the fragment with these. However, one of them would suffice as long as uniqueness is achieved.

We rely greatly on the payment status metrics to fine tune our system (both current and future versions). Failure to send status metrics might result in us disabling the enhancements for your customers.

Integration checklist

  1. Make sure to pass back press event onBackPressed and call super.onActivityResult (in case of Fragment-Based Integration).
  2. Send payment_status via GodelTracker.trackPaymentStatus or POST this information to our servers directly. We would recommend server-side POST technique as it is 100% reliable.
  3. Get the final build tested by Juspay's QA team.

Updated 21 days ago


Android


Added sdkwalletidentifier param for amazonpay refreshwallet

Suggested Edits are limited on API Reference Pages

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