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

Attribute	Description
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
version string(4) optional	Version of the API. Example: v1
requestTimestamp string(15) optional	EPOCH timestamp of the time at which request is being sent. Example: 1588402269
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"
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

Attribute	Description
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

Attribute	Description
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
version string(2)	Version of the API passed in the request. Example: v1
responseTimestamp string(15)	EPOCH timestamp of the time at which response is being sent. Example: 1588402269
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"
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

Attribute

Description

resultInfo

object

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

ResultInfo

Attribute	Description
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 indicates the status of API call. Possible Values: TXN_SUCCESS, TXN_FAILURE, PENDING
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

txnId

string(64)

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

Example: 202005081112128XXXXXX68470101509706

orderId

string(50)

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

Example: OREDRID_98765

refundId

string(64)

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

Example: 123455081112128XXXXXX68470101509706

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

txnAmount

string(10)

Order value of the transaction in INR.

Example: 1.00

refundAmount

string

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 (".")

Example: 1.00

totalRefundAmount

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

Example: 1.00

acceptRefundStatus

string

Status of Paytm accepting the refund

userCreditInitiateStatus

string

Status of Paytm initiating the refund with the acquirer

merchantRefundRequestTimestamp

string(30)

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

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

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

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

txnTimestamp

string(20)

Timestamp of payment transaction.

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

refundDetailInfoList

array of object

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

RefundDetailInfoList

Attribute	Description
payMethod string(10)	Payment method through which the refund has happened
rrn string(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
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 (".") Example: 1.00
issuingBankName string(50)	Name of issuing bank where refund is being credited
userCreditExpectedDate string(50)	Latest date for customer to realize the refund
maskedCardNumber string(25)	For credit/debit card refunds, this contains the masked number of the card where refund is being credited to
cardScheme string(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
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 bank Example: BACB0000003
issuingBankCode string	Code of issuing bank where refund is being credited

refundReason

string

Reason passed at the time of initiating the refund

Example: Sample Refund Reason

agentInfo

object

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

AgentInfo

Attribute	Description
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

Response Codes & Messages

resultCode	resultStatus	resultMsg
10	TXN_SUCCESS	Refund successful
501	PENDING	System error
601	PENDING	Refund request was raised for this transaction. But it is pending state.
330	TXN_FAILURE	Checksum provided is invalid
335	TXN_FAILURE	Mid is invalid
600	TXN_FAILURE	Invalid refund request
620	TXN_FAILURE	BALANCE_NOT_ENOUGH
631	TXN_FAILURE	Record not found

⇾

Staging

Production

https://securegw-stage.paytm.in/v2/refund/status copy 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}"}}'