VAN API Integration Suite
VAN (Virtual Account Number) solution from Paytm Payments Bank Limited (PPBL) helps you create multiple virtual account numbers that are linked to the current/nodal account you have opened with PPBL. These virtual accounts can then be distributed to users from whom money needs to be collection. Once these users transfer funds from their bank accounts, you will automatically be able to reconcile outstanding collections. You no longer need to go through the cumbersome manual process of matching collections using transaction reference number/ screenshots shared by users. VAN solution reduces manual effort involved in reconciliation as well as eliminates human errors.
Let’s understand how PPBL VAN solution solves your business needs using an example.
Let’s assume ABCD Private Limited (APL) is an educational institute and needs to collect tuition fees from students each month for 3 courses (COURSE A, COURSE B, COURSE C) it offers. ABCD identifies each student uniquely using their roll numbers (Student 1’s roll number is 000001, Student 2’s roll number is 000002 and so on).
APL opens a Current Account (A/C No 710000000123) with PPBL and opts for VAN solution. APL starts creating VAN numbers by following below guidelines.
- All PPBL VANs are fixed length (16 characters)
- PPBL VANs support upper case letters (A-Z) and digits (0-9) only. No special characters are allowed. Each VAN is split into 2 parts: prefix and suffix.
- Prefix is common for VANs created on top of a particular account.
- Suffixes are different for each VAN created on top of a particular account.
APL selects VAN prefix as ‘APL’.
Then APL has to select suffix for each VAN. This suffix has to be different for all VANs created by APL
For Student 1 who has enrolled for COURSE A, suffix can COURSEA000001. VAN given to Student 1 will be APLCOURSEA000001
For Student 2 who has enrolled for COURSE A, suffix can COURSEA000002. VAN given to Student 2 will be APLCOURSEA000002
For Student 3 who has enrolled for COURSE B, suffix can COURSEB000003. VAN given to Student 3 will be APLCOURSEB000003
Now APL distributes VANs to all students (along with Account Name as ABCD private limited and IFSC as PYTM0123456). Student 1 who has VAN ‘APLCOURSEA000001’ now needs to make pay his monthly tuition fees. Student 1 adds APLCOURSEA000001 as a beneficiary in his personal bank account and initiates an outward NEFT payment worth INR 10,000 on APLCOURSEA000001. The moment this amount is credited to APL’s Current Account (710000000123), APL will get notified (via a Call-back API) that credit has been made using VAN ‘APLCOURSEA000001’. APL can knock-off outstanding fees against Student 1 for Course A for the given month. There is no need for Student A to share transaction UTR (or screenshot of the same) with APL’s finance team.
VAN Collection with TPV
What is Third Party Validation/Verification (TPV)? What is it's importance?
Third Party Validation/Verification (TPV) is a process of validating customer’s information as a pre-approved and authorized information by an independent party. Third-party validation is a very important step in the BFSI (Banking, Financial Services and Insurance) sector.
Merchants of these sectors are prone to frauds, money laundering, tax-evasion activities, etc. In order to mitigate such risks, Securities and Exchange Board of India (SEBI) has mandated that all businesses operating in these sectors must ensure that payments are accepted from the customers' registered, KYC-approved bank accounts only.
Using PPBL VAN Collection API, you can comply with the regulatory guidelines to ensure that the customers make payments only from their registered bank accounts (TPV Accounts). If payments are made from the unregistered accounts (non-TPV), they are automatically refunded to the customers.
PPBL VAN - TPV features
To facilitate Third Party Validation, helping businesses comply with the SEBI regulatory guidelines and ensure their customers have a seemless payment experience through their registered bank accounts, PPBL enhanced its existing VAN Collection API services. The salient features of PPBL VAN - TPV are:
- VAN TPV Activation: You can enable TPV feature on all VANs (VANs over Current Accounts & Nodal Accounts), by simply adding a TPV account. If a TPV account is not added then it is a regular VAN.
- VAN TPV Addition: You can add the TPV VANs while creating a VAN or for existing VANs.
- TPV Account Status: You can mark TPV Account(s) Active / Inactive that are mapped to a VAN.
- No. of TPV Accounts for a VAN: Each VAN can be mapped with 10 Active TPV Accounts. You can map upto a total of 20 accounts (with maximum of 10 active accounts)
- Fetch TPV Accounts for a VAN: You can fetch details of all the TPV accounts mapped to a given VAN.
- Third Party Account Validation Rules: Each funding transaction of a TPV activated VAN will be subjected to validation. The remitter account details would be validated based on the mode of transaction:
- For NEFT & RTGS Transactions (If IFSC is provided to the client): Match on account number after removing leading zeros + IFSC
- For NEFT & RTGS Transactions (If IFSC is not provided to the client): Match on account number after removing leading zeros
- For IMPS & Xfer Transactions: Match on account number after removing leading zeros
- Note: IFSC code is not a mandatory fields for validation.
- TPV Failures: All transactions which fail due to TPV would be instantly refunded to the remitter account.
- TPV Success / Failure Notifications: PPBL shall share MIS with TPV success or failure details for every transaction on a given VAN or set of VAN(s).
Overview of VAN API Suite
- Create Virtual Account Number (VAN): You can create a Virtual Account Number using this API. You can also add TPV accounts (if needed) while creating the VAN.
- Update VAN: Using this API you can enable/disable a VAN for accepting/rejecting fund inflow to the VAN. You can also add TPV accounts and update TPV account status to Active / Inactive.
- List all VAN details for an Account Number: This API returns the list of all VANs (with details) mapped to the specified account number.
- Get VAN details for a VAN ID: This API returns all details stored for a specified VAN ID. You can also fetch the details of all the TPV accounts mapped to a VAN.
- Search VAN(s) by set filter(s): This API returns VAN(s) & its details for specified filter(s). For example: You can search VAN(s) created between two given dates.
In order to create VANs using API suite, clients first have to complete integration testing on PPBL staging environment.
- Client needs to reach out to respective PPBL Key Account Manager (KAM) to get test credentials created.
- Client requests for a particular VAN prefix. KAM checks if prefix is available on staging environment and confirms to client. Client also share call-back URL for staging. This URL will be used to receive notifications every time a credit is made to underlying account using a VAN created on top of the account.
- KAM will get a test account created on PPBL staging environment and get necessary configurations done in PPBL tech systems.
- Post this, partner id and secret key will be shared with client on their email ids. These will be used in all API requests for authentication at PPBL end (more details mentioned later)
- Client should first integrate all APIs for VAN management (create, edit, disable, view)
- Once VAN Management has been integrated and tested, client needs to test call-back integration on staging. For this, clients need to reach out to respective KAM as they will not be able to transfer money to VANs on staging environment. KAM will get test transactions initiated on VANs created on staging using different pay-modes (IMPS, NEFT, RTGS, within PPBL transfers) using PPBL staging simulator. Client will receive call-back notifications every time a successful credit is made on a VAN.
- Client notifies KAM that integration testing is complete.
- Once integration testing is complete, client can go live with VAN solution.
- Client requests for VAN prefix on production environment. KAM checks if prefix is available on production environment and confirms back to client. Client also shares call-back URL and IPs for production environment. URLs need to be different for staging and production environment
- KAM gets necessary configurations done on client’s current / nodal account opened with PPBL.
- Client id and secret key is then shared with client on their registered email ids
- Client can now start creating VAN on production environment.
Each PPBL VAN has a prefix. Client ABCD Private Limited who has a current account with PPBL chose prefix as APL. Prefix helps clients do branding for their company.
Guidelines for prefix
- Client can opt for only 1 Prefix for a given current/ nodal account.
- Prefix will be common for all VANs created on top of a given current/ nodal account.
- PPBL suggests that Prefix length should be between 2-10 characters. If the length of a prefix is too long, client will not have sufficient characters left in suffix to generate the required number of VANs
- Prefix is subject to availability. If a particular prefix has already been allotted to a different client, the same cannot be issued to a new client
Note: Client will have to reach out to PPBL KAM to get prefix generated (on staging and production both).
Verification of Secret Key and Connectivity
PPBL will share secret key with client separately over email. Clients should save the secret key securely at their end as this key will be required in all the API requests to authenticate the API request. In case the key gets compromised, client should reach out to PPBL immediately. PPBL will disable this key and share new keys with the client.
The client will have to do an authentication verification at PPBL end by generating a JWT (JSON Web Token) token and verifying it using PPBL's API. This verification will ensure that the client is able to connect to PPBL's systems and the requests are successfully accepted at PPBL. Follow the below specified steps for verifying the same:
- Pre-requisites to verification of secret key:
- A test current/nodal account will be created separately by PPBL for client integration
- Partner id will be created and shared by PPBL to client.
- Secret key will be created and shared by PPBL to client.
Follow the below steps to create JWT for Authentication header of APIs :
2) Paste the sample JWT token given below in the Encoded column :
Sample JWT :
3) Update the following parameters in the PAYLOAD column :
a). partnerId - unique id generated by PPBL and shared after onboarding the partner
b). timestamp - current timestamp value in milliseconds (for sample you can copy the UNIX time from this website https://currentmillis.com/)
c). requestReferenceId - a unique request id to track the request, this id should always be unique for each request generated.
4) Paste the secret Key shared in the VERIFY SIGNATURE column and un-check the "secret base64 encoded" checkbox :
5) Now copy the JWT created in the Encoded column and use it as Authorization header in the API:
Authenticate created JWT token:
Sample Curl to check the JWT token created using the above process :
curl --location --request POST 'https://pass-api-staging.paytmbank.com/api/ts/transaction/ext/v3/user-balance?account_type=ca'
--header 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJQQVlUTSIsInRpbWVzdGFtcCI6IjE1NDEwNDQyNTcwMDAiLCJwYXJ0bmVySWQiOiJOb2RhbF9QYXJ0bmVyIiwicmVxdWVzdFJlZmVyZW5jZUlkIjoiUmVxMTIzIn0.dkSTKhskJIhcxrbtElVkC037agtevqhWR24AW1mlhCA' \
--header 'Content-Type: application/json'