POSTQuery VAN API

Use Case

This API is used to:

Query VAN details based on VAN number
Query VAN details based on the identification number

Request Attributes

Content Type : JSON

Head

Attribute	Description
requestTimestamp string optional	EPOCH timestamp of the time at which request is being sent. Example: 1588402269
tokenType string mandatory	This parameter identifies whether the API works on checksum authentication. Possible Values: CHECKSUM
token string mandatory	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 optional	The parameter value identifies the Channel for which API call is initiated. Possible values: WEB, WAP
clientId string optional	Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.
version string optional	Version of the API. Example: v1

Body

Attribute

Description

mid

string

optional

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

mandatory

Unique request id

searchKey

string

optional

Possible values: VAN, IDN

searchDetails

object

mandatory

This number will be used to query data

SearchDetails

Attribute	Description
merchantPrefix string conditional	This a merchant identifier called merchant prefix issued to the merchant at the time of onboarding. Merchant can opt for names resembling their business names. E.g. Paytm can opt for merchant prefix as PYTM.
searchId string optional	Identification Number in case of IDN Van number in case of VAN

Response Attributes

Content Type : JSON

Head

Attribute	Description
responseTimestamp string	EPOCH timestamp of the time at which response is being sent. Example: 1588402269
clientId string	Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.
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

van details

VanDetails

Attribute

Description

identificationNo

string

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.

responseStatus

string

SUCCESS/FAIL

searchId

string

Will contain the search Id sent in request

merchantPrefix

string

Merchant identifier issued to the merchant at the time of onboarding. Merchants can opt for names resembling their business names. E.g. Paytm can opt for merchant prefix as PYTM.

errorMessage

string

Provided, in case of errors

errorCode

string

Provided, in case of errors

beneficiaryName

string

Beneficiary Name of the VAN. Along with the VAN, this needs to given to the customer.

ifscCode

string

IFSC code of the VAN. Along with the VAN, this needs to given to the customer.

bankName

string

Bank name in which the VAN is created

van

string

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

active

boolean

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

(Will receive in case of success)

purpose

string

The purpose for which VAN is getting created. This is free string that can be passed by 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

string

Customer details consists of name on 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

string

User-defined fields

Will receive in case of success

tpvList

object

List of bank accounts allowed to make payments to a VAN.

Currently, we are supporting max 20 account addition out of which only 10 can be active at any point in time.

tpvList

Attribute	Description
active boolean	Status of the bank account. TPV will be performed if the bank account status is Active.
accountHolderName string	The person whose name is on a bank account. It can be alphanumeric and supports four special characters-space, a hyphen, full stop and apostrophe.
accountNumber string	Bank account number is the primary identifier for the bank account. It can be alphanumeric and supports two special characters-space and hyphen.
bankName string	The bank of the financial institution where the bank account is held. It can be alphanumeric and supports the following- special characters-space, a hyphen, full stop, apostrophe, ampersand, parenthesis, comma and slash.
ifscCode string	IFSC (Indian Financial System Code) is an 11 digit alphanumeric code that is used to identify the bank branch of a bank account.
nbin string	National Bank Identification Number(NBIN) is an alphanumeric code that is used to identify a bank branch.

Response Codes & Messages

resultCode	resultStatus	resultMessage
0000	S	SUCCESS
0001	F	specific failure message example: body.requestId : requestId should not be empty : rejected value []"
2001	F	Bank Transfer not supported
2002	F	CheckSum Validation Failure
2003	F	Jwt Validation Failure
2004	F	Incorrect mid This case will happen when mid is not passed in request.

Error codes and messages in VanDetails

errorCode	responseStatus	errorMessage
0002	FAILURE	Internal issue.
0003	FAILURE	Internal issue.
0004	FAILURE	Internal issue.
1000	FAILURE	Internal issue.
1001	FAILURE	Internal issue.
1002	FAILURE	Internal issue.
1003	FAILURE	Internal issue.
1004	FAILURE	Internal issue.
1005	FAILURE	Internal issue.
1006	FAILURE	Internal issue.
1007	FAILURE	Internal issue.
1008	FAILURE	Internal issue.
1009	FAILURE	Internal issue.
1010	FAILURE	Internal issue.
1011	FAILURE	Internal issue.
1012	FAILURE	Internal issue.
1013	FAILURE	Internal issue.
1014	FAILURE	Internal issue.
1015	FAILURE	Internal issue.
1016	FAILURE	Internal issue.
1017	FAILURE	Internal issue.
1018	FAILURE	Internal issue.
1019	FAILURE	Internal issue.
1020	FAILURE	Internal issue.
3000	FAILURE	Van doesn't belong to the mid in request
3001	FAILURE	Invalid search id. Accepted value: IDN, VAN
3002	FAILURE	IdentificationNumber length is invalid
3003	FAILURE	Merchant prefix sent in request is invalid
4000	FAILURE	Internal issue.
4002	FAILURE	Internal issue.
4003	FAILURE	Internal issue.
4006	FAILURE	Internal issue.
4007	FAILURE	Internal issue.
5001	FAILURE	In query via van/identificationNo, van does not exist
5002	FAILURE	Internal issue.

⇾

Staging

Production

'https://securestage.paytmpayments.com/vanproxy/api/v1/van/query?mid={mid} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://securestage.paytmpayments.com/vanproxy/api/v1/van/query?mid={mid}' --header 'Content-Type: application/json' --data '{"body":{"requestId":"1602151579","searchKey":"VAN","mid":"{mid}","searchDetails":[{"searchId":"PYLOKP1602146881"}]},"head":{"clientId":"C11","version":"v1","requestTimestamp":1602151579,"channelId":"SYSTEM","tokenType":"CHECKSUM","token":"{checksum}"}}'