Custom UI SDK Integration for Ionic Cordova platform

To merchants who have built their app on an ionic platform, Paytm provides a plugin to conveniently integrate Custom UI SDK for both Android and iOS. On this page, you will see the steps required to integrate Custom UI SDK with an ionic plugin for your app. This plugin helps you to build a seamless and responsive checkout experience for your iOS or Android application.

Pre-requisites

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

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

Note: Save the MID and merchant key generated in the above step.
The additional details such as Client Id and Client Secret Key will be shared with you over an email after the approval.
Go through the checksum logic to understand how to generate and validate the checksum.
Get the staging android or iOS Paytm app for integration testing on the merchant staging environment. For login into the staging Paytm app, use mobile no. 7777777770 and OTP 888888.

Staging Credentials

Login to dashboard.paytm.com with your Paytm account details.
Click on API keys under the Developer settings in the left menu.
Click the Generate now button under the Test API Details.

Note: MID and merchant keys generation may take few minutes. In case you do not see these details, please logout and login after 5 minutes. Proceed now to generate these keys.

Integration on Ionic Cordova for Custom UI SDK

1
Add plugins to your ionic project
- ionic cordova plugin add cordova-paytm-customuisdk
- ionic cordova plugin add cordova-plugin-androidx
- ionic cordova plugin add cordova-plugin-androidx-adapter
Note: Ignore the warning message "Plugin doesn't support this project's cordova-android version. cordova-android: 9.0.0, failed version requirement: <9.0.0", if it comes on adding cordova-plugin-androidx plugin.

Add an ionic wrapper

Note: We are working on ionic-native wrapper for custom ui sdk and you can use the below command to add that.

npm install @ionic-native/custom-uisdk

But for now, use the process below to add ionic wapper:

Take checkout from the below git command out from your ionic project directory (branch customui-sdk)

- git clone -b 'customui-sdk' https://github.com/paytm/ionic-native.git
- cd ionic-native
- npm i
- npm run build

Now go to your ionic project directory and run the below command:

cp -r ../ionic-native/dist/@ionic-native/plugins/custom-uisdk ./node_modules/@ionic-native

Note: Change the path of directories as per your project structure and while running any code for cordova plugin, you have to run above copy(cp) code again.

After adding ionic wapper, add the CustomUISDK to app.module.ts providers as below:

import { CustomUISDK } from "@ionic-native/custom-uisdk/ngx";
@NgModule({
 declarations: [AppComponent],
 entryComponents: [],
 imports: [
   BrowserModule,
   IonicModule.forRoot(),
   AppRoutingModule,
   HttpClientModule,
 ],
 providers: [
   StatusBar,
   SplashScreen,
   CustomUISDK, //here
   { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
 ],
 bootstrap: [AppComponent],
})
export class AppModule {}

3
Implement the following methods to extract Paytm user’s saved instruments.
In case you want to show the Paytm user’s saved payment instruments including the wallet, implement the following methods:

isPaytmAppInstalled: This method is used to check whether Paytm is installed or not.

isPaytmAppInstalled

Method Usage:

this.customUI.isPaytmAppInstalled()

Response: Boolean

Parameter	Description
True	If the Paytm app is installed and supports the feature to extract authcode
False	If the Paytm app is not installed or does not support the feature to extract authcode

fetchAuthCode: If the Paytm app is installed on a user device, you call this method to fetch a temporary authcode from the user. User will be shown a consent checkbox dialog and will only return authcode when the user presses the ok button of dialog.

fetchAuthCode

Method Usage:

this.customUI.fetchAuthCode(this.clientId, this.mid)

Method Parameters:

Attribute	Description	Mandatory
clientId String	Unique Id given by Paytm	Yes
mid String	Unique Identifier given by Paytm	Yes

Attribute

Description

Mandatory

clientId

String

Unique Id given by Paytm

Yes

mid

String

Unique Identifier given by Paytm

Yes

Response:

 {"response" : authCode}

Attribute

Description

authCode

String

Alphanumeric authCode string e.g. ‘Apfdf-2234-nhdjshj-wers’, in case the auth code is fetched

You need to call the OAuth token API using the authorization code received to receive the refresh token and SSO token associated with the 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.

4

After the user adds a product in the cart and clicks to proceed for checkout, your app calls the backend server to get the order payout. Then, your backend server calls Initiate Transaction API from 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.
5

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

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

Call initPaytmSDK method

You need to call the initPaytmSDK method before calling any transaction method in the SDK. After calling the transaction method, response will be in the “then” method in case of success and in “catch” method in case of error. Example for the wallet transaction is given below:

import { CustomUISDK } from "@ionic-native/custom-uisdk/ngx";
export class HomePage implements OnInit {
initPaytmSdk() {
   this.customUI.initPaytmSDK(
     this.mid,
     this.orderId,
     this.txnToken,
     this.amount,
     false,
     null
   );
 } 
goForWalletTransaction() {
    this.customUI.goForWalletTransaction(this.paymentFlow)
     .then((res) => {
       alert(JSON.stringify(res));
 })
     .catch((err) => {
       alert(JSON.stringify(err));
     });
   }
}

Method Parameters:

Parameter	Description	Mandatory
mid (string)	Merchant Id identifying a merchant	Yes
orderId (string)	Unique identifier for current order	Yes
txnToken (string)	Transaction token to identify the current transaction received in response to Initiate Transaction API from Paytm	Yes
amount (string)	Order amount for the current transaction	Yes
isStaging (boolean)	To set the staging environment	Yes
callbackUrl (string)	Defines the custom Callback Url for receiving the result of the transaction	No

7
Proceed for the transaction
When the user clicks 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.

Invoke the goForWalletTransaction method if the user selects Paytm Wallet for proceeding with a transaction.

Method Usage:

this.customUI.goForWalletTransaction(this.paymentFlow)

Method Parameters:

Attribute

Description

Mandatory

paymentFlow

String

Current payment flow (NONE, ADDANDPAY)

Yes

8
Integration of Additional/Optional Methods

appInvoke: This method is called to invoke the Paytm app if installed or redirect flow in case the Paytm app is not installed.

appInvoke

Method Usage:

this.customUI.appInvoke()

setEnvironment: This method is used to change the PG environment from production to staging.

setEnvironment

Method Usage:

this.customUI.setEnvironment(environment)

Method Parameters:

Attribute

Description

Mandatory

environment

String

Current environment (STAGING/PRODUCTION)

Yes

getEnvironment: This method is called to check the current environment.

getEnvironment

Method Usage:

this.customUI.getEnvironment()

getBin: This method is used to get the bin information and success rate of the entered card. It can be used with a Transaction Token or Access Token.

getBin

Note: Call this method after the initPaytmSDK method in case tokenType is TXN_TOKEN.

Method Usage:

this.customUI
     .getBin(this.cardNumber, tokenType, this.txnToken, this.mid, null)

Method Parameters:

Parameter	Description	Mandatory
cardSixDigit String	First six digits of the card	Yes
tokenType String	It can be "TXN_TOKEN","ACCESS"	Yes
token String	Token value used(access/txntoken)	Yes
mid String	Merchant ID	Yes
referenceID String	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.	If token type is ACCESS

Response:

{
    "head": {
        "requestId": "null",
        "responseTimestamp": "1630415256947",
        "version": "v1"
    },
    "body": {
        "authModes": ["otp"],
        "binDetail": {
            "bin": "541919",
            "binTokenization": "false",
            "channelCode": "MASTER",
            "channelName": "MASTER",
            "cnMax": "16",
            "cnMin": "16",
            "cvvL": "3",
            "cvvR": "true",
            "expR": "true",
            "isActive": "true",
            "isIndian": "true",
            "issuingBank": "HDFC Bank",
            "issuingBankCode": "HDFC",
            "paymentMode": "DEBIT_CARD"
        },
        "errorMessage": "EMI not available",
        "hasLowSuccessRate": {
            "msg": "",
            "status": "false"
        },
        "iconUrl": "https://staticgw3.paytm.in/33.1.1/images/wap/merchantLow/master.png",
        "isEmiAvailable": false,
        "isHybridDisabled": false,
        "oneClickMaxAmount": "2000",
        "oneClickSupported": false,
        "prepaidCard": false,
        "prepaidCardMaxAmount": "100000",
        "resultInfo": {
            "resultCode": "0000",
            "resultMsg": "Success",
            "resultStatus": "S"
        }
    }
}

fetchNBList: This method is used to get the list of all netbanking banks along with their success rate. This method can be used with a transaction or access token.

fetchNBList

Note: Call this method after the initPaytmSDK method in case tokenType is TXN_TOKEN.

Method Usage:

this.customUI
     .fetchNBList(tokenType, this.txnToken, this.mid, this.orderId, null)

Method Parameters:

Parameter	Description	Mandatory
orderID String	Unique identifier for current order	If tokenType is TXN_TOKEN
tokenType String	It can be "TXN_TOKEN","ACCESS"	Yes
token String	Token value used(access/txntoken)	Yes
mid String	Merchant ID	Yes
referenceID String	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.	If token type is ACCESS

Response:

{
    "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"
                }
            ]
        }
    }
}

Parameter	Description
channelName	Bank Name
channelCode	Bank Code
iconUrl	Bank Logo URL
hasLowSuccess	Information about bank’s success rate (HasLowSuccess contains Boolean status and String msg )

fetchEmiDetails (For Android Only): This method is used to fetch available EMI plans on a given card.

fetchEmiDetails

Method Usage:

this.customUI
     .fetchEmiDetails(this.cardType, this.channelCode)

Method Parameters:

Parameter

Description

Mandatory

channelCode

String

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

Yes

cardType

String

Type of card (DEBIT_CARD, CREDIT_CARD)

Yes

getLastNBSavedBank: This method is used to fetch the bank code through which the last successful Netbanking transaction was done.

getLastNBSavedBank

Method Usage:

this.customUI
     .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

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

getLastSavedVPA

Method Usage:

this.customUI.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

isAuthCodeValid (For Android Only): This method is used to check if the fetched authcode is valid or not.

isAuthCodeValid

Method Usage:

this.customUI
     .isAuthCodeValid(this.clientId, this.authCode)

Method Parameters:

Parameter

Description

Mandatory

clientId

String

The clientId issued from Paytm identifying a merchant

Yes

authCode

String

Authcode got from fetchAuthCode method

Yes

Response: Boolean

Parameter	Description
True	In case, auth code is valid which was fetched from fetchAuthCode method.
False	In case, auth code is not valid which was fetched from fetchAuthCode method.

checkHasInstrument (For Android Only): This method is called to check if the user has any saved instruments.

checkHasInstrument

Method Usage:

this.customUI
     .checkHasInstrument(this.mid)

Method Parameters:

Parameter

Description

Mandatory

mid

String

Merchant id identifying a merchant

Yes

Response: Boolean

Parameter	Description
True	In case, Paytm app is installed and the merchant has payment instrument
False	In case, Paytm app is not installed or merchant doesn’t have any payment instrument

9
Run Script (iOS Platform)

Add the below script to strip framework architectures at runtime bash.

"${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PaytmNativeSDK.framework/strip-frameworks.sh"

Attribute	Description
appName String	Intent App Name
displayName String	Intent App Display Name
icon String	Intent App icon name
scheme String	Intent App scheme to invoke the app

Parameter	Description	Mandatory
cardNumber String	Card number for a new card	Yes
cardExpiry String	Card expiry date in the format MM/YY (eg. 11/19)	Yes
cardType String	Type of card (DEBIT_CARD, CREDIT_CARD)	Yes
cardCvv String	CVV of the card	Yes
paymentFlow String	Current payment flow (NONE, HYBRID, ADDNPAY)	Yes
authMode String	Mode of 2FA chosen for the card (either by 'pin' or 'OTP'), options obtained from fetchBinDetails API	Yes
channelCode String	Channel code of card obtained from fetchBinDetails API(eg. VISA, MASTER)	Yes
bankCode String	Bank code of card obtained from fetchBinDetails API(eg. ICICI, AXIS)	Yes
issuingBankCode String	Bank code of card obtained from fetchBinDetails API(eg. ICICI, AXIS)	Yes
emiChannelId String	EMI plan Id in case of an EMI transaction	No
saveCard Boolean	Flag to indicate if the new card should be saved at Paytm’s end	Yes

Parameter	Description	Mandatory
cardId String	CardId for a saved card	Yes
cardType String	Type of card (DEBIT_CARD, CREDIT_CARD)	Yes
cardCvv String	CVV of the card	Yes
paymentFlow String	Current payment flow (NONE, HYBRID, ADDNPAY)	Yes
authMode String	Mode of 2FA chosen for the card (either by 'pin' or 'OTP'), options obtained from fetchBinDetails API	Yes
channelCode String	Channel code of card obtained from fetchBinDetails API(eg. VISA, MASTER)	Yes
issuingBankCode String	Bank code of card obtained from fetchBinDetails API(eg. ICICI, AXIS)	Yes
emiChannelId String	EMI Plan id in case of an EMI transaction	No