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

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

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

Attribute

Description

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

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

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

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

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

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

Attribute

Description

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

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

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

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
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}"} }'