• Getting Started
    • Website Integration
      Mobile Integration (Android/IOS)
      Enterprise Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Webhooks
      Testing
      Refunds
      Guides
      Other Processes

      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
      • Refund reference number with which customer can inquire the refund status with his bank

      Request Attributes

      API Content format: JSON

      Head

      ATTRIBUTEDESCRIPTIONMANDATORY
      versionString (4) Version of the API. Current version is v1 No
      signatureString (108) Checksum string created by using Paytm checksum logic Yes
      requestTimestampString (15) EPOCH timestamp of the time at which 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 No
      channelIdString (3) Channel through which call initiated.
      WEB: Web server, WAP: Mobile device.
      No

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      midString(20) 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.Yes
      orderIdString (50)OrderId as provided by merchant during payment transaction against which refund is being raised.Yes
      refIdString (50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquiredYes

      Response Attributes

      Head

      ATTRIBUTEDescription
      versionString (4) Version of the API passed in the request.
      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)Channel through which call initiated.
      WEB: Web server, WAP: Mobile device.
      responseTimestampString (15) EPOCH timestamp of the time at which response is being sent.
      signature String (108) Checksum string created by using Paytm checksum logic

      Body

      ATTRIBUTEDescription
      midString (20)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.
      txnIdString (64)TXNID is Paytm payment Transaction Id against which the refund transaction is being placed.
      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)Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.
      txnAmount String (10)Order value of the transaction in INR
      refundAmount String (10)Amount for which refund is to be made. It can be equal to or less than the transaction amount and should be upto two decimal places. Only special character allowed is (".")
      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
      resultInfoResultInforesultInfo Object
      acceptRefundStatusStringStatus of Paytm accepting the refund
      userCreditInitiateStatusStringStatus of Paytm initiating the refund with the acquirer
      merchantRefundRequestTimestampString (30)EPOCH timestamp of the time at which request is being sent.
      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
      refundDetailInfoListRefundDetailInfoListDetails of refund like masked refund destination, refund amount allocation, RRN Number etc

      RefundDetailInfoList

      ATTRIBUTEDESCRIPTION
      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

      ATTRIBUTEDescription
      resultCodeStringResult code returned to merchant. Max length of result code can be 64
      resultStatusenumResult Status of transaction
      (TXN_SUCCESS, PENDING, TXN_FAILURE)
      resultMsgstringResult Message corresponding to transaction

      Response Codes & Messages

      resultCoderesultStatusresultMsg
      10TXN_SUCCESSRefund successful
      501PENDINGSystem error
      601PENDINGRefund request was raised for this transaction. But it is pending state.
      330TXN_FAILUREChecksum provided is invalid
      335TXN_FAILUREMid is invalid
      600TXN_FAILUREInvalid refund request
      620TXN_FAILURERefund Failed
      631TXN_FAILURERecord not found

      Endpoints

      Staging: https://securegw-stage.paytm.in/v2/refund/status

      Production: https://securegw.paytm.in/v2/refund/status

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/v2/refund/status' --header 'Content-Type: application/json' --data '{"body":{"mid":"{mid}","orderId":"{order-id}","refId":"{unique-refund-id}"},"head":{"clientId":"{client-id}","signature":"{signature}"}}'
                  

      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

      ATTRIBUTEDESCRIPTIONMANDATORY
      MID String(20)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 completeYes
      ORDERID String(50)OrderId as provided by merchant during payment transaction against which refund is being raised.Yes
      REFID String(50)Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.Yes
      CHECKSUMHASH String(108)Signature to avoid tampering. Generated using server side checksum utility available hereYes

      Response Attributes

      ATTRIBUTEDESCRIPTION
      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 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
      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)Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.
      REFUNDID String(64)This is a unique Paytm refund identifier that is issued by Paytm for each valid refund request

      Response Codes and Messages

      RESPCODESTATUSRESPMSG
      10TXN_SUCCESSRefund successful
      501PENDINGSystem error
      601PENDINGRefund request was raised for this transaction but it is pending state
      604PENDINGWe are experiencing delays from the bank
      311TXN_FAILUREInvalid refund request
      328TXN_FAILURECurrency not same
      331TXN_FAILURERecord not found
      600TXN_FAILUREInvalid refund request
      602TXN_FAILUREBank has declined refund request
      606TXN_FAILUREChecksum generated by paytm payment gateway does not match checksum expected by bank
      607TXN_FAILUREOrder not exist for current request
      609TXN_FAILURERefund initiated for a rejected transaction
      610TXN_FAILURETransaction fully refunded already
      612TXN_FAILUREThis is a valid authorized transaction
      617TXN_FAILURERefund already raised
      619TXN_FAILUREInvalid refund amount
      620TXN_FAILURERefund failed
      622TXN_FAILURENo_token-transcation_limited
      623TXN_FAILURERefund is already Success or in Pending state.Please check status query for final result
      640TXN_FAILUREOrder is frozen
      700TXN_FAILUREInvalid consult request
      701TXN_FAILURERefund already raised with same refID
      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/refund/status' --header 'Content-Type: application/json' --data '{"MID":"{mid}","ORDERID":"{order-id}","REFID":"{unique-refund-id}","CHECKSUM":"{checksum}"}'