search

POSTRefund Status API

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

Content Type : JSON

Head

AttributeDescription
version
string(4)
optional

Version of the API.

Example: v1

channelId
string(3)
optional

The parameter value identifies the Channel for which API call is initiated.

 
Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
requestTimestamp
string(15)
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

clientId
string(3)
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(108)
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

AttributeDescription
mid
string(20)
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(50)
mandatory

It is unique reference ID for a transaction passed in the transaction request and in Refund API. Order ID should be pass to check the actual status of refund.

Example: OREDRID_98765

refId
string(50)
mandatory

Merchant's Reference Id unique for every refund transaction. This is REFID for which refund status is being inquired.

Example: REFUNDID_98765

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string(2)

Version of the API passed in the request.
Example: v1

channelId
string(3)

The parameter value identifies the Channel for which API call is initiated.

Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
responseTimestamp
string(15)

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

clientId
string(3)

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(108)

You should validate the parameter values by verifying the signature comes in the response. It ensures that parameter values not tempered. Signature string can be verified by using Paytm checksum library.

Body

AttributeDescription
resultInfo
object

This parameter gives the information about the result of the API response

ResultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field  
 

Possible Values: TXN_SUCCESS, TXN_FAILURE, PENDING, NO_RECORD_FOUND

resultMsg
string

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

mid
string(20)

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(50)

Order ID is merchant’s unique reference ID for a transaction that has sent in request.

Example: OREDRID_98765

refId
string(50)

Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.
Example: REFUNDID_98765

refundId
string(64)

This is a unique Paytm Refund Id that is issued by Paytm for each refund request.

Example: 123455081112128XXXXXX68470101509706

txnId
string(64)

TXNID is Paytm payment Transaction Id against which the refund transaction is being placed.

Example: 202005081112128XXXXXX68470101509706

txnTimestamp
string(20)

Timestamp of customer to merchant payment transaction.

Example: 2020-05-02 12:24:25.0

source
string

Source.

Example: Merchant

txnAmount
string(10)

Order value of the transaction in INR.

Example: 100.00

refundAmount
string

Amount for which refund was initiated by the merchant. It can be equal to or less than the transaction amount.

Example: 30.00

totalRefundAmount
string(10)

Total cumulative refund amount against this transaction.
For example for a transaction with an order value as INR 100, there have been two refunds of INR 30 & INR 40 historically, then TOTALREFUNDAMT will be INR 70.

Example: 70.00

merchantRefundRequestTimestamp
string(30)

EPOCH timestamp of the time at which request is being sent.

Example: 2020-05-02 12:24:25.0

maxRefundRetryTimeStamp
string

Timestamp till which system refund retry would be attempted in case of insufficient MPA.

Example: 2020-05-02 12:24:25.0

acceptRefundStatus
string

Status of Paytm accepting the refund

acceptRefundTimestamp
string(30)

Timestamp at which Paytm accepted the refund. At the time of acceptance refund amount is deducted from the merchant payable balance

Example: 2020-05-02 12:24:25.0

userCreditInitiateStatus
string

Status of Paytm initiating the refund with the acquirer

userCreditInitiateTimestamp
string(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

Example: 2020-05-02 12:24:25.0

refundReason
string

Reason passed at the time of initiating the refund

Example:  Sample Refund Reason

refundDetailInfoList
array of object

Details of refund like masked refund destination, refund amount allocation, RRN Number etc

RefundDetailInfoList
+
AttributeDescription
payMethod
string(10)

Payment method through which the refund has happened

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 the refund will be realized instantly by the customer.

refundAmount
string(10)

Amount for which refund was initiated by the merchant. It can be equal to or less than the transaction amount.
Example: 30.00

issuingBankName
string(50)

Name of issuing bank where refund is being credited

maskedCardNumber
string(25)

    
For credit/debit card refunds, this contains the masked number of the card where the refund is being credited to.

cardScheme
string(10)

For credit/debit card refunds, this contains the card scheme where refund is being credited to

userMobileNo
string(15)

User's masked mobile number

maskedVpa
string(30)

For UPI refunds, this contains the VPA where refund is being credited to

maskedBankAccountNumber
string(25)

For To_instant refund type, this contains the masked bank account where refund is being credited to

ifscCode
string

Ifsc code of the bank

Example: BACB0000003

issuingBankCode
string

Code of issuing bank where refund is being credited

rrn
string(20)

Reference number with which customers 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.

arn
string

Unique Reference Number generated by the Acquirer Bank for Visa, Master and Rupay networks that indicates the settlement between the acquirer and card issuing bank is complete.

Please note ARN is 23 digit number typically starting with 3, 7 or 8 and is not the same as RRN (Retrieval Reference Number).

Example: 73256633124312285716334

arnAvailable
boolean

Indicates the eligibility of ARN for card refunds.
Possible Values: false

userCreditExpectedDate
string(50)

Latest timestamp for customers to realize the refund

Example: 2020-05-02 12:24:25.0

agentInfo
object

Refund initiator details. These will be available in refund success response and refund report generated from merchant panel 
 

AgentInfo
+
AttributeDescription
employeeId
string

Employee ID of the person who initiated refund

Example: EMP-001

name
string

Name of the person who initiated refund

Example: Test

phoneNo
string

Phone number of the person who initiated refund

Example:  7777777777

email
string

EmailID of the person who initiated refund

Example: customer@example.com

gatewayInfo
string

Response provided by the gateway during payment or transaction. This is available for Super Router product only.

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_FAILUREBALANCE_NOT_ENOUGH
631TXN_FAILURERecord not found
602TXN_FAILURERefund cannot be processed by the bank
663TXN_FAILURERefund cannot be processed as chargeback received at banks' end
664TXN_FAILURERefund cannot be processed by the bank as customer source account is frozen
665TXN_FAILURERefund cannot be processed by the bank as customer source account is closed
666TXN_FAILURERefund cannot be processed by the bank as customer source account limit breached
667TXN_FAILURERefund cannot be processed by the bank as refund window expired
668TXN_FAILURERefund cannot be processed by the bank as issuing bank is down or facing issues
669TXN_FAILURERefund rejected by the bank due to risk
⇾
Staging
Production
https://securegw-stage.paytm.in/v2/refund/statuscopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/v2/refund/status' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","orderId":"ORDERID_98765","refId":"REFUNDID_98765"},"head":{"signature":"{signature}"}}'
copy icon