search

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

AttributeDescription
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

AttributeDescription
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
+
AttributeDescription
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

AttributeDescription
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

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

van details

VanDetails
+
AttributeDescription
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
+
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
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
+
AttributeDescription
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

resultCoderesultStatusresultMessage
0000SSUCCESS
0001Fspecific failure message example: body.requestId : requestId should not be empty : rejected value []"
2001FBank Transfer not supported
2002FCheckSum Validation Failure
2003FJwt Validation Failure
2004FIncorrect 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://securegw-stage.paytm.in/vanproxy/api/v1/van/query?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/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}"}}'
copy icon