paytm developer docs logoDeveloperDocumentation
search

Add money to your customer’s Paytm Wallet with Paytm Payment Gateway

Overview of Add Money

If a customer does not have enough balance for an order/ transaction on your website/app, you can trigger the add money request to Paytm so that you can complete the payment for your order. Customer can select a pre-set amount or enter a custom amount to add. After the customer submits the request, you need to do the following:

  1. Create an order in your order system and generate checksumhash at your server end for payment request. Checksumhash is used for detecting errors or tampering introduced during transmission of request. Checksum is generated using Merchant Key which should be kept only on server side for security reasons. You have to send an additional parameter in the add money request:

    REQUEST_TYPE: ADD_MONEY

  2. POST the payload and checksumhash in an HTML. This redirects the customer to Paytm's add money checkout page.

  3. Customer fills payment details and completes the payment authentication. Once the payment is complete, response is posted in HTML form POST on your app/website's callback URL.

  4. Verify checksumhash received in response to ensure that it has not been tampered with.

  5. Customer will now have the money added to her Paytm Wallet and you can continue with checkout.
     

Steps in Add Money via Paytm Payment Gateway

Step 1:

At the click of the Add money button by a customer on your website, create an order in your system and generate the required payload for the payment request. Parameters of a payload are provided below:
 

Request Attributes

PARAMETER DESCRIPTION    

REQUEST_TYPE

String(50)

Mandatory

 This parameter is used to identify the transaction flow. Its value for different flows is mentioned below:
  • 'ADD_MONEY' for the add money request.
    

MID

String(20)

Mandatory

 This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different on staging and production environment. Your staging MID is available here & production MID will be available once your activation is complete.    

ORDER_ID

String(50)

Mandatory

 Unique reference ID for an Order request which is generated by merchant and sent in the transaction request payload. Duplicate order request is rejected by Paytm. It's alphanumeric and special character allowed are “@” “-” “_” “. ” “.”.  

CUST_ID

String(64)

Mandatory

 This parameter is the unique reference ID for every customer and is generated by the merchant. The allowed special characters for this parameter are @, ! ,_ ,$, .    

TXN_AMOUNT

String(10)

Mandatory

 This is the “Transaction Amount” that is to be charged the customer’s credit card /debit card /bank account / Paytm Wallet. Should contain digits up to two decimal points. The only special character allowed is (“.”) . Please ensure that the amount is in the same currency as defined for the Merchant ID being used.    

CHANNEL_ID

String(3)
Mandatory

 Channel through which API call is initiated. For websites, the value to be passed should be "WEB" and for Mobile websites/App, the value to be passed should be "WAP"
This parameter is used to control the theme of the payment page. Based on the channel passed, Paytm will render the layout suitable for that specific platform.		    

INDUSTRY_TYPE_ID

String(20)

Mandatory

 Industry type should pass here. This will be provided by Paytm. Ex: “Retail”    

WEBSITE

String(30)

Mandatory

 WEBSITE Name should be passed here. This will be provided by Paytm    

CHECKSUMHASH

String(108)

Optional

 Signature encryption for validation. It's value to be sent should be the checksum string created by using Paytm checksum library available here. The checksum is used to ensure data is not tempered when a request is posted in APIs. In the case of checksum mismatch due to data tempering Paytm will reject the request.    

SSO_TOKEN

String(36)

Mandatory

 This is a unique token linked with the user's Paytm wallet and is provided in the response while linking user's Paytm wallet.    

CALLBACK_URL

String(255) Mandatory

 On completion of the transaction, Paytm payment gateway will send the response on this URL. This can be a dynamic response URL provided by the merchant. Sample URL to be sent by the merchant is "https://merchant.com/callback/"    

Step 2 :

Generate checksumhash using Paytm library with parameters in key value pairs. Using the payload and checksumhash make an HTML form post and redirect customer to Paytm server. Code snippets and Github links for the checksum utility and HTML form post are provided below.
 

TreeMap<String, String> paytmParams = new TreeMap<String, String>();
paytmParams.put("MID", "YOUR_MID_HERE");
paytmParams.put("REQUEST_TYPE", "ADD_MONEY");
paytmParams.put("WEBSITE", "WEBSTAGING");
paytmParams.put("INDUSTRY_TYPE_ID", "Retail");
paytmParams.put("CHANNEL_ID", "WEB");
paytmParams.put("ORDER_ID", "ORDERID_98765");
paytmParams.put("CUST_ID", "CUST_001");
paytmParams.put("MOBILE_NO", "7777777777");
paytmParams.put("EMAIL", "abc@xyz.com");
paytmParams.put("SSO_TOKEN", "SSO_TOKEN_OF_USER");
paytmParams.put("TXN_AMOUNT", "1.00");
paytmParams.put("CALLBACK_URL", "https://merchant.com/callback");

/*
* Generate checksum for parameters we have
* You can get Checksum JAR from https://paytmpayments.com/docs/checksum/
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys 
*/

String checksum = PaytmChecksum.generateSignature(paytmParams,"YOUR_MERCHANT_KEY");

/* for Staging */
String url = "https://securestage.paytmpayments.com/order/process";

/* for Production */
// String url = "https://secure.paytmpayments.com/order/process";

StringBuilder outputHtml = new StringBuilder();
outputHtml.append("<html>");
outputHtml.append("<head>");
outputHtml.append("<title>Merchant Checkout Page</title>");
outputHtml.append("</head>");
outputHtml.append("<body>");
outputHtml.append("<center><h1>Please do not refresh this page...</h1></center>");
outputHtml.append("<form method='post' action='" + url + "' name='paytm_form'>");
for(Map.Entry<String,String> entry : paytmParams.entrySet()) {
    outputHtml.append("<input type='hidden' name='" + entry.getKey() + "' value='" + entry.getValue() + "'>");
}

outputHtml.append("<input type='hidden' name='CHECKSUMHASH' value='" + checksum + "'>");
outputHtml.append("</form>");
outputHtml.append("<script type='text/javascript'>");
outputHtml.append("document.paytm_form.submit();");
outputHtml.append("</script>");
outputHtml.append("</body>");
outputHtml.append("</html>");
const https = require('https');

/*
* import checksum generation utility
* You can get this utility from https://paytmpayments.com/docs/checksum/
*/

const PaytmChecksum = require('./PaytmChecksum');

https.createServer(function (req, res) {
    var paytmParams = {
    	"MID"              : "YOUR_MID_HERE",
	"REQUEST_TYPE"     : "ADD_MONEY",
	"WEBSITE"          : "WEBSTAGING",
	"INDUSTRY_TYPE_ID" : "Retail",
	"CHANNEL_ID"       : "WEB",
	"ORDER_ID"         : "ORDERID_98765",
	"CUST_ID"          : "CUST_001",
	"MOBILE_NO"        : "7777777777",
	"EMAIL"            : "abc@xyz.com",
	"SSO_TOKEN"        : "SSO_TOKEN_OF_USER",
	"TXN_AMOUNT"       : "1.00",
	"CALLBACK_URL"     : "https://merchant.com/callback",
    };

/*
* Generate checksum for parameters we have
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys 
*/

PaytmChecksum.generateSignature(paytmParams, "YOUR_MERCHANT_KEY").then(function(checksum){

/* for Staging */
var url = "https://securestage.paytmpayments.com/order/process";

/* for Production */
// var url = "https://secure.paytmpayments.com/order/process";

res.writeHead(200, {'Content-Type': 'text/html'});
res.write('<html>');
res.write('<head>');
res.write('<title>Merchant Checkout Page</title>');
res.write('</head>');
res.write('<body>');
res.write('<center><h1>Please do not refresh this page...</h1></center>');
res.write('<form method="post" action="' + url + '" name="paytm_form">');
for(var x in paytmParams){
	res.write('<input type="hidden" name="' + x + '" value="' + paytmParams[x] + '">');
}
res.write('<input type="hidden" name="CHECKSUMHASH" value="' + checksum + '">');
res.write('</form>');
res.write('<script type="text/javascript">');
res.write('document.paytm_form.submit();');
res.write('</script>');
res.write('</body>');
res.write('</html>');
res.end();
});
}).listen(3000);
<?php

/*
* import checksum generation utility
* You can get this utility from https://paytmpayments.com/docs/checksum/
*/

require_once("paytmChecksum.php");

$paytmParams = array(

    "MID"              => "YOUR_MID_HERE",
    "REQUEST_TYPE"     => "ADD_MONEY",
    "WEBSITE"          => "WEBSTAGING",
    "INDUSTRY_TYPE_ID" => "Retail",
    "CHANNEL_ID"       => "WEB",
    "ORDER_ID"         => "ORDERID_98765",
    "CUST_ID"          => "CUST_001",
    "MOBILE_NO"        => "7777777777",
    "EMAIL"            => "abc@xyz.com",
    "SSO_TOKEN"        => "SSO_TOKEN_OF_USER",
    "TXN_AMOUNT"       => "1.00",
    "CALLBACK_URL"     => "https://merchant.com/callback",
);

/*
* Generate checksum for parameters we have
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys 
*/

$checksum = PaytmChecksum::generateSignature($paytmParams, "YOUR_MERCHANT_KEY");

/* for Staging */
$url = "https://securestage.paytmpayments.com/order/process";

/* for Production */
// $url = "https://secure.paytmpayments.com/order/process";
?>
<html>
	<head>
		<title>Merchant Checkout Page</title>
	</head>
	<body>
		<center><h1>Please do not refresh this page...</h1></center>
		<form method='post' action='<?php echo $url; ?>' name='paytm_form'>
				<?php
					foreach($paytmParams as $name => $value) {
						echo '<input type="hidden" name="' . $name .'" value="' . $value . '">';
					}
				?>
				<input type="hidden" name="CHECKSUMHASH" value="<?php echo $checksum ?>">
		</form>
		<script type="text/javascript">
			document.paytm_form.submit();
		</script>
	</body>
</html>
# import checksum generation utility
# You can get this utility from https://paytmpayments.com/docs/checksum/

import PaytmChecksum

paytmParams = {
	"MID"              : "YOUR_MID_HERE",
	"REQUEST_TYPE"     : "ADD_MONEY",
	"WEBSITE"          : "WEBSTAGING",
	"INDUSTRY_TYPE_ID" : "Retail",
	"CHANNEL_ID"       : "WEB",
	"ORDER_ID"         : "ORDERID_98765",
	"CUST_ID"          : "CUST_001",
	"MOBILE_NO"        : "7777777777",
	"EMAIL"            : "abc@xyz.com",
	"SSO_TOKEN"        : "SSO_TOKEN_OF_USER",
	"TXN_AMOUNT"       : "1.00",
	"CALLBACK_URL"     : "https://merchant.com/callback",
}

# Generate checksum for parameters we have
# Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys

checksum = PaytmChecksum.generateSignature(paytmParams, "YOUR_MERCHANT_KEY")

# for Staging
url = "https://securestage.paytmpayments.com/order/process"

# for Production
# url = "https://secure.paytmpayments.com/order/process"

print('<html>')
print('<head>')
print('<title>Merchant Checkout Page</title>')
print('</head>')
print('<body>')
print('<center><h1>Please do not refresh this page...</h1></center>')
print('<form method="post" action="' + url + '" name="paytm_form">')
for name, value in paytmParams.items():
	print('<input type="hidden" name="' + name + '" value="' + value + '">')
print('<input type="hidden" name="CHECKSUMHASH" value="' + checksum + '">')
print('</form>')
print('<script type="text/javascript">')
print('document.paytm_form.submit();')
print('</script>')
print('</body>')
print('</html>')
/* initialize a Dictionary object */
Dictionary<String, String> paytmParams = new Dictionary<String, String>();

/* Find your MID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
paytmParams.Add("MID", "YOUR_MID_HERE");

/* this will be ADD_MONEY */
paytmParams.Add("REQUEST_TYPE", "ADD_MONEY");

/* Find your WEBSITE in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
paytmParams.Add("WEBSITE", "YOUR_WEBSITE_HERE");

/* Find your INDUSTRY_TYPE_ID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
paytmParams.Add("INDUSTRY_TYPE_ID", "YOUR_INDUSTRY_TYPE_ID_HERE");

/* WEB for website and WAP for Mobile-websites or App */
paytmParams.Add("CHANNEL_ID", "YOUR_CHANNEL_ID");

/* Enter your unique order id */
paytmParams.Add("ORDER_ID", "YOUR_ORDER_ID");

/* unique id that belongs to your customer */
paytmParams.Add("CUST_ID", "CUSTOMER_ID");

/* customer's mobile number */
paytmParams.Add("MOBILE_NO", "CUSTOMER_MOBILE_NUMBER");

/* customer's email */
paytmParams.Add("EMAIL", "CUSTOMER_EMAIL");

/* this is an unique token linked to paytm user, provided by paytm */
paytmParams.Add("SSO_TOKEN", "SSO_TOKEN_OF_USER");

/**
* Amount in INR that is needs to be added
* this should be numeric with optionally having two decimal points
*/
paytmParams.Add("TXN_AMOUNT", "ORDER_TRANSACTION_AMOUNT");

/* on completion of transaction, we will send you the response on this URL */
paytmParams.Add("CALLBACK_URL", "YOUR_CALLBACK_URL");

/**
* Generate checksum for parameters we have
* You can get Checksum DLL from https://paytmpayments.com/docs/checksum/
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys 
*/
String checksum = Paytm.CheckSum.generateSignature(paytmParams,"YOUR_MERCHANT_KEY");

/* for Staging */
String url = "https://securestage.paytmpayments.com/order/process";

/* for Production */
// String url = "https://secure.paytmpayments.com/order/process";

/* Prepare HTML Form and Submit to Paytm */
String outputHtml = "";
outputHtml += "<html>";
outputHtml += "<head>";
outputHtml += "<title>Merchant Checkout Page</title>";
outputHtml += "</head>";
outputHtml += "<body>";
outputHtml += "<center><h1>Please do not refresh this page...</h1></center>";
outputHtml += "<form method='post' action='" + url + "' name='paytm_form'>";
foreach (string key in paytmParams.Keys) {
    outputHtml += "<input type='hidden' name='" + key + "' value='" + paytmParams[key] + "'>";
}
outputHtml += "<input type='hidden' name='CHECKSUMHASH' value='" + checksum + "'>";
outputHtml += "</form>";
outputHtml += "<script type='text/javascript'>";
outputHtml += "document.paytm_form.submit();";
outputHtml += "</script>";
outputHtml += "</body>";
outputHtml += "</html>";

Endpoints:
Staging: https://securestage.paytmpayments.com/order/process
Production: https://secure.paytmpayments.com/order/process

HTML Form Post

<html>
    <head>
        <title>Merchant Check Out Page</title>
    </head>
    <body>
        <center><h1>Please do not refresh this page...</h1></center>
        <form method="post" action="https://securestage.paytmpayments.com/order/process?ORDER_ID=YOUR_ORDER_ID" name="paytm">
            <table border="1">
                <tbody>
                    <input type="hidden" name="MID" value="YOUR_MID_HERE">
                    <input type="hidden" name="WEBSITE" value="YOUR_WEBSITE_HERE">
                    <input type="hidden" name="REQUEST_TYPE" value="ADD_MONEY">
                    <input type="hidden" name="SSO_TOKEN" value="SSO_TOKEN_OF_USER">
                    <input type="hidden" name="ORDER_ID" value="YOUR_ORDER_ID">
                    <input type="hidden" name="CUST_ID" value="CUSTOMER_ID">
                    <input type="hidden" name="MOBILE_NO" value="CUSTOMER_MOBILE_NUMBER">
                    <input type="hidden" name="EMAIL" value="CUSTOMER_EMAIL">
                    <input type="hidden" name="INDUSTRY_TYPE_ID" value="YOUR_INDUSTRY_TYPE_ID_HERE">
                    <input type="hidden" name="CHANNEL_ID" value="YOUR_CHANNEL_ID">
                    <input type="hidden" name="TXN_AMOUNT" value="ORDER_TRANSACTION_AMOUNT">
                    <input type="hidden" name="CALLBACK_URL" value="YOUR_CALLBACK_URL">
                    <input type="hidden" name="CHECKSUMHASH" value="GENERATED_CHECKSUM_VALUE">
                </tbody>
            </table>
        <script type="text/javascript">
            document.paytm.submit();
        </script>
        </form>
    </body>
</html>

Step 3:

Customer fills the payment details and is redirected to bank page for authorization. Once the transaction is authorized, Paytm receives the response from the bank and returns a status to your website via your callback URL. Response attributes description and the sample HTML form post is provided below:
 

Response Sent by Paytm

Parameter Description

MID

String(20)

 This is a unique identifier provided to every merchant by Paytm.

TXNID

String (length: up to 64 digits, datatype: long)

 This is a unique Paytm transaction ID corresponding to OrderID for which status is being checked.

ORDERID

String(50)

 Order ID is merchant’s unique reference ID for a transaction 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 the bank to servers.

TXNAMOUNT

String(10)

 Order value of the transaction in INR. A merchant should validate this amount against that send in the transaction request payload. In case the amount does not match, the merchant should not provide the services to the customer. This is needed to avoid request and response tampering possible at the time of transaction.

CURRENCY

String(3)

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

STATUS

String(20)

 This contains the transaction status and has only three values: TXN_SUCCESS, TXN_FAILURE & PENDING.

RESPCODE

String(10)

 Codes refer to a particular reason of payment failure. List in this PDF.

RESPMSG

String(500)

 Description message attached with each RESPCODE. List in this PDF.

TXNDATE

DateTime

 Date of the payment transaction in the format "yyyy-MM-dd HH:mm:ss.S"
Format - "2015-11-02 11:40:46.0"

GATEWAYNAME

String(15)

 Gateway used by Paytm to process the transactions. For Credit, Debit Cards, and 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.
For Net banking & wallet, the value will be Issuing Bank name and Wallet respectively.

BANKNAME

String(500)

 Name of issuing bank of the payment instrument used by the customer. For Credit Cards Debit Cards, Netbanking - Name of the issuing bank.
Example: In case the customer uses SBI's credit card, the value will be "SBI”.
For Paytm Wallet, the value will be Wallet.
In case of UPI, this parameter will not be present in the response.

PAYMENTMODE

String(15)

 The payment mode used by the customer for a transaction:
  • Credit card - CC
  • Debit card - DC
  • Net banking - NB
  • UPI - UPI
  • Paytm wallet - PPI
  • Postpaid - PAYTMCC

CHECKSUMHASH

String(108)

 Signature encryption for validation. It's value to be sent should be the checksum string created by using Paytm checksum library available here. Checksum is used to ensure data is not tempered via verify the checksum method. 
<html>
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
     <title>Paytm Secure Online Payment Gateway</title>
   </head>
   <body>
      <table align='center'>
            <tr>
            <td><STRONG>Transaction is being processed,</STRONG></td>
            </tr>
            <tr>
            <td><font color='blue'>Please wait ...</font></td>
            </tr>
            <tr>
            <td>(Please do not press 'Refresh' or 'Back' button</td>
            </tr>
      </table>
      <FORM NAME='TESTFORM' ACTION='YOUR_CALLBACK_URL' METHOD='POST'>
            <input type='hidden' name='CURRENCY' value='PAYMENT_CURRENCY'>
            <input type='hidden' name='CUST_ID' value='CUSTOMER_ID'>
            <input type='hidden' name='GATEWAYNAME' value='GATEWAY_USED_BY_PAYTM'>
            <input type='hidden' name='RESPMSG' value='PAYTM_RESPONSE_MESSAGE_DESCRIPTION'>
            <input type='hidden' name='BANKNAME' value='BANK_NAME_OF_ISSUING_PAYMENT_MODE'>
            <input type='hidden' name='PAYMENTMODE' value='PAYMENT_MODE_USED_BY_CUSTOMER'>
            <input type='hidden' name='MID' value='YOUR_MID_HERE'>
            <input type='hidden' name='RESPCODE' value='PAYTM_RESPONSE_CODE'>
            <input type='hidden' name='TXNID' value='PAYTM_TRANSACTION_ID'>
            <input type='hidden' name='TXNAMOUNT' value='ORDER_TRANSACTION_AMOUNT'>
            <input type='hidden' name='ORDERID' value='YOUR_ORDER_ID'>
            <input type='hidden' name='STATUS' value='PAYTM_TRANSACTION_STATUS'>
            <input type='hidden' name='BANKTXNID' value='BANK_TRANSACTION_ID'>
            <input type='hidden' name='TXNDATE' value='TRANSACTION_DATE_TIME'>
            <input type='hidden' name='CHECKSUMHASH'  value='PAYTM_GENERATED_CHECKSUM_VALUE'>
      </FORM>
   </body>
 <script type="text/javascript">  document.forms[0].submit();</script>    
</html>

Step 4:

Checksumhash received in response of transaction needs to be verified on merchant server using Paytm library with all the parameters in key-value pairs. Code snippets and Github links for the checksum utility are provided here.
 

Step 5 :

Customer will be able to see the added amount in his/her Wallet.