search

Native Apps Integration

The native SDKs for Custom UI solution allows you to integrate the same in your native Apps for both Android and iOS. This document provides the steps required to integrate the solution in your App for processing seamless payments from your customers.

Custom UI SDK Android versions

The Custom UI SDK for Android is available with different versions. These versions support different features as per your requirements. Please refer to the table below for different supported versions.

Android SDK version Features Status
com.paytm.nativesdk:core:1.0.6 Includes core SDK feature with Direct bank integration Published
com.paytm.nativesdk:core-nodp:1.0.5 Includes core SDK features without Direct bank page Published
com.paytm.nativesdk:core-wr:1.0.7 Includes core SDK features along with Redirection support and App invoke for wallet balance insufficient Published
com.paytm.nativesdk:core-vs:1.0.0 Includes core SDK features along with Visa one click Available on request
com.paytm.nativesdk:core-ep:1.0.0 Includes core SDK features along with OTP Auto read through Assist Available on request

Pre-requisties

Before starting the integration, make sure you follow the steps below:

  1. Create an account on Paytm as a merchant. Click on how to create an account.

  2. Get the merchant Id and merchant key for the integration environment after creating the account.

  3. The additional details such as Client Id and Client Secret Key will be shared with you over an email after the approval.

  4. Go through the checksum logic to understand how to generate and validate the checksum.

  5. Get the staging android or iOS Paytm app for integration testing on the merchant staging environment.

Integration steps for Paytm Custom UI SDK

Perform the following steps to integrate the Paytm Custom UI SDK: 

  1. 1
    Add Dependencies for the Paytm Custom UI SDK
    1. Add the below line to ‘repositories’ section of your project-level build.gradle file.
      maven {
          url "https://artifactory.paytm.in/libs-release-local" 
      }
    2. Add below line to ‘dependencies’ section of your app build.gradle.
      implementation "com.paytm.nativesdk:core:1.0.6"

      Note: To help you with the integration, we have provided a sample merchant app integrated with this SDK. To get the sample app, please click here.

  2. 2
    Merchant needs to first initialize SDK in the onCreate of Application class or before calling any method of SDK Method.
     
    Signature:
    PaytmSDK.init(context: Context)

    Method Parameter:

    context: Application Context
  3. 3
    Implement the following methods to extract Paytm user’s saved instruments.
  4. Implement the following methods in case you want to show Paytm user’s saved payment instruments including a wallet. You need to check if the Paytm App is installed on the user’s phone and it supports the feature of getting the authToken for the logged-in Paytm user.
    These methods can be accessed using an instance of PaytmPaymentsUtilRepository. This instance can be obtained as below:

     PaytmPaymentsUtilRepository paymentsUtilRepository = PaytmSDK.getPaymentsUtilRepository()

After having the instance methods in this class you can call the following methods:

  1. You need to call the method isPaytmAppInstalled to check if the Paytm App is installed on the user’s phone.
isPaytmAppInstalled

Method Usage:

paymentsUtilRepository.isPaytmAppInstalled(context)

Method Parameters:

Context context: The current application Context

Response: Boolean

Parameter Description
True In case, Paytm App is installed and supports the feature to extract authcode
False In case, Paytm App is not there or does not support the feature to extract authcode
  1. You need to call the method fetchAuthCode on the background thread in order to get the authcode for the currently logged in user inside Paytm App. For fetching authCode using Paytm SDK, include Paytm's custom checkbox on your UI. The authCode will be fetched only if the user has checked the checkbox.
fetchAuthCode

Use the below line to include the custom checkbox in your xml, you can customize it as a normal checkbox.

<net.one97.paytm.nativesdk.widget.PaytmConsentCheckBox
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 android:text="Allow <Merchant> to fetch Paytm instruments" /> 

Method Usage:

paymentsUtilRepository.fetchAuthCode(context,clientId)

Method Parameters:

Parameter Description

context

Context

The current application Context

clientId

String

The clientId issued from Paytm identifying a merchant

Response:

Parameter Description
String Alphanumeric authCode string e.g. ‘Apfdf-2234-nhdjshj-wers’ in case auth code fetched
Null In case authCode could not be fetched.
  1. You need to call the OAuth token API using the authorization code received to receive the refresh token and SSO token associated with Paytm user.

    Note: SSO token will be used to fetch saved instruments of paytm user and refresh token will be used to get a new SSO token of paytm user after its expiry.

  1. 4
    Implement the interface PaytmSDKCallbackListener
  2. Implement the interface PaytmSDKCallbackListener to get the status of a transaction for different payment instruments. This interface has the following callbacks methods.

    1. onTransactionResponse: This will provide the response status data related to a transaction. The response will contain a JSON string of TxnInfo. Refer the following:
      // get json string of txnInfo
      public void onTransactionResponse(TransactionInfo bundle) {
          if (bundle != null) {
              if (bundle.getTxnInfo() != null) {
                  String s = new Gson().toJson(bundle.getTxnInfo());
                  Toast.makeText(this, s, Toast.LENGTH_LONG).show();
              }
          }
      }            
      Sample TxnInfo data
      {
          "ORDERID": "PARCEL15816826759",
          "MID": "AliSub58582630351896",
          "TXNID": "20200214111212800110168052313701129",
          "TXNAMOUNT": "1.00",
          "PAYMENTMODE": "CC",
          "CURRENCY": "INR",
          "TXNDATE": "2020-02-14 17:48:13.0",
          "STATUS": "TXN_SUCCESS",
          "RESPCODE": "01",
          "RESPMSG": "Txn Success",
          "MERC_UNQ_REF": "test4",
          "UDF_1": "test1",
          "UDF_2": "test2",
          "UDF_3": "test3",
          "ADDITIONAL_INFO": "test5",
          "GATEWAYNAME": "ICICIPAY",
          "BANKTXNID": "68568621250",
          "BANKNAME": "HSBC",
          "PROMO_CAMP_ID": "PROMO CODE",
          "PROMO_RESPCODE": "702",
          "PROMO_STATUS": "FAILURE"
      }
    2. TransactionInfo.ResultInfo: This will contain the status of a transaction, along with retry supported information in case payment can be retried for the same orderId. Status of the transaction can be obtained using ResultInfo.resultStatus contains the transaction status and has only three values: TXN_SUCCESS, TXN_FAILURE and PENDING.
    3. onBackPressedCancelTransaction: This method will be called if a user presses the Back button on any of the screens during the transaction such as the OTP page.
    4. onGenericError (String errorCode, String errorMsg): This method will be called if you report No Network cases or Timeouts.
      Error code Error message
      101 No Internet connection
      103 TIMEOUT
      104 UNKNOWN
  3. 5
    After the user adds the product in the cart and clicks the button to proceed for checkout, your app calls the backend server to get the order payout. Then, your backend server calls Initiate Transaction API from the backend to generate the Transaction Token.

    Note: In case you wish to use the custom Callback URL in Initiate Transaction API then please include the config setMerchantCallbackUrl during Initialization of SDK.

  4. 6
    Using the Transaction token received above, your backend server calls the Fetch Payment Options API to receive the different payment options including the user's saved instruments and other instruments like CC/DC, NB, UPI, EMI etc.

    Note: In case you do not want to create order first, you may call the Fetch Payment Options API before Initiate Transaction. For more details please Get in touch with us.

  5. 7
    Initialization of the SDK


    Initialize the SDK using the parameters mid, orderId, txnToken, and amount. The SDK can be initialized as shown below:

    Signature:

    PaytmSDK.Builder builder = new PaytmSDK.Builder(this, mid, orderId, txnToken, amount, this
    /*PaytmSDKCallbackListener*/);
    
    builder.setMerchantCallbackUrl(Constants.callBackUrl);
    builder.setNativePlusEnabled(isNativePlusEnabled);
    
    PaytmSDK paytmSDK = builder.build();

    Method Parameters:

    Parameter Description

    context

    Context

    Your application context

    mid

    String

    Merchant id identifying a merchant

    orderId

    String

    Unique identifier for current order

    txnToken

    String

    Transaction token to identify the current transaction received in response to Initiate Transaction API from Paytm. Refer to Step 4.
    double amount Order amount for the current transaction

    PaytmSDKCallbackListener

    callback

    Interface implementation to get the result of a payment transaction. Refer to Step 3.

    Note: You can make changes for some of the optional configurations. Please refer to the Optional Configurations.

  1. 8
    Proceed for the Transaction

    When the user clicks on the Pay button after entering the payment instrument’s details in the selected payment method, you need to proceed for the transaction. Please follow the steps below for proceeding with the transaction.
  1. Create a model of PaymentRequestModel type based on the type of payment mode chosen by the user.

Model name : CardRequestModel

Creation of Object:

CardRequestModel cardRequestModel = new CardRequestModel(paymentMode, paymentFlow, 
cardNumber, cardId, cardCvv, cardExpiry, bankCode, channelCode, authMode, emiPlanId, 
shouldSaveCard)

Constructor Parameters:

Parameter Description

paymentMode

String

type of card (DEBIT_CARD, CREDIT_CARD)

paymentFlow

String

current payment flow (NONE, HYBRID, ADDNPAY)

newCardNumber

String

card number digits for a new card (null for the saved card)

savedCardId

String

cardId for a saved card (null for a new card)

cardCvv

String

CVV of the card

cardExpiry

String

card expiry date in the format MM/YY (eg. 11/19)

channelCode

String

channelCode of card obtained from fetchBinDetails API(eg. VISA, MASTER)

bankCode

String

bank code of card obtained from fetchBinDetails API(eg. ICICI, AXIS)

authMode

String

the mode of 2FA chosen for a card(either by 'pin' or 'OTP'), options obtained from fetchBinDetails API

emiPlanId

String

emiPlan id in case of an EMI transaction

shouldSaveCard

Boolean

flag to indicate if the new card should be saved at Paytm’s end
  1. Call paytmSDK.startTransaction to call Process Transaction API. Once you have created the request model for the payment mode selected by the user, call the below method, to start a payment transaction.
      paytmSdk.startTransaction(Activity context, PaymentRequestModel paymentRequestModel)

    Method Params:

    Parameter Description
    Activity context SDK needs the context of activity as it might have to further launch new activities bank OTP pages/ website etc. based on payment mode selected.
    PaymentRequestModel paymentRequestModel The type of paymentRequestModel created for this transaction

    Note: This step is not relevant for UPI intent integration.

  2. Fetch the payment result in PaytmSDKCallbackListenerThe result of the transaction will be received via PaytmSDKCallbackListener Interface described in Step 4.

    Note: This step is not relevant for UPI intent integration.

  3. Clean up SDK instance

    After completing the transaction merchant should call the below method to clear payment SDK state when destroying the PG page.
      paytmSdk.clear()
  1. 9
    Integration of Additional/Optional Methods
    1. Optional Configurations: Please change the following configurations based on your requirements.
      1. setServer (Server server) - Use this to test the APIs on the merchant Integration environment. Default value is Server.PRODUCTION
        PaytmSDK.Builder builder = 
            PaytmSDK.builder(context, mid, orderId, txn, amount, this);    
        if(isStaging) {
            PaytmSDK.setServer(Server.STAGING)
        }
        else{
            PaytmSDK.setServer(Server.PRODUCTION)
        }
        PaytmSDK paytmSdk = builder.build();
      2. setAssistEnabled (boolean enablePaytmAssist) - Use this to enable Paytm Auto Assist feature (Auto reading OTP). The default value is False.

      3. setCustomEndPoint (String URL) - Use this in order to point the SDK APIs to a custom end point. Default production URL is "https://securegw.paytm.in/theia"

      4. setMerchantCallbackUrl (String merchantCallbackUrl) - Use this to define the custom CallbackUrl for receiving the result of the Transaction. By default its value is empty.

      5. setLoggingEnabled (boolean enableLogging) - Use this to enable the logs in case required to debug any issue. By default, its value is set as False.

  1. fetchUpiBalance: To fetch account balance for a UPI account after entering the mpin. This method is required in case the merchant wants to integrate UPI Push flow through the SDK. Paytm App will be launched in this case.
fetchUpiBalance

Model Name: UpiDataRequestModel
 

Creation of Object:

UpiDataRequestModel UpiDataRequestModel = UpiDataRequestModel(vpa, 
bankAccountString, 100)

Constructor Parameters:

Parameter Description

vpa

String

Virtual Payment Adress(eg.xyz@paytm)

bankAccount

String

JSON string representing a bank account for UPI

requestCode

int

The activity requestCode to receive the result of a transaction

Method Parameters:

Parameter Description
Activity context SDK needs the context of activity as it might have to further launch new activities bank OTP pages/ website and/or Paytm App etc. based on payment mode selected.
UpiDataRequestModel upiDataRequestModel UPI request data

Usage:

paytmSDK.fetchUpiBalance(this, upiDataRequestModel)

Response:

Result will be received in onActivityResult as Intent data and can be obtained as shown:
String data = intent.getStringExtra("response"):

{   // value of data
  "statusCode": 100,
  "statusMsg": "SUCCESS",
  "totalBalance": "12345.6"
}
  1. setUpiMpin: This method is used to set MPIN for a UPI account. Paytm app will be launched in this case.
setUpiMpin

Model Name: UpiDataRequestModel

 

Creation of Object:

UpiDataRequestModel UpiDataRequestModel = UpiDataRequestModel(vpa, 
bankAccountString, 101)

Constructor Params:

Parameter Description

vpa

String

Virtual Payment Adress(eg.xyz@paytm)

bankAccount

String

JSON string representing a bank account for UPI

requestCode

int

The activity requestCode to receive a result of the transaction

Method Parameters:

Parameter Description
Activity context SDK needs the context of activity as it might have to further launch new activities bank OTP pages/ website and/or Paytm App etc. based on payment mode selected.

UpiDataRequestModel upiDataRequestModel

UPI request data

Usage:

paytmSDK.setUpiPin(this, upiDataRequestModel) 

Response:

Result will be received in onActivityResult as Intent data and can be obtained as shown :
String data = intent.getStringExtra("response"):

{   // value of data
  "statusCode": 100,
  "statusMsg": "SUCCESS",
}
  1. openPaytmAppForAddMoneyToWallet: This method can be used to invoke and complete the transaction from Paytm App in case wallet balance is insufficient. On calling this method, the transaction shall be completed on Paytm App and you will get the result in onActivityResult of your activity.
openPaytmAppForAddMoneyToWallet
PaytmSDK.getPaymentsHelper().openPaytmAppForAddMoneyToWallet(this, AppConstant.REQUESTCODE_OPEN_PAYTM_ADD_MONEY)

Method Params:

Parameter Description
Activity context SDK needs the context of activity as it might have to further launch new activities bank OTP pages/ website and/or Paytm App etc. based on payment mode selected.

requestCode

int 

Integer request code to receive a result of the transaction in onActivityResult

Notes:

  1. In onActivityResult of your activity, check the result as response = data.getStringExtra("response").
  2. In case Paytm app is not present then the method openPaytmAppForAddMoneyToWallet will open webview for Payment and result will be received via PaytmSDKCallbackListener as done for other paymodes.
  3. This method is available only in the SDK version com.paytm.nativesdk:core-wr:1.0.7.
  1. userHasSavedInstruments: This method is used to check if the user has any saved Payment instruments.
userHasSavedInstruments

Usage:

PaytmPaymentsUtilRepository paymentsUtilRepository =PaytmSDK.getPaymentsUtilRepository()
paymentsUtilRepository.userHasSavedInstruments(context, mid)

Method Parameters:

Parameter Description

context

Context

Context needed to make a query

mid

String

Merchant id needed to fetch saved instruments of user

Response:

This method will return a boolean parameter.

Value Description
True User is logged in and has saved instruments
False Either the user is not logged in or has no saved instruments
  1. getLastNBSavedBank: This method is used to fetch the bank code through which the last successful Netbanking transaction was done.
getLastNBSavedBank

Usage:

PaytmPaymentsUtilRepository paymentsUtilRepository =PaytmSDK.getPaymentsUtilRepository()
paymentsUtilRepository.getLastNBSavedBank()

Response:

This method will return a string parameter.

Value Description
"ICICI" If a user has used ICICI bank in his last net banking transaction
“” Empty if no such bank is saved

Note: This method will return the bank code using which successful transaction using NetBanking was done

  1. getLastSavedVPA: This method is used to fetch the VPA through which the last UPI Collect transaction was done by the user.
getLastSavedVPA

Usage:

PaytmPaymentsUtilRepository paymentsUtilRepository =PaytmSDK.getPaymentsUtilRepository()
paymentsUtilRepository.getLastSavedVPA()

Response:

This method will return a string parameter.

Value Description
"abc@xyz" If a user has used this VPA in his last UPI collect transaction
“” Empty if no such VPA is saved
  1. PaymentMethodDataSource.Callback: Implement this callback, to get the relevant data as per the need. The following methods take this callback to provide the parametrized results as per the method.
i. getNBList

Use this method, to fetch the list of all the net banking supported banks.
 

Method Signature:

fun getNBList(callback: PaymentMethodDataSource.Callback<JSONObject>)

The returned result will be of NBResponse type. The bank's list can be fetched using the PayChannelOptions object that includes the list of banks.


Method Parameters:

Attribute Description
callback Callback to get the response received by the API request invoked by the above method

Usage:

PaytmSDK.getPaymentsHelper()
   getNBList(object:PaymentMethodDataSource.Callback<JSONObject> {
        override fun onResponse(response: JSONObject?,) {
            Toast.makeText(this@BaseInstrumentActivity, getMessage(response),
            Toast.LENGTH_LONG).show()
        }
        override fun onErrorResponse(error: VolleyError?, errorInfo: JSONObject?) {
             Toast.makeText(this@BaseInstrumentActivity, 
                getMessage(errorInfo) ?: "Error fetching NB List", 
                Toast.LENGTH_LONG).show()  
        }
})

The sample response of Fetch NB channel can be found below:

class="language-javascript">{
    "head":{
        "requestId":null,
        "responseTimestamp":"1591622928848",
        "version":"v1"
    },
    "body":{
        "extraParamsMap":null,
        "resultInfo":{
            "resultStatus":"S",
            "resultCode":"0000",
            "resultMsg":"Success"
        },
        "nbPayOption":{
            "displayName":"Net Banking",
            "isDisabled":{
                "status":"false",
                "msg":""
            },
            "payChannelOptions":[
                {
                "isDisabled":{
                    "status":"false",
                    "msg":null
                },
                "hasLowSuccess":{
                    "status":"false",
                    "msg":""
                },
                "iconUrl":"AXIS.png",
                "isHybridDisabled":false,
                "channelCode":"AXIS",
                "channelName":"Axis Bank"
                },
                {
                "isDisabled":{
                    "status":"false",
                    "msg":null
                },
                "hasLowSuccess":{
                    "status":"false",
                    "msg":""
                },
                "iconUrl":"HDFC.png",
                "isHybridDisabled":false,
                "channelCode":"HDFC",
                "channelName":"HDFC Bank"
                }
            ]
        }
    }
}

PayChannelOptions contains the items listed below:

  • String channelName - Bank Name

  • String channelCode - Bank Code

  • String iconUrl - Bank Logo URL

  • HasLowSuccess hasLowSuccess - Information about the bank’s success rate (HasLowSuccess contains Boolean status and String msg )

ii. Fetch Bin

Fetch Bin can be used to get the bin information and success rate of the entered card. It can be used with Transaction token or Access token.

Method Signature:

PaymentsDataImpl.fetchBinDetails(cardSixDigit, 
    token value, token type, mid, reference id, object : 
    PaymentMethodDataSource.Callback {
        override fun onResponse(response: JSONObject?) {
        }
        override fun onErrorResponse(error: VolleyError?, errorInfo: JSONObject?) {
        }
    })


Method Parameters:

Attribute Description
cardSixDigits First six digits of the card
token Token value used(access/txntoken)
tokenType It can be "TXN_TOKEN", "ACCESS"
mid Merchant ID
referenceId Unique ID between 10 to 20 digits and is only required in case of tokenType as ACCESS. It should be similar to the value used in access token generation.

Note: Paytm SDK builder is required to be created first in case using this method with transaction token.

The sample response to Fetch Bin can be found below:

{
    "head":{
        "requestId":null,
        "responseTimestamp":"1591622928848",
        "version":"v1"
    },
    "body":{
        "extraParamsMap":null,
        "resultInfo":{
            "resultStatus":"S",
            "resultCode":"0000",
            "resultMsg":"Success"
        },
        "nbPayOption":{
            "displayName":"Net Banking",
            "isDisabled":{
                "status":"false",
                "msg":""
            },
            "payChannelOptions":[
                {
                "isDisabled":{
                    "status":"false",
                    "msg":null
                },
                "hasLowSuccess":{
                    "status":"false",
                    "msg":""
                },
                "iconUrl":"AXIS.png",
                "isHybridDisabled":false,
                "channelCode":"AXIS",
                "channelName":"Axis Bank"
                },
                {
                "isDisabled":{
                    "status":"false",
                    "msg":null
                },
                "hasLowSuccess":{
                    "status":"false",
                    "msg":""
                },
                "iconUrl":"HDFC.png",
                "isHybridDisabled":false,
                "channelCode":"HDFC",
                "channelName":"HDFC Bank"
                }
            ]
        }
    }
}
  1. 10
    Add the following pro-guard rules:
    - keep class net.one97.paytm.nativesdk.** { *; }
    - keep interface net.one97.paytm.nativesdk.** { *; }