Check Payment Status API

Used to check the status of the payment request. Status against a particular MerchantId:TransactionId can be fetched using the transaction status API. Please refer below section for details.

It is mandatory for the merchant to check the status of a transaction.

  • The cashier should select the “check the transaction status” button which should call the terminal’s server. Terminal’s server should call PhonePe server with this API to know the status.
  • Add a message in the POS asking the cashier to click the Check Status button only after customer tells the cashier that he has made the payment.
  • The payment status can be Success, Failed or Pending.
  • When Pending, There should be a message POS “Payment is in progress, please check the status after sometime.” (ideally, Collect expiry time – current time taken). “
  • For eg. let’s assume the expiry time passed in collect request is 180 sec. Status is checked after 60 sec and payment is in pending state, the time to wait will 120 sec maximum since payment will be closed within 180 sec.

**Base Url**:**Payment-Status-Check Endpoint**:

PROD

Base Url: https://mercury-t2.phonepe.com

Payment-Status-Check Endpoint: https://mercury-t2.phonepe.com/v3/transaction/{merchantId}/{transactionId}/status

<html-block html=”

Request Headers

“>

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(“/v3/transaction/{merchantId}/{transactionId}/status” +
saltKey) + “###” + saltIndex

<html-block html=”

Path Parameters

“>

Parameter NameTypeDescriptionMandatory
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePeYes
transactionIdSTRINGMerchant transactionID for which status is to be fetchedYes

<html-block html=”

Response Parameters

“>

Parameter NameTypeDescription
successBOOLEANA boolean to indicate the success/failure of the request.
codeENUMPlease see the list of Transaction Status Response Codes below. You should base your decision on this parameter.
messageSTRINGShort message about status of transaction
transactionId
STRINGUnique Transaction ID generated by the merchant to track this request to PhonePe
merchantIdSTRINGUnique Merchant ID assigned to the merchant by PhonePe
amountLONGTransaction amount in paise
providerReferenceIdSTRINGPhonePe transaction Id
paymentStateENUMTransaction Status, Refer below section for list of states
payResponseCodeSTRINGPhonePe internal status code. Please note this is a string value and new codes are likely to be added in the future. (Please don’t do the marshalling/unmarshalling into an enum for this at your side). This is an informative value.

<html-block html=”

Transaction Status Response Codes

“>

CodeDescription
TRANSACTION_NOT_FOUNDPayment not initiated inside PhonePe
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect
INTERNAL_SERVER_ERRORSomething went wrong
PAYMENT_SUCCESSPayment is successful
PAYMENT_ERRORPayment failed
PAYMENT_PENDINGPayment is pending. It does not indicate failed payment.
PAYMENT_CANCELLEDPayment cancelled by merchant
PAYMENT_DECLINEDPayment declined by user
{
    "success": true,
    "code": "PAYMENT_SUCCESS",
    "message": "Your payment is successful.",
    "data": {
        "merchantId": "MERCHANTUAT",
        "transactionId": "TEST20231004021527",
        "providerReferenceId": "C2310111154080381214775",
        "amount": 100,
        "paymentState": "COMPLETED",
        "payResponseCode": "SUCCESS",
        "paymentModes": [
            {
                "mode": "ACCOUNT",
                "transactionState": "COMPLETED",
                "transactionResponseCode": "00",
                "flags": 0,
                "amount": 100,
                "actualAmount": 100,
                "instrumentId": "IN2308301622030151690900",
                "type": "ACCOUNT",
                "accountId": "AC188429164440737231111",
                "accountNumber": "******8185",
                "accountHolderName": "Test_User",
                "ifsc": "TEST0009107",
                "utr": "231011115408",
                "upiTransactionId": "U2310111154256871214022",
                "vpa": "test123@ibl",
                "accountAuthMode": "UPI",
                "accountType": "SAVINGS"
            }
        ],
        "transactionContext": {
            "qrCodeId": null,
            "posDeviceId": null,
            "storeId": "store1",
            "terminalId": "terminal1"
        }
    }
}
{
    "success": false,
    "code": "PAYMENT_ERROR",
    "message": "Payment Failed",
    "data": {
        "merchantId": "MERCHANTUAT",
        "transactionId": "TEST20231004021526",
        "providerReferenceId": "T2310111143595731214112",
        "amount": 100,
        "merchantOrderId": "808090133",
        "paymentState": "FAILED",
        "payResponseCode": "UPI_BACKBONE_ERROR"
    }
}

Cross-check the amount which has been passed in forward payment path(Accept payment API) and in the response of Check Transaction Status API.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.IO;
using System.Net;
using System.Text;
using System.Security.Cryptography;
using Newtonsoft.Json;

namespace Rextester
{
    public class Program
    {
        private const string PHONEPE_STAGE_BASE_URL = "https://mercury-uat.phonepe.com/enterprise-sandbox";
        private string merchantKey = "8289e078-be0b-484d-ae60-052f117f8deb";
        private const string merchantId = "M2306160483220675579140";
        private string transactionId = "mer_order_8";
       
        public bool SendCheckPaymentStatusRequest()
        {
            string headerString = String.Format("/v3/transaction/{0}/{1}/status{2}", merchantId, transactionId, merchantKey);
            Console.WriteLine("headerString: " + headerString);
            string checksum = GenerateSha256ChecksumFromBase64Json("", headerString);
            checksum = checksum + "###1";
            Console.WriteLine(checksum);

            bool result = CallPhonePeStatusApi(checksum);

            return result;
        }
        
        private bool CallPhonePeStatusApi(String xVerify)
        {
            Console.WriteLine("CallPhonePeStatusApi()");
            string txnURL = PHONEPE_STAGE_BASE_URL;
            String urlSuffix = String.Format("/v3/transaction/{0}/{1}/status", merchantId, transactionId);
            txnURL = txnURL + urlSuffix;

            Console.WriteLine("Url: " + txnURL);
            
            try
            {
                HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create(txnURL);

                webRequest.Method = "GET";
                webRequest.ContentType = "application/json";
                webRequest.Headers.Add("x-verify", xVerify);

                string responseData = string.Empty;
                
                using (StreamReader responseReader = new StreamReader(webRequest.GetResponse().GetResponseStream()))
                {
                    responseData = responseReader.ReadToEnd();
                    if (responseData.Length > 0)
                    {
                        PhonePeStatusResponseBody responseBody = JsonConvert.DeserializeObject<PhonePeStatusResponseBody>(responseData);
                        Console.WriteLine(responseData);
                        Console.WriteLine(responseBody.message);
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
                return false;
            }
            return false;
        }
        
        		
// calculate SHA256
private string GenerateSha256ChecksumFromBase64Json(string base64JsonString, string jsonSuffixString)
        {
            string checksum = null;
            SHA256 sha256 = SHA256.Create();
            string checksumString = base64JsonString + jsonSuffixString;
            byte[] checksumBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(checksumString));
            checksum = BitConverter.ToString(checksumBytes).Replace("-", string.Empty);
            return checksum;
        }

        public static void Main(string[] args){
            Program obj = new Program();
            bool statusResponse = obj.SendCheckPaymentStatusRequest();
            Console.WriteLine("Payment status check");
        }
    }

   public class PhonePeStatusResponseBody
    {
        public bool success;
        public string code;
        public string message;
        public Data data;
    }
    public class Data
    {
        public string transactionId;
        public int amount;
        public string merchantId;
        public string providerReferenceId;
    }

}

from django.shortcuts import render
from django.http import HttpResponse
import requests
import base64
import hashlib
from rest_framework.decorators import api_view
import json
from django.http import JsonResponse
import qrcode
import os

txnid = "TEST20231004021525T"
baseUrl = 'https://mercury-uat.phonepe.com/enterprise-sandbox'
MID = 'MERCHANTUAT'
saltkey = 'f1fed176-917c-4c1b-b5ae-1e1d39e1f8d5'
keyindex = '1'

def checkstatus(request):
    merchantId = MID
    transactionId = txnid
    # transactionId = 'ref_' + txnid
    url = baseUrl + '/v3/transaction/' + merchantId + '/' + transactionId + '/status'
    # for Sha256 calculation
    api_saltkey = saltkey
    str_forSha256 = '/v3/transaction/' + merchantId + '/' + transactionId + '/status' + api_saltkey
    print(str_forSha256)
    print(url)
    sha_value = hashlib.sha256(str_forSha256.encode('UTF-8')).hexdigest()
    x_verify = sha_value + '###' + keyindex

    headers = {
        "Content-Type": "application/json",
        #"x-provider-id": "IMPRESSIONPOS",
        "X-VERIFY": x_verify
    }
    print(x_verify)
    res = requests.get(url=url, headers=headers)
    return HttpResponse(res)
{“method”:”get”,”url”:”/v3/transaction/{merchantId}/{transactionId}/status”,”auth”:”required”,”results”:{“codes”:[{“name”:””,”code”:”{\n \”success\”: true,\n \”code\”: \”PAYMENT_SUCCESS\”,\n \”message\”: \”Your payment is successful.\”,\n \”data\”: {\n \”transactionId\”: \”TX123456789\”,\n \”merchantId\”: \”U123456789\”,\n \”amount\”: 100,\n \”providerReferenceId\”: \”PPXXXXXX\”,\n \”paymentState\”: \”COMPLETED\”,\n \”payResponseCode\”: \”SUCCESS\”\n }\n }”,”language”:”json”,”status”:200},{“name”:””,”code”:”{}”,”language”:”json”,”status”:400}]},”params”:[{“name”:”Content-Type”,”type”:”string”,”enumValues”:””,”default”:””,”desc”:””,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310b4db86a6e002d1c80cd”},{“name”:”X-VERIFY”,”type”:”string”,”enumValues”:””,”default”:”90443659f151a86831b7502c797c2ee4f3bcf63cbdad141c154effc2aad5c762###1″,”desc”:”SHA256(\”/v3/transaction/{merchantId}/{transactionId}/status\” + saltKey) + \”###\” + saltIndex”,”required”:true,”in”:”header”,”ref”:””,”_id”:”5f310b4db86a6e002d1c80cc”},{“name”:”merchantId”,”type”:”string”,”enumValues”:””,”default”:”MERCHANTUAT”,”desc”:”Unique Merchant ID assigned to the merchant by PhonePe”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5f310b4db86a6e002d1c80cb”},{“name”:”transactionId”,”type”:”string”,”enumValues”:””,”default”:”TX123456789″,”desc”:”Merchant transaction id for which status is to be fetched”,”required”:false,”in”:”path”,”ref”:””,”_id”:”5f310b4db86a6e002d1c80ca”}],”examples”:{“codes”:[]},”apiSetting”:”64c244096688b200429110a5″}
https://mercury-uat.phonepe.com/enterprise-sandbox