search

POSTRefund List API

Use Case

To fetch the list of refund requests completed between two dates.

Request Attributes

Content Type : JSON

Head

AttributeDescription
tokenType
string
mandatory

Authentication method

Example: CHECKSUM

clientId
string(3)
mandatory

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

isSort
string
optional

Used to sort the refund results in ascending or descending order based on refund date

Example: true

startDate
string
mandatory

Include refunds from start date time (yyyy-MM-ddTHH:mm:ss zzzz)

Example: "2020-06-01T00:34:00+05:30"

endDate
string
mandatory

Include refunds till end date time (yyyy-MM-ddTHH:mm:ss zzzz)

Example: "2020-06-01T00:34:00+05:30"

pageNum
string
optional

Page number for which merchant has requested

Example: 2

pageSize
string
optional

Page size that merchant has requested

Example: 20

Note

  • The current capacity is that only refund records up to 20K can be sorted in a given time range.
  • The difference between start time and end time should be less then or equal to 30 Days.
  • On a single page we can display upto 50 records.

Response Attributes

Content Type : JSON

Body

AttributeDescription
status
string

Status of Request

Example: Success

count
int

Number of result found

Example: 1

resultCode
string

resultCode

Example: 00000000

errorMessage
string

Message

Example: Success

orders
object

Order Details

Orders
+
AttributeDescription
mid
string

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

The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”.
Example: OREDRID_98765

refId
string

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

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

Example: 123455081112128XXXXXX68470101509706

txnAmount
string

Order value of the transaction in INR.
Example: 100.00

txnTimeStamp
string

Timestamp of customer to merchant payment transaction.

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

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

merchantRefundRequestTimeStamp
string

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

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

acceptRefundStatus
string

Status of Paytm accepting the refund

acceptRefundTimeStamp
string

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

Response Codes & Messages

resultCodestatuserrorMessage
00000000TXN_SUCCESSSuccess
00000010TXN_FAILUREINTERNAL_SERVER_ERROR
00000022TXN_FAILURECHECKSUM_VALIDATION_FAILED
00000030TXN_FAILUREILLEGAL_PARAM
00000031TXN_FAILUREFACADE_EXCEPTION
00000040TXN_FAILUREMERCHANT_NOT_FOUND
00000073TXN_FAILUREInvalid date format or invalid date range
⇾
Staging
Production
https://securegw-stage.paytm.in/merchant-passbook/api/v1/refundListcopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/merchant-passbook/api/v1/refundList' \
--header 'content-type: application/json' \
--data-raw '{"head": {"tokenType": "CHECKSUM","clientId": "C11","signature": "{signature}"},"body": {"mid":"{mid}","isSort":"true","startDate":"2020-06-01T00:34:00+05:30","endDate":"2020-06-30T14:35:24+05:30","pageSize":10,"pageNum":1}}'
copy icon