search

POSTUpdate VAN API

Use Case

  • This API is used to disable/enable VAN's. Status of the VAN account. It has two possible values:
    • Active - If the VAN is active, money transferred by the customer will be accepted
    • Inactive - If the VAN is Inactive, money transferred by the customer will be reversed
  • Additionally, this API is used to add bank account numbers to an existing VAN to support third-party validation (TPV). 

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestTimestamp
string(15)
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

tokenType
string(10)
mandatory

This parameter identifies if the API works on checksum authentication.

Possible Values: CHECKSUM,JWT

token
string
mandatory
  • For tokenType JWT, use JWT token.
  • For tokenType CHECKSUM, the value to be sent should be the checksum string created using the 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

AttributeDescription
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(20)
mandatory

Unique request id

vanInfo
object
mandatory

Van info consists of the Virtual Account Number ( VAN) and its status. At least one VAN and max 10 can be activated or inactivated in a single go.

VanInfo
+
AttributeDescription
van
string(16)
mandatory

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
mandatory

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
tpvList
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
Account Number
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(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

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".

vanInfo
object

Van info consists of Virtual Account Number (VAN) and its status. At least one VAN and max 10 can be activated or inactivated in a single go.

VanInfo
+
AttributeDescription
van
string(10)

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

vanStatus
string

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
responseStatus
string

Possible Values: SUCCESS, FAILED

errorCode
string(3)

Provided in case of errors

errorMessage
string

Provided in case of errors

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

Status of response

errorCode
string

Provided in case of error

errorMessage
string

Provided in case of error

Response Codes & Messages

resultCoderesultStatusresultMessage
200 SUCCESS Success
302 FAILED Request Validation Failure
401 FAILED Invalid Request
404 FAILED Data Not Found
502 FAILED Unknown Error Occurred

Error codes and messages in VanDetails

ERRORCODE RESPONSESTATUS ERRORMESSAGE
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.
⇾
Staging
Production
https://securegw-stage.paytm.in/vanproxy/api/v1/van/update?mid={mid}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl - X POST 'https://securegw-stage.paytm.in/vanproxy/api/v1/van/update?mid={mid}'\
    --header 'Content-Type: application/json'\
    --data '{"body": {"requestId": "1607519443", "mid": "{mid}", "vanInfo": [{"van": "{van}", "active": "true", "tpvList": [{"accountHolderName": "Test Account 1", "accountNumber": "917777777777", "bankName": "Paytm Payments Bank", "ifscCode": "PYTM123456", "nbin": "string", "active": true } ] } ] }, "head": {"clientId": "C11", "version": "v1", "requestTimestamp": "1607519443", "channelId": "WEB", "tokenType": "CHECKSUM", "token": "{checksum}"} }'

 

copy icon