Refund Status API

Checksum required: YES

Use Case


To fetch the details of refund transaction. The details provided are as follows:

  • Status of refund
  • Destination where refund has been initiated
  • Destination where refund has been initiated
  • Refund reference number with which customer can inquire the refund status with his bank

Request Attributes:

API Content format: JSON

Head

NameDESCRIPTIONMANDATORY
versionString (4) Version of the API. Current version is v1 YES
signatureString (108) Checksum string created by using Paytm checksum logic YES
requestTimestampString (15) EPOCH timestamp of the time request is being sent NO
clientIdString (3) This is used in case of merchant has two different merchant keys. In case one merchant key merchant should pass - C11 YES
channelIdString (3) For websites, the value is WEB For Mobile websites App, the value is WAPNO

Body

NameDESCRIPTIONMANDATORY
midString(20) This is a unique identifier provided to every merchant by Paytm. YES
orderIdString (50)Order ID is merchant’s unique reference ID for a transaction passed in the transaction payload. This is Order ID for which refund status is being inquiredYES
refIdString (50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquiredYES

Response Attributes:

Head

NAMEDescription
versionString (4) Version of the API. Current version is v1
clientIdString (3) This is used in case of merchant has two different merchant keys. In case one merchant key merchant should pass - C11
channelIdString (3)For websites, the value is WEB For Mobile websites/App, the value is WAP
requestTimestampString (15) EPOCH timestamp of the time request is being sent
signature String (108) Checksum string created by using Paytm checksum logic

Body

NAMEDescription
midString (20)This is a unique identifier provided to every merchant by Paytm
txnIdString (64)This is a unique Paytm transaction ID corresponding to REFID for which status is being checked. TXNID is provided in response payload for every transaction
orderIdString (50)Order ID is merchant’s unique reference ID for a transaction passed in the transaction payload
refundIdString (64)This is a unique Paytm refund identifier that is issued by Paytm for each valid refund request
refIdString (50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquired
txnAmount String (10)Order value of the transaction in INR
refundAmount String (10)Amount for which refund is supposed to be made. It can be equal to or lesser than the transaction amount. It should be upto two decimal place. Should not include any separator like (“,”)
totalRefundAmountString (10)Total cumulative refund amount against this transaction. For example for a transaction with order value as INR 100, there has been two refunds of INR 20 & INR 30 historically, then TOTALREFUNDAMT will be INR 50
resultInfoJson Object
acceptRefundStatusStringStatus of Paytm accepting the refund
userCreditInitiateStatusStringStatus of Paytm initiating the refund with the acquirer
merchantRefundRequestTimestampString (30)Timestamp at which merchant requested the refund
acceptRefundTimestampString (30)Timestamp at which Paytm accepted the refund. At the time of acceptance refund amount is deducted from the merchant payable balance
userCreditInitiateTimestampString (30)Timestamp at which Paytm has initiated the refund with the acquirer. Note that this should not be confused with the time customer realizes the money into his account
txnTimestampString (30)Timestamp of payment transaction
refundDetailInfoListJson ObjectDetails of refund like masked refund destination, refund amount allocation, RRN Number etc

Refund Detail Info Json Object

NAMEDESCRIPTION
payMethodString (10)Payment method through which the refund has happened
rrnString (20)Reference number with which customer can inquire status with their respective issuing bank. This is generated by acquiring and passed to the issuing bank. This is not available for all the paymodes
refundAmountString (10)Refund amount in INR
issuingBankNameString (50)Name of issuing bank where refund is being credited
userCreditExpectedDateString (50)Latest date for customer to realize the refund
maskedCardNumberString (25)For credit/debit card refunds, this contains the masked number of the card where refund is being credited to
cardSchemeString (10)For credit/debit card refunds, this contains the card scheme where refund is being credited to
refundType String (10)Type of refund. To_Source: Refund is being credited to the same destination through which the payment took place To_Instant: Refund is being credited to a bank account where refund will be realized instantly by the customer
userMobileNoString (15)User's masked mobile number
maskedVpaString (30)For UPI refunds, this contains the VPA where refund is being credited to
maskedBankAccountNumberString (25)For To_instant refund type, this contains the masked bank account where refund is being credited to

resultInfo Json Object

NAMEDescription
resultStatusenumResult Status of transaction
resultCodestringResult code returned to merchant . Max length of result code can be 64
resultMsgstringResult Message corresponding to transaction

Responses

NAMERESULT STATUS RESULT MESSAGE
10TXN_SUCCESSRefund successful
631TXN_FAILURERecord not found
600TXN_FAILUREInvalid refund request
601PENDINGRefund request was raised for this transaction. But it is pending state.
501TXN_FAILURESystem error
330TXN_FAILUREChecksum provided is invalid
335TXN_FAILUREMid is invalid

Checksum Generation Utility

For Web:

For App:


Endpoints

Staging: https://securegw-stage.paytm.in/refund/api/v1/refundStatus

Production: https://securegw.paytm.in/refund/api/v1/refundStatus

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/refund/api/v1/refundStatus' --header 'Content-Type: application/json' --data '{"body":{"mid":"xxxxxxxxxxxxxxxxxxxx","orderId":"xxxxxxxxxxxxxxxx","refId":"xxxxxxxxxxxxxxxxxxxxxxx"},"head":{"clientId":"C11","version":"v1","signature":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}}'

Old Refund Status API

Checksum required: YES

We do not recommend you to use this API. We will soon deprecate this API

Use Case


  • To fetch status of refund transaction where real time response was not received of refund request
  • To fetch status of refund transaction where refund transaction status was communicated as pending

Request Attributes:

API Content format: JSON

PARAMETERDESCRIPTION
MID String(20) MandatoryThis 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 MIDs is available here & production MID will be available once your activation is complete
ORDERID String(50) MandatoryOrder ID is merchant’s unique reference ID for a transaction passed in the transaction payload. This is Order ID for which refund status is being inquired
REFID String(50) MandatoryMerchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquired
CHECKSUMHASH String(108) MandatorySignature to avoid tampering. Generated using server side checksum utility available here

Response Attributes:

API Content format: JSON

PARAMETERDESCRIPTION
TXNID String(64)This is a unique Paytm transaction ID corresponding to REFID for which status is being checked. TXNID is provided in response payload for every transaction
BANKTXNID String(100)The transaction ID sent by the bank. In case of Paytm proprietary instruments too, there is unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be NULL or empty string. Primary reason for this is user dropping out of the payment flow before the transaction reaches to bank to servers
ORDERID String(50)Order ID is merchant’s unique reference ID for a transaction passed in the transaction payload
TXNAMOUNT String(10)Order value of the transaction in INR
STATUS String(20)This contains the status of refunds. It has following values: TXN_SUCCESS, TXN_FAILURE & PENDING
GATEWAY String(20)Gateway used by Paytm to process the transactions. By payment mode, gateways are provided below
Credit, debit cards 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 - Issuing Bank
Paytm Wallet - Wallet
RESPCODE String(10)Codes refer to a particular reason of refund failure. These are detailed in the list provided below
RESPMSG String(500)Description message attached with each respcode. These are detailed in the list provided below
MID String(20)This is a unique identifier provided to every merchant by Paytm
PAYMENTMODE String(15)The payment mode used by customer for transaction
Credit card – CC
Debit card - DC
Net banking - NB
UPI - UPI
Paytm wallet – PPI
REFUNDAMOUNT String(10)Amount for which refund is supposed to be made. It can be equal to or lesser than the transaction amount. It should be upto two decimal place. Should not include any separator like (“,”)
TOTALREFUNDAMT String(10)Total cummulative refund amount against this transaction. For example for a transaction with order value as INR 100, there has been two refunds of INR 20 & INR 30 historically, then TOTALREFUNDAMT will be INR 50
TXNDATE DateTimeDate of payment transaction in the format "yyyy-MM-dd HH:mm:ss.S"
Format - “2015-11-02 11:40:46.0”
REFUNDDATE DateTimeDate of REFUND in the format "yyyy-MM-dd HH:mm:ss.S"
EX- “2015-11- 02 11:40:46.0”
REFID String(50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquired
REFUNDID String(64)This is a unique Paytm refund identifier that is issued by Paytm for each valid refund request

Refund Status Response Codes, Messages and Status

PARAMETERDESCRIPTIONSTATUS
10Refund successfulTXN_SUCCESS
311Invalid refund requestTXN_FAILURE
328Currency not sameTXN_FAILURE
501System errorTXN_FAILURE
600Invalid refund requestTXN_FAILURE
601Refund request was raised for this transaction but it is pending statePENDING
602Bank has declined refund requestTXN_FAILURE
604We are experiencing delays from the bankPENDING
606Checksum generated by paytm payment gateway does not match checksum expected by bankTXN_FAILURE
607Order not exist for current requestTXN_FAILURE
609Refund initiated for a rejected transactionTXN_FAILURE
610Transaction fully refunded alreadyTXN_FAILURE
612This is a valid authorized transactionTXN_FAILURE
617Refund already raisedTXN_FAILURE
619Invalid refund amountTXN_FAILURE
620Refund failedTXN_FAILURE
622No_token-transcation_limitedTXN_FAILURE
623Refund is already Success or in Pending state.Please check status query for final resultTXN_FAILURE
640Order is frozenTXN_FAILURE
700Invalid consult requestTXN_FAILURE
701Refund already raised with same refIDTXN_FAILURE
331Record not foundTXN_FAILURE
Request CodeResponse JSON
curl -X POST
https://securegw-stage.paytm.in/refund/status -H
'JsonData={"MID":"rxazcv89315285244163",
"ORDERID":"order1","REFID":"reforder1",
"CHECKSUMHASH":"b%2BhFyBK9XUc8Sa%2BVzv7QFNoOQp%2FepntTjl15SQ%2FssJnJGbDfLAY9RIbLsYM9D5c3P0c44vQeB5b1A3qoGDStO6QjfdwpwxafS4wm8%2B%2B8S6k%3D"}'