This step involves one validation (Receive & Validate Callback Response) and one API integration (Transaction Status API).
To update the transaction status, Paytm PG uses Callback URL as a default option to send the response of the transaction. However, it is highly recommended to integrate Transaction Status API or Webhook and fetch the final payment status before confirming your customer’s order.
Receive & Validate Callback Response
When the payment is successful, you receive the transaction status from Paytm PG on the Callback URL.
TIP
You can manage callback in the same page instead of redirecting to another page by passing parameter, redirect=false in JS Checkout config. Consequently, you get the payment response inside transactionStatus handler in JS Checkout. This is where you can manage the callback.
The signature in this response needs to be validated via Checksum library. The implementation is similar to the Initiate Payment step.
CAUTION
Failure to validate the checksum may result in fraudulent transactions.
POST Transaction Status API
This API is used to verify transaction status before confirming customer’s order.
Paytm PG strongly recommends the merchants to integrate this Transaction Status API that can be used to fetch the final transaction status corresponding to requested OrderId. Following are the transaction statuses:
Success
Failed
Pending
This API gets the transaction status corresponding to requested OrderId for specific merchant.
/* initialize an object */
JSONObject paytmParams = new JSONObject();
/* body parameters */
JSONObject body = new JSONObject();
/* Find your MID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
body.put("mid", "YOUR_MID_HERE");
/* Enter your order id which needs to be check status for */
body.put("orderId", "YOUR_ORDER_ID");
/**
* Generate checksum by parameters we have in body
* 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(body.toString(), "YOUR_MERCHANT_KEY");
/* head parameters */
JSONObject head = new JSONObject();
/* put generated checksum value here */
head.put("signature", checksum);
/* prepare JSON string for request */
paytmParams.put("body", body);
paytmParams.put("head", head);
String post_data = paytmParams.toString();
/* for Staging */
URL url = new URL("https://securestage.paytmpayments.com/v3/order/status");
/* for Production */
// URL url = new URL("https://secure.paytmpayments.com/v3/order/status");
try {
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
DataOutputStream requestWriter = new DataOutputStream(connection.getOutputStream());
requestWriter.writeBytes(post_data);
requestWriter.close();
String responseData = "";
InputStream is = connection.getInputStream();
BufferedReader responseReader = new BufferedReader(new InputStreamReader(is));
if ((responseData = responseReader.readLine()) != null) {
System.out.append("Response: " + responseData);
}
// System.out.append("Request: " + post_data);
responseReader.close();
} catch (Exception exception) {
exception.printStackTrace();
}
const https = require('https');
/**
* import checksum generation utility
* You can get this utility from https://paytmpayments.com/docs/checksum/
*/
const PaytmChecksum = require('./PaytmChecksum');
/* initialize an object */
var paytmParams = {};
/* body parameters */
paytmParams.body = {
/* Find your MID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
"mid" : "YOUR_MID_HERE",
/* Enter your order id which needs to be check status for */
"orderId" : "YOUR_ORDER_ID",
};
/**
* Generate checksum by parameters we have in body
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys
*/
PaytmChecksum.generateSignature(JSON.stringify(paytmParams.body), "YOUR_MERCHANT_KEY").then(function(checksum){
/* head parameters */
paytmParams.head = {
/* put generated checksum value here */
"signature" : checksum
};
/* prepare JSON string for request */
var post_data = JSON.stringify(paytmParams);
var options = {
/* for Staging */
hostname: 'securestage.paytmpayments.com',
/* for Production */
// hostname: 'secure.paytmpayments.com',
port: 443,
path: '/v3/order/status',
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Content-Length': post_data.length
}
};
// Set up the request
var response = "";
var post_req = https.request(options, function(post_res) {
post_res.on('data', function (chunk) {
response += chunk;
});
post_res.on('end', function(){
console.log('Response: ', response);
});
});
// post the data
post_req.write(post_data);
post_req.end();
});
<?php
/**
* import checksum generation utility
* You can get this utility from https://paytmpayments.com/docs/checksum/
*/
require_once("PaytmChecksum.php");
/* initialize an array */
$paytmParams = array();
/* body parameters */
$paytmParams["body"] = array(
/* Find your MID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys */
"mid" => "YOUR_MID_HERE",
/* Enter your order id which needs to be check status for */
"orderId" => "YOUR_ORDER_ID",
);
/**
* Generate checksum by parameters we have in body
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys
*/
$checksum = PaytmChecksum::generateSignature(json_encode($paytmParams["body"], JSON_UNESCAPED_SLASHES), "YOUR_MERCHANT_KEY");
/* head parameters */
$paytmParams["head"] = array(
/* put generated checksum value here */
"signature" => $checksum
);
/* prepare JSON string for request */
$post_data = json_encode($paytmParams, JSON_UNESCAPED_SLASHES);
/* for Staging */
$url = "https://securestage.paytmpayments.com/v3/order/status";
/* for Production */
// $url = "https://secure.paytmpayments.com/v3/order/status";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$response = curl_exec($ch);
import requests
import json
# import checksum generation utility
# You can get this utility from https://paytmpayments.com/docs/checksum/
import PaytmChecksum
# initialize a dictionary
paytmParams = dict()
# body parameters
paytmParams["body"] = {
# Find your MID in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys
"mid" : "YOUR_MID_HERE",
# Enter your order id which needs to be check status for
"orderId" : "YOUR_ORDER_ID",
}
# Generate checksum by parameters we have in body
# Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys
checksum = PaytmChecksum.generateSignature(json.dumps(paytmParams["body"]), "YOUR_MERCHANT_KEY")
# head parameters
paytmParams["head"] = {
# put generated checksum value here
"signature" : checksum
}
# prepare JSON string for request
post_data = json.dumps(paytmParams)
# for Staging
url = "https://securestage.paytmpayments.com/v3/order/status"
# for Production
# url = "https://secure.paytmpayments.com/v3/order/status"
response = requests.post(url, data = post_data, headers = {"Content-type": "application/json"}).json()
Dictionary<string, string> body = new Dictionary<string, string>();
Dictionary<string, string> head = new Dictionary<string, string>();
Dictionary<string, Dictionary<string, string>> requestBody = new Dictionary<string, Dictionary<string, string>>();
body.Add("mid", "YOUR_MID_HERE");
body.Add("orderId", "ORDERID_98765");
/*
* Generate checksum by parameters we have in body
* Find your Merchant Key in your Paytm Dashboard at https://dashboard.paytmpayments.com/next/apikeys
*/
string paytmChecksum = Checksum.generateSignature(JsonConvert.SerializeObject(body), "YOUR_KEY_HERE");
head.Add("signature", paytmChecksum);
requestBody.Add("body", body);
requestBody.Add("head", head);
string post_data = JsonConvert.SerializeObject(requestBody);
//For Staging
string url = "https://securestage.paytmpayments.com/v3/order/status";
//For Production
//string url = "https://secure.paytmpayments.com/v3/order/status";
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create(url);
webRequest.Method = "POST";
webRequest.ContentType = "application/json";
webRequest.ContentLength = post_data.Length;
using (StreamWriter requestWriter = new StreamWriter(webRequest.GetRequestStream()))
{
requestWriter.Write(post_data);
}
string responseData = string.Empty;
using (StreamReader responseReader = new StreamReader(webRequest.GetResponse().GetResponseStream()))
{
responseData = responseReader.ReadToEnd();
Console.WriteLine(responseData);
}
Request Attributes
Content Type : JSON
Head
Attribute
Data Type
Mandatory / Optional
Description
Possible Values
version
String
Optional
Version of the API. Example: v1
--
channelId
String
Optional
The parameter value identifies the Channel for which the API call is initiated.
WEB, WAP
requestTimestamp
String
Optional
EPOCH timestamp of the time at which request is being sent. Example: 1588402269
--
clientId
String
Optional
Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key. Example: C11
--
signature
String
Mandatory
Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.
--
Body
Attribute
Data Type
Mandatory / Optional
Description
Possible Values
mid
String
Mandatory
Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation. Example: INTEGR7769XXXXXX9383
--
orderId
String
Mandatory
The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”. Example: OREDRID_98765
--
txnType
String
Optional
Transaction type of the payment
The parameter that would define which status will be presented in the response.
If value = PREAUTH the status and amount in response would be that of pre-auth
If value = CAPTURE the status and amount in response would be that of capture
If value = RELEASE the status and amount in response would be that of release
If value is blank then order amount and status will be provided in response
Parameter value identifies the Channel for which the API call is initiated.
WEB, WAP
requestTimestamp
String
EPOCH timestamp of the time at which request is being sent. Example: 1588402269
--
clientId
String
Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key. Example: C11
--
signature
String
Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.
--
Body
Attribute
Data Type
Description
Possible Values
resultInfo
resultCode
resultStatus
resultMsg
Object
String
String
String
This parameter gives the information about the result of the API response.
This is the resultCode corresponding to a particular message and is returned to the merchant. Its maximum length is 64. The different result codes corresponding to this API are mentioned below.
This parameter is the result specific to the phase of the transaction mentioned in the txnType field
This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
Transaction Id of the payment Example: 202005081112128XXXXXX68470101509706
--
bankTxnId
String
Bank transaction Id from the bank Example: 77700XXXX215242
--
orderId
String
Unique reference ID for an Order request generated by merchant for payment. Example: OREDRID_98765
--
txnAmount
String
Payment transaction amount
1.00
txnType
String
Transaction type of the payment
--
gatewayName
String
Name of the gateway used to process the transaction. In case of Super Router, this is the payment aggregator chosen to process the transaction.
bankName
String
Bank Name used in payment
Example: Paytm Payments Bank, ICICI Bank
mid
String
Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation. Example: INTEGR7769XXXXXX9383
--
paymentMode
String
Payment Mode used in payment.
PPI , UPI , CC , DC , NB
refundAmt
String
Refund amount of the payment
Example: 1.00
--
txnDate
String
Date on which the pre-auth/capture/release/order was created (depending on the value of txnType)
Example: 2020-05-05 14:00:28
--
authRefId
String
Authentication ID for the 2FA transaction generated as received from the acquirer. Condition: Mandatory for RupayCards.
merchantUniqueReference
String
Merchant's reference text which is sent in the order's request.
--
Response Codes & Messages
Please refer to the Transaction Status Codes to learn more about the Transaction Statuses and their codes.
Configure Webhook
Instead of using the Transaction Status API, alternatively you can configure Webhook to get the final transaction status. You can configure the webhook for Payment Status in most of the usecases from the merchant dashboard.
NOTE
Webhooks are the user specified HTTP callbacks that get triggered by some event and are used to connect two applications. It is a way Paytm PG server to send notification on the final status of transaction, refund, etc. to a publicly accessible web URL of the merchant. Unlike the Transaction Status API where you need to poll the data frequently to get the real time status, Webhook sends you the transaction status in real time and automated manner.
To consume a webhook, you must configure a publicly accessible web URL from your Paytm dashboard. This URL should be capable of handling the updated event/response sent by Paytm PG.
Paytm sends a server to server (S2S) response in key value pairs on the webhook configured and on callback URL. Payment Success Webhook response is sent for the final transaction status i.e. success or failed.
To know more about the webhook response, please refer to the Payment Status.