search

Verify Payment Status

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.

 

    REQUEST

Sample Request

curl -X POST 'https://securestage.paytmpayments.com/v3/order/status' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","orderId":"{order-id}"},"head":{"signature":"{signature}"}}'

 

/* 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
PREAUTH, RELEASE, CAPTURE, WITHDRAW

 

 

    RESPONSE

Sample Response

{
    "head": {
        "responseTimestamp": "1553496322922",
        "version": "v1",
        "clientId": "C11",
        "signature": "xxxxx"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "TXN_SUCCESS",
            "resultCode": "01",
            "resultMsg": "Txn Success"
        },
        "txnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "bankTxnId": "xxxxxxxxxxxxxxx",
        "orderId": "xxxxxxx",
        "txnAmount": "100.00",
        "txnType": "SALE",
        "gatewayName": "HDFC",
        "bankName": "HSBC",
        "mid": "xxxxxxxxxxxxxxxxxxxx",
        "paymentMode": "CC",
        "refundAmt": "100.00",
        "txnDate": "2019-02-20 12:35:20.0",
        "authRefId": "50112883"
    }
}        

 

Response Attributes

 

Content Type : JSON

Head

 

Attribute Data Type Description Possible Values
version String Version of the API.
Example: v1
        --
channelId String 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.      

 

                   --

 

 

TXN_SUCCESS, TXN_FAILURE, PENDING, NO_RECORD_FOUND

 

                    --

 

 

                     --

 

 

 

 

txnId

String

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.