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

      Refund API

      Checksum required: Yes

      Use Case


      To initiate partial or complete refund of transaction done on Paytm payment gateway

      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)Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.Yes
      txnIdString (64)TXNID is Paytm payment Transaction Id against which the refund transaction is being placed. TXNID is provided in response payload for every payment transaction.Yes
      refundAmountStringAmount 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 (".")Yes
      txnTypeStringThis has fixed value for refund transaction - "REFUND".Yes
      commentsString (500)Comments can be given by merchant citing the reason for refund. No
      preferredDestinationStringFor refunds to source, this parameter is not required. In case merchant has taken instant refund solution from Paytm and customer has allowed refund to his bank account, then the value to be passed is TO_INSTANT.No

      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)For websites, the value is WEB
      For Mobile websites/App, the value is WAP.
      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.
      orderIdString (50)OrderId is merchant's unique Reference Id against which the refund transaction is being placed.
      refIdString (50)Merchant's Reference Id unique for every refund transaction. This is REFID for which refund status is being inquired.
      refundAmountString (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 (",").
      refundIdString (64)This is a unique Paytm Refund Id that is issued by Paytm for each refund request.
      resultInfoResultInforesultInfo Object
      txnAmountString (10)Order value of the transaction in INR.
      txnIdString (64)TXNID is Paytm payment Transaction Id against which the refund transaction is being placed.
      txnTimestampString (20)Timestamp of payment transaction.

      ResultInfo

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

      Response Codes and Messages

      resultCoderesultStatusresultMsg
      10TXN_SUCCESS Refund Successful
      501PENDING System Error
      601PENDING Refund request was raised for this transaction. But it is pending state.
      330TXN_FAILURE Checksum provided is invalid
      335TXN_FAILURE Mid is invalid
      600TXN_FAILURE Invalid refund request.
      607TXN_FAILURE Refund can not be initiated for a cancelled transaction.
      617TXN_FAILURE Refund Already Raised
      619TXN_FAILURE Invalid refund amount
      626TXN_FAILURE Not allowed to reprocess refund request
      627TXN_FAILURE Order Details Mismatch
      628TXN_FAILURE Refund is in Pending state.Please check status query for final result
      629TXN_FAILURE Refund is already Successful
      635TXN_FAILURE Partial Refund under Rupee 1 is not allowed

      Endpoints

      Staging: https://securegw-stage.paytm.in/refund/apply

      Production: https://securegw.paytm.in/refund/apply

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/refund/apply' --header 'Content-Type: application/json' --data '{"body":{"mid":"{mid}","txnType":"REFUND","orderId":"{order-id}","txnId":"{transaction-id}","refId":"{unique-refund-id}","refundAmount":"{amount-to-refund}"},"head":{"clientId":"{client-id}","signature":"{signature}"}}'
      

      Old Refund API

      Checksum required: Yes

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

      Use Case


      To initiate partial or complete refund to source account from which the transaction was done

      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 complete.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
      TXNID String(64)TXNID is Paytm payment Transaction Id against which the refund transaction is being placed. TXNID is provided in response payload for every payment transaction.Yes
      ORDERID String(50)OrderId is merchant's unique Reference Id against which the refund transaction is being placed. OrderID is provided by merchant in transaction request payload.Yes
      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. Only special character allowed is (".").Yes
      TXNTYPE StringThis has fixed value for refund transaction - "REFUND".Yes
      CHECKSUM String(108)Signature to avoid tampering. Generated using server side checksum utility available here.Yes
      COMMENTS String(50)Comments can be given by merchant citing the reason for refund.No
      preferredDestination String1)For refunds to the source, the merchant need not pass this parameter. In case merchant has taken instant refund solution from Paytm and customer has given permission to refund into his bank account, then the value to be passed is To_INSTANT.
      2)If the refund is done via token then this parameter is MANDATORY and its value should be either TO_VPA(is token is generated for VPA)/TO_INSTANT(if the token is generated for an account).
      No
      token String(128)token generated via (/api/v1/account/validate?mid=<mid>&requestId=<requestId>) API.No

      Response Attributes

      ATTRIBUTEDESCRIPTION
      MID String(20)This is a unique identifier provided to every merchant by Paytm.
      TXNID String(64)TXNID is Paytm payment transaction ID against which the refund transaction is being placed.
      ORDERID String(50)ORDERID is merchant's unique reference ID against which the refund transaction is being placed.
      REFUNDAMOUNT String(10)Amount for which refund is supposed to be made.
      TXNAMOUNT String(10)Order value of the transaction in INR.
      REFID String(50)Unique Reference Id for refund transaction which is generated by merchant and sent in the request.
      STATUS String(20)This contains the status of refunds. It has following values: TXN_SUCCESS, TXN_FAILURE & PENDING.
      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.
      TXNDATE DateTimeDate of payment transaction in the format "yyyy-MM-dd HH:mm:ss.S"
      Format - "2015-11-02 11:40:46.0".
      CARD_ISSUER String(20)Name of issuing bank of the payment instrument used by customer. By paymodes, the details are provided below
      Credit, debit cards, UPI - Name of the issuing bank. Example in case customer uses SBI's credit card, the value will be "SBI"
      NB - empty string
      Paytm Wallet - empty string.
      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.
      REFUNDDATE DateTimeDate and timeof REFUND in the format "yyyy-MM-dd HH:mm:ss.S"
      EX- "2015-11- 02 11:40:46.0".
      REFUNDID String(64)This is a unique Paytm Refund Id that is issued by Paytm for each refund request.
      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
      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.

      Response Codes and Messages

      RESPCODESTATUSRESPMSG
      10TXN_SUCCESSRefund successful
      601PENDINGRefund request was raised for this transaction. But it is pending state.
      328TXN_FAILURECurrency not same
      501TXN_FAILURESystem error
      600TXN_FAILUREInvalid 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
      612TXN_FAILUREThis is a valid authorized transaction
      617TXN_FAILURERefund already raised
      619TXN_FAILUREInvalid refund amount
      620TXN_FAILURERefund failed
      622TXN_FAILURENo_token-transcation_limited
      635TXN_FAILUREPartial Refund under Rupee 1 is not allowed
      640TXN_FAILUREOrder is frozen
      700TXN_FAILUREInvalid consult request
      701TXN_FAILURERefund already raised with same refid
      702TXN_FAILURENot allowed to reprocess refund request
      703TXN_FAILURERefund is already success or in pending state. Please check status query for final result
      704TXN_FAILUREBalance not enough
      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/refund/process' --header 'Content-Type: application/json' --data '{"MID":"{mid}","TXNTYPE":"REFUND","TXNID":"{transaction-id}","ORDERID":"{order-id}","REFUNDAMOUNT":"{amount-to-refund}","REFID":"{unique-refund-id}","CHECKSUM":"{checksum}"}'