search

POSTCreate VAN API

Use Case

This API is used to:

  • Create VANs for an entity/customer. In response, VAN Number, IFSC Code, and Beneficiary Name is received. This needs to give to the entity/customer to make the required payment.
  • Add bank account numbers to a VAN to support third-party verification (TPV). 
     

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

Unique for each request

vanDetails
object
mandatory

These details will be used to create VANs. You can create a minimum of 1  and a maximum of 10 VANs at a time. 

Additionally, bank accounts can be added to a given VAN for third-party validation (TPV). 

VanDetails
+
AttributeDescription
identificationNo
string
mandatory

This is 10 digits alphanumeric string that forms that 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
mandatory

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.

purpose
string
optional

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
object
optional

Customer details consists of name on contact details

CustomerDetails
+
AttributeDescription
customerName
string
optional

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
optional

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
optional

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
optional

User defined fields

UserDefinedFields
+
AttributeDescription
UDF1 - UDF5
string
optional

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.

tpv
object
optional

This list is used to add the bank accounts which will be 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
accountNumber
string
mandatory

Bank account number is the primary identifier for the bank account. It can be alphanumeric and supports two special characters-space and hyphen.

active
boolean
mandatory

Status of the bank account. TPV will be performed if the bank account status is Active.

accountHolderName
string
optional

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.

bankName
string
optional

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
optional

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
optional

National Bank Identification Number(NBIN) is an alphanumeric code that is used to identify a bank branch.

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

These details will be used to create VANs. You can create a minimum of 1  and a maximum of 10 VANs at a time. 

VanDetails
+
AttributeDescription
van
string

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

identificationNo
string

This is 10 digits alphanumeric string that forms that 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

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

responseStatus
string

Possible Values: SUCCESS, FAILURE

bankName
string

Bank name in which VAN is created

beneficiaryName
string

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

errorCode
string

Provided in case of errors

errorMessage
string

Provided in case of errors

ifscCode
string

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

tpvList
object

In case of failure only, the first bank account where the bank account added to a VAN failed will be returned in the response.

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

responseStatus
string

Possible Values: SUCCESS, FAILURE

errorCode
string

Provided in case of error

errorMessage
string

Provided in case of error

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
3004 FAILURE Customer detail should not me more then 1
3006 FAILURE Email id format not correct
3100 FAILURE Internal issue.
3101 FAILURE Internal issue.
3102 FAILURE Internal issue.
3103 FAILURE Internal issue.
3104 FAILURE Internal issue.
3105 FAILURE Internal issue.
3106 FAILURE Internal issue.
4000 FAILURE Internal issue.
4002 FAILURE Internal issue.
4003 FAILURE Internal issue.
4004 FAILURE Internal issue.
4005 FAILURE Internal issue.
4006 FAILURE Internal issue.
4007 FAILURE Internal issue.
4008 FAILURE Internal issue.
4009 FAILURE Internal issue.
4010 FAILURE In Van creation, if the van already exists
4010 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?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl - X POST 'https://securegw-stage.paytm.in/vanproxy/api/v1/van?mid={mid}'--header 'Content-Type: application/json'--data '{"body": {"requestId": "1618814077", "mid": "{mid}", "vanDetails": [{"identificationNo": "1618814077", "purpose": "Testing only", "merchantPrefix": "1234", "customerDetails": [{"customerEmail": "testuser@gmail.com", "customerMobile": "7777777777", "customerName": "test user"} ], "userDefinedFields": {"udf1": "test1", "udf2": "test2", "udf3": "test3", "udf4": "test4", "udf5": "test5"}, "tpvList": [{"accountHolderName": "Test Account 1", "accountNumber": "917777777777", "bankName": "Paytm Payments Bank", "ifscCode": "PYTM123456", "nbin": "string", "active": true } ] } ] }, "head": {"clientId": "C11", "version": "v1", "requestTimestamp": "1618814077", "channelId": "WEB", "tokenType": "CHECKSUM", "token": "{checksum}"} }'
copy icon