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

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

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

requestId

string(64)

mandatory

Unique reference ID which is given in request payload

searchParams

object

mandatory

Search parameters to filter data

SearchParams

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

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

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

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: 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

Attribute

Description

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

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

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

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

resultCode	resultStatus	resultMessage
0000	S	Success
0001	F	Mandatory parameter missing
3015	F	Invalid date format
3016	F	start date should be less than end date
3017	F	invalid status, should be true/false
3018	F	Van 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://securestage.paytmpayments.com/vanproxy/api/v1/van/search?mid={mid} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://securestage.paytmpayments.com/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="}}'