paytm developer docs logoDeveloperDocumentation
search

POSTVAN List API

Use Case

This API is used to fetch VANs basis various parameters such as mid and VAN status created between a specific 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

token
string
mandatory
  • For tokenType JWT, use JWT token.
  • For tokenType CHECKSUM, It's value to be sent should be the checksum string created by using Paytm checksum library. Authorization string corresponding to the tokenType used.

Example: 16Xm7DXbvNqhaLw+HMj4XB6XTQKCoM=

channelId
string(6)
optional

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

Possible Values: WEB/WAP/SYSTEM

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
optional

Version of the API.

Example: v1

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

requestId
string(64)
mandatory

Unique reference ID which is given in request payload

searchParams
object
mandatory

Search parameters to filter data

SearchParams
+
AttributeDescription
mid
string
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

active
boolean
optional

Status of the VAN account. It has two possible values: 

  • Active - If a VAN is active, money transferred by the customer will be accepted
  • Inactive - If a VAN is Inactive, money transferred by the customer will be reversed
startDate
string
optional

Pass the start date from which VANs were created in Unix timestamp

Example: Date format-1596562773000

endDate
string
optional

Pass the end date in Unix timestamp

pageInfo
object
mandatory

Consists of pagination info for the VAN list.

Example: If there are 100 records, if the offset is 2, and the limit is 100, you will get records from 2 to 100 in response.

PageInfo
+
AttributeDescription
limit
Integer
mandatory

Per page response list size. Min value is 1 and the max is 100.

offset
integer
mandatory

Number of records to be skipped. The default value is 1.

Response Attributes

Content Type : JSON

Head

AttributeDescription
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

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 indicates the status of API call.

Possible values:
S
For Success
,
F
For Failure
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 in section " Response Codes and Messages".

vanDetails
object

List of VAN details

VanDetails
+
AttributeDescription
identificationNo
string(10)

This is a 10 digits alphanumeric string which forms the last 10 digits of the VAN. While merchants can use this in multiple ways possible, this should be unique to the entity against which reconciliation is required. The length of this is fixed and hence needs to be accommodated for while passing this number.

merchantPrefix
string(4)

Merchant identifier issued to the merchant at the time of onboarding. Merchants can opt for names resembling their business names.

Example: Paytm can opt for merchant prefix as PYTM.

beneficiaryName
string

Beneficiary Name of the VAN.

ifscCode
string

IFSC code of the VAN.

bankName
string

Bank name in which the VAN is created.

van
string(16)

Virtual Account Number. This is a 16 alphanumeric account number which will be given to the end customer to initiate a bank transfer.

active
string

Status of the VAN account. It has two possible values:

  • Active - If a VAN is active, money transferred by the customer will be accepted
  • Inactive - If VAN is Inactive, money transferred by the customer will be reversed
date
string

Date of van creation.

purpose
string

Purpose for which the VAN is getting created. This is a free string that can be passed by the merchant. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.

customerDetails
Object

Customer details consist of name and contact details.

CustomerDetails
+
AttributeDescription
customerName
string

Name of the entity to which the VAN is being given to. It can be name of customer, name of area etc. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.
Going forward this will be used in email and SMS communication in VAN disbursals amongst customers.

customerEmail
string

Email ID of the customer. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.
Going forward this will be used in email and SMS communication in VAN disbursals amongst customers.

customerMobile
string

Mobile Number of the customer. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.
Going forward this will be used in email and SMS communication in VAN disbursals amongst customers.

userDefinedFields
Object

User-defined fields.

UserDefinedFields
+
AttributeDescription
UDF1 - UDF5
string

UDF stands for user-defined fields. These fields can be used by merchants for reconciliation purpose. The value passed in these fields will be available in order APIs, webhooks, VAN APIs, transaction and settlement report against the payment received for a particular VAN.

pageInfo
Object
PageInfo
+
AttributeDescription
offset
Integer

Number of records to be skipped. The default value is 1.

limit
Integer

Per page response list size. Min value is 1 and the max is 100.

nextPage
boolean

True/False. True, when more than 100 records are present else False. The merchant needs to send the request again with different offset and limit to fetch the remaining VANs. 

total
Integer

Total number of pages corresponding to this query.

Response Codes & Messages

resultCoderesultStatusresultMessage
0000 S Success
0001 F Mandatory parameter missing
3015 F Invalid date format
3016 Fstart date should be less than end date
3017 Finvalid status, should be true/false
3018 FVan not found - case where searchParams mid mismatch happens with parent level mid

Error codes and messages

Below error codes will be sent if downstream service sends a failure response to VAN service during search/query filter response. The error codes are different as it will be easy to track the failure reason from downstream. Merchants may not need to handle each below error.

errorCode responseStatus errorMessage
6000 F Process Fail
6001 F Process Fail
6002 F Process Fail
6003 F Process Fail
6004 F Process Fail
6005 F Process Fail
⇾
Staging
Production
https://securegw-stage.paytm.in/vanproxy/api/v1/van/search?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/vanproxy/api/v1/van/search?mid=INTEGR77698636129383' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"INTEGR77698636129383","requestId":"1607417598","searchParams":{"mid":"INTEGR77698636129383","startDate":"1603082659000","endDate":"1603090554000"},"pageInfo":{"limit":2,"offset":1}},"head":{"channelId":"SYSTEM","tokenType":"CHECKSUM","token":"PPMg/0d4YqSvt97b2bnZc0153QsB8e3VVXHGd5ANcDhdkgAE1U/fxlzsPpx627Dx4zQNI1NZGBG7Bw+0hws6lot8o+RTAyyrHtwApgUuBes="}}'
copy icon