search

JS Elements

Build a completely native payment experience without haggling with multiple APIs. JS Elements offers pre-built UI blocks (called Elements) that include input boxes and buttons which can be embedded seamlessly on your payment page. These elements can be further customized as per your brand’s theme.

Note: All user sensitive information such as card details, account details, etc. are directly entered on the ‘element’ rendered by the Paytm JS library. Thereby, ensuring that these details are transmitted safely to Paytm and are PCI-DSS compliant.

How is it different from the JS checkout solution?

Unlike JS checkout, with JS Elements you can create an inline payment page without the need to render an iframe on top of your cart page. With our pre-built UI blocks, you can create the payment page exactly as you desire with the utmost ease.

 

You can see the demo below to see JS elements in action.

 

Integration Overview

  1. As the user reaches the cart page, create an order and call Paytm’s Initiate transaction API from your server together with a checksum and fetch a transaction token (txnToken) in response.
    Note: Integrating Initiate Transaction API is mandatory for the merchant to consume this solution.
  2. Use this transaction token alongside the following parameters to initialize the JS library.
    • orderId
    • amount
    • tokenType
    • token 
  3. Use the ‘elements’ method in JS library to create an element instance.
  4. Use the ‘ELEMENT_PAYMODE’ method to render the payment source element (cards, netbanking, UPI, Paytm etc.) on your page. You can view the detailed steps here.
  5. User enters the payment details and authorizes the transaction on the bank’s page.
  6. After receiving the transaction response from the bank, Paytm posts an HTML form on your callback_url provided in the Initiate Transaction API request. Sample HTML form with response attributes and description shown below.
    Response Attributes Description

    MID

    String(20)

    Unique identifier provided by Paytm to every merchant

    TXNID

    String(64)

    Unique transaction ID issued by Paytm for each transaction

    ORDERID

    String(50)

    Unique reference ID generated by merchant for a transaction and sent in the request

    BANKTXNID

    String

    The transaction ID sent by the bank. In case of Paytm proprietary instruments too, there is a unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be a NULL or empty string. The primary reason for this is user dropping out of the payment flow before the transaction reaches to bank servers.

    TXNAMOUNT

    String(10)

    Amount paid by the customer in INR

    CURRENCY

    String(3)

    Currency in which the transaction has taken place. Currently, only "INR" is the supported currency of the transaction.

    STATUS

    String(20)

    Status of the transaction and it has only three values: TXN_SUCCESS, TXN_FAILURE and PENDING

    RESPCODE

    String(10)

    Particular reason of payment failure/success. List in this PDF.

    RESPMSG

    String(500)

    Description message linked with each respcode. List in this PDF.

    TXNDATE

    DateTime

    Date and Time of transaction in the format "yyyy-MM-dd HH:mm:ss.S".

    Example: "2015-11- 02 11:40:46.0".

    GATEWAYNAME

    String(15)

    Gateway used by Paytm to process the transactions. Paymode wise details are provided below: 
    • Credit Card/Debit Card/UPI - Gateway used to process the transaction. For example, if HDFC gateway has been used to process SBI credit card transactions, the value will be HDFC
    • Net banking - Netbanking transactions are not routed via the gateway. Hence, issuing bank name is passed in this field.
    • Paytm Wallet - The value of the GATEWAYNAME will be 'WALLET'
    • Paytm Postpaid - The value of the GATEWAYNAME will be 'PAYTMCC'

    BANKNAME

    String(500)

    Name of issuing bank of the payment instrument used by customer. Paymode wise details are provided below:
    • Credit Card/Debit Cards/Net banking - Name of the issuing bank. Example in case customer uses SBI's credit card, the value will be "SBI"
    • Paytm Wallet - Wallet
    • UPI - This parameter will not be present in the response.

    PAYMENTMODE

    String(15)

    Payment mode used by customer for a transaction:
    • Credit Card - CC
    • Debit Card - DC
    • Net banking - NB
    • UPI - UPI
    • Paytm Wallet - PPI
    • Postpaid - PAYTMCC

    CHECKSUMHASH

    String(108)

    Security parameter to avoid tampering which is verified using the server-side checksum utility provided by Paytm.
  7. Validate the checksum received in the callback_url using the checksum library provided by Paytm. Code snippets and Github links for the checksum library are provided here.
  8. Validate transaction response via a server-side request using the Transaction Status API or by configuring a webhook url. The Transaction Status API requires checksumhash in request and its verification in response (webhook URL response needs checksum validation). The status received via the API or the webhook should be treated as the final transaction status. 
Note: This Transaction Status API/Webhook response is in addition to the response received on callback url . We  strongly  recommended its implementation for security reasons.

Create an Element

Note: Integrating Initiate Transaction API is mandatory for the merchant to consume this solution.
 

Step 1. Load the JS library

<script type="application/javascript" crossorigin="anonymous" src="{HOST}/merchantpgpui/checkoutjs/merchants/{MID}.js"></script>

Where, {HOST} - Server host from where merchant configurations are loaded.

 

Following are the host domains based on the environment:

  • Production - https://securegw.paytm.in
  • Staging - https://securegw-stage.paytm.in

{MID} - Merchant ID (unique identifier assigned to each merchant )

 

Testing MID can be fetched from the API Keys section of the Merchant Dashboard. Production MID is generated by Paytm post successful activation of your account and can be fetched from the same dashboard.

 

Step 2.  Initialise the config options

The config details can be checked from here.

var config = {
 flow:"DEFAULT",
 //Optional to hide paymode label when only one paymode is available
 hidePaymodeLabel: true,
 data:{
   orderId:"orderId",
   amount: 200,
   token:"token",
   tokenType:"TXN_TOKEN"
 },
 style: {
   //Optional: global style that will apply to all paymodes
   bodyColor: "green"
 },
 merchant:{
   mid:"mid"
 },
 handler: {
   notifyMerchant: function(eventType, data) {
       console.log("notify merchant called", eventType, data);
   }
 }
};
*hidePaymodeLabel: An option config to hide paymode label where only one paymode is available. For example: In case of card paymode(element), when there are no saved card available this config can be used to hide "Card/debit card" label.

 

Step 3. Create an Elements instance

var elements = window.Paytm.CheckoutJS.elements(config);

 

Step 4. Render a payment source  instance from the elements instance

List of available payment source to create jsElement are given below:

  • CARD: Used to render the element to make payment with Debit/Credit card
  • NB: Used to render the element to make payment with Net Banking
  • UPI: Used to render the element to make payment with UPI
  • PAY_WITH_PAYTM: Used to render the element to make payment with Paytm Wallet
  • SCAN_AND_PAY: Used to render the element to make payment with QR code scanner
  • EMI: Used to render the element to make payment with EMI
var cardElement = elements.createElement(
 //paymode
 window.Paytm.CheckoutJS.ELEMENT_PAYMODE.CARD,
 //element config
 {
   //Mandatory: selector where you want to render/display it
   root: "#card",
   //Optional: element style
   style: {
     bodyBackgroundColor: "white"     
   }
 }
);

cardElement.invoke();

The createElement instance exposes two methods:

  • invoke: To render the paymode (element)
  • close: To manually close/remove the rendered element

Sample Code Snippet:

<html>
 <head>
   <title>Js Element Demo</title>
 </head>
 <body>
   <!-- Card paymode container -->
   <div id="card"></div>
   <script type="application/javascript" crossorigin="anonymous" src="https://securegw.paytm.in/merchantpgpui/checkoutjs/merchants/dummyExampleMIDIdentifier.js" onload="onScriptLoad();"></script>
   <script>
   function onScriptLoad(){
     
      //Check if CheckoutJS is available
      if(window.Paytm && window.Paytm.CheckoutJS){
     
        //Add callback function to CheckoutJS onLoad function
        window.Paytm.CheckoutJS.onLoad(function       excecuteAfterCompleteLoad() {
          //Config
          var config = {
            flow:"DEFAULT",
            hidePaymodeLabel: true,
            data:{
              orderId:"orderId",
              amount: 200,
              token:"token",
              tokenType:"TXN_TOKEN"
            },
            merchant:{
              mid:"mid"
            },
            handler: {
              notifyMerchant: function(eventType, data) {
                console.log("notify merchant called", eventType, data);
              }
            }
          };

          //Create elements instance
          var elements = window.Paytm.CheckoutJS.elements(config);
          //Create card element
          var cardElement = elements.createElement(window.Paytm.CheckoutJS.ELEMENT_PAYMODE.CARD, {root: "#card", style: {bodyBackgroundColor: "blue"}});
          //Render element
          cardElement.invoke();
        });
      }
    }
   </script>
 </body>
</html>

Testing the JS Elements integration

Once the integration is complete, you may test it using the staging credentials available at the API Keys section of the Merchant Dashboard and using the test paymode credentials listed here.
 
Once the test transaction is complete, move your code to a live environment with production account details. Note that production accounts details are available after you have activated your account on the dashboard.
 
We would also recommend you to read about Refund Management.
 
In case of any issues with integration, please Get in touch.