paytm developer docs logoDeveloperDocumentation
search

POSTOrder List API

Use Case

This API can be used by the merchant to fetch the order level details for a given MID and respective date range.

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestTimestamp
string(15)
optional

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

tokenType
string(10)
mandatory

This parameter identifies whether the API works on checksum authentication. 

Possible Values: CHECKSUM, JWT

signature
string
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(64)
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

orderSearchType
string
mandatory

Transaction type of payment

Note: Need to put "|" pipe for separation in between.

Possible Values: TRANSACTION, REFUND, M2B, TRANSFER_FOR_SETTLEMENT, CANCEL, REPAYMENT, TRANSFER_TO_BANK, CHARGEBACK, ALL

orderSearchStatus
string
mandatory

Type of search status for Order List

Note: Need to put "|" pipe for separation in between.

Possible Values: SUCCESS, FAILURE, PENDING

merchantOrderId
string
optional

Unique reference ID for an Order request generated by the merchant for payment.

Example: OREDRID_98765

fromDate
string
mandatory

Pass the from date from which transactions need to fetch

Note: Max Range supported is 30 days. The value of orderCreatedStartTime should be in 18 months.

Example format: YYYY-MM-DDTHH:MM:SS

toDate
string
mandatory

Pass the end date

Note: Max Range supported is 30 days. The value of orderCreatedStartTime should be in 18 months.

Example format: YYYY-MM-DDTHH:MM:SS

payMode
string(64)
optional

Payment Mode used in payment

Example: BANK_TRANSFER

isSort
string
optional

Decide whether sort the query result, the default value is false;

  • true: meaning sort the query result, then Platform+ will limit the total query count to 10000
  • false: meaning not sort the query result, then Platform+ will not limit the total query count

Example: true/false

pageNumber
Integer
mandatory

Offset of records to show (Default: 1)

pageSize
Integer
mandatory

Number of records to fetch for this Page (Default: 20)

searchConditions
object
optional

Search conditions contain the value for VAN_ID and RRN_CODE

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string(15)

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

version
string(4)

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

signature
string

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

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

resultStatus
string(64)

This parameter indicates the status of the API call.

Possible Values: SUCCESS, INVALID_SIGNATURE, MANDATORY_PARAM_MISSING, REQUEST_PARAMS_INVALID, SYSTEM_ERROR, CHECKSUM_VALIDATION_FAILED

resultMsg
string (256)

This parameter is the result message which contains information about the result. The different result messages corresponding to this API are mentioned below in section " Response Codes and Messages".

resultCodeId
string (64)

Failure reason code where status is FAILURE. A detailed list of statusCode is mentioned at the bottom of this page.

orders
object

order details

Orders
+
AttributeDescription
merchantOrderId
string

Unique reference ID for an Order request generated by the merchant for payment.

Example: PPBL561219199111010

orderCreatedTime
string

Order creation request initiation date and time

Example: 2020-12-14 10:36:24

orderCompletedTime
string

Order completion date and time

Example: 2020-12-14 10:36:28

payMode
string

Type of transaction

Example: BANK_TRANSFER

amount
string

Amount in INR requested by the merchant for this order

Example: 20.00

txnId
string

Transaction Id of the payment

Example: 20201214111212800110168278400437455

vanId
string

Virtual Account Number. This is the 16 alphanumeric account number to which customer has initiated the transfer.

Example: van-PY1010K73578974

vanIfscCode
string

Ifsc code of van account

Example: PYTM0123456

rrn
string

Unique transaction reference number from the bank. This is only provided for bank account transfer.

Example: rrnCode-92325522

orderSearchStatus
string

Status of the Order

Example: SUCCESS

orderSearchType
string

The type of order

Example: TRANSACTION

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

merchantName
string

Name of the merchant entity

Example: vaibhav

pageNum
string

current page number

pageSize
string

record size per page

Response Codes and Messages

ResultStatus ResultCodeId ResultCode ResultMsg
SUCCESS 1001 SUCCESS Success
INVALID_SIGNATURE 4001 FAILURE

Provided Signature is invalid
MANDATORY_PARAM_MISSING 4002 FAILURE Mandatory Param Missing
REQUEST_PARAMS_INVALID 4003 FAILURE Invalid Request Params
SYSTEM_ERROR 4099 FAILURE System Error
CHECKSUM_VALIDATION_FAILED 4009 FAILURE Checksum validation failed
⇾
Staging
Production
https://securegw-stage.paytm.in/merchant-passbook/search/list/order/v2copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw.paytm.in/merchant-passbook/search/list/order/v2 \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"INTEGR77698636129383","fromDate":"2021-01-25T23:59:35+08:00","toDate":"2021-02-02T23:59:35+08:00","orderSearchType":"TRANSACTION","orderSearchStatus":"SUCCESS","pageNumber":"1","pageSize":"50","searchConditions":[{"searchKey":"VAN_ID","searchValue":"PYI3831611899004"}]},"head":{"requestTimestamp":"","tokenType":"CHECKSUM","signature":"meuvQL3iu0X7JodCFtBXDNC1klm3KU8wuUlGKg/gyeT3qfMEUjHrqGxms7x9LFOZvVIeh5/u3FdrKnsEycWULp6N06URowmrct+gsI1N78A="}}'
copy icon