8. Virtual Payment Address (VPA) Based Payment

A Virtual Payment Address (VPA) is a unique identifier that resolves the bank account details and facilitate for the payment even without knowing beneficiary account details. It acts as an ID independent of your bank account number and other details. The VPA can be then used to transfer funds from one account to another directly, without providing bank account details. With the implementation of VPA based fund transfer, NPI integrated banks alternative channels, PSPs and connectIPS users can transfer the fund to the beneficiary account based on the VPA. For now, registered mobile number in banks KYC, connectIPS system and PSPs wallet has been considered as a virtual payment address. The VPA address can also be any unique id provided by the other service provided like PSPs, etc. Below are the some of the pre-requisites to the NPI members for participating VPA based payment ecosystem.

The participating member has to be integrated with NPI for VPA based payments.
Unique id has to be provided by any service providers like Bank, PSPs and connectIPS system.
In case of connectIPS VPA based payment, user has linked the account in connectIPS system and set the primary account to receive the fund.
The mobile number of the connectIPS user must match with the mobile number present at the KYC of the transaction receiving bank of the receiver.

8.1. Process Flow

With the current implementation, VPA based payments can be initiated either direct to the bank providing the beneficiary registered mobile number in banks KYC or through connectIPS system.

Sender initiates the VPA based payment by providing the sender mobile number registered in banks KYC. In case of connectIPS system based VPA payment, recipient should have linked account in connectIPS system and set as primary.
The VPA engine resolves the corresponding bank account details based on the mobile number provided by the sender.
Sender will get the beneficiary account number and name with masking to make sure the correctness of recipient.
After sender confirms that payment, it will follow the normal payment flow where sender account will be debited and beneficiary account will be credited. In case of VPA based payment initiated from PSPs respective wallet, pool account will be debited and beneficiary account will be credited.
After payment is successful, notification is sent back to the sender.

Example Image

Figure:Process flow diagram for VPA

8.2. Fetch Participant Details

Virtual Payment Address (VPA) based payments can be made to the three types of participants namely connectIPS, Bank and Wallet. Th below API endpoint is designed to fetch the list of corresponding participants in VPA based payment network.

POST URL: <hostname: port>/vpa/detail

Sample Request

{ 
"type":"ALL" 
} 

Network Type ALL: Fetch the list of all participants in VPA based payment network.

BANK: Fetch the list of banks available for VPA based payment.

CIPS: connectIPS system

PSP: Fetch the list of wallets available for VPA based payment.

Sample Response

{
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"VPA detail list",
   "responseData":[
      {
         "name":"NIC Asia Bank Ltd",
         "code":"2301",
         "type":"BANK"
      },
      {
         "name":"Nabil bank Limited",
         "code":"0401",
         "type":"BANK"
      },
      {
         "name":"connectIPS",
         "code":"CONNECTIPS",
         "type":"CIPS"
      },
      {
         "name":"Khalti",
         "code":"WAL-10-KHA-2",
         "type":"PSP"
      }
   ],
   "responseErrors":[
      
   ]
}

Note: For VPA based transaction, code of this sample response to be used as bankId in next API.

8.3. Fetch Account Details

Before making the VPA based transactions, payment detail has to be fetched from respective systems with corresponding unique identifier (VPA).

POST URL: <hostname: port>/vpa/account/detail

Request Parameters

#	Parameter Name	Data Type	Constraint	Description	Presence
1	originatorUniqueId	String	Length (max.20)	Originator unique identifier	M
2	bankId	String	Length (max. 4)	Beneficiary participant code in NCHL system	M
3	vpa	String	Length (10)	Beneficiary identifier (VPA) for fund transfer	M
4	requestToken	String		Token	M

Token String= originatorUniqueId+”,” +vpa+”,” + bankId +”,” + userId

Response Parameters

#	Parameter Name	Data Type	Constraint	Description	Presence
1	requestIdentifier	String	Length (30)	Request id provided by NPI	M
2	originatorUniqueId	String	Length (max.20)	Originator unique identifier	M
3	vpa	String	Length (10)	Beneficiary identifier (VPA) for fund transfer	M
4	bankId	String	Length (max. 4)	Beneficiary participant code in NCHL system	M
5	acctName	String		Beneficiary account name	M
6	accountId	String	Length (max. 20)	Beneficiary account number	M
7	token	String		Token	M

Token String =requestIdentifier+ “,” +originatorUniqueId+ “,” +vpa+ “,” + bankId + “,” + acctName + “,” + accountId + “,” + userId

Sample Request

{ 
 "originatorUniqueId": "VPA-116", 
 "vpa": "9855555555", 
 "bankId": "2501", 
 "requestToken":"XB4Vw27hArPaerQuLSZj……………dD38dK1W6Z+9gjPMcD2A4P=" 
}

Success Response

{
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"Account Detail",
   "responseData":{
      "requestIdentifier":"20221103150555130N0h",
      "originatorUniqueId":"VPA-116",
      "vpa":"9855555555",
      "bankId":"2501",
      "acctName":"ANKI*****PANE",
      "accountId":"0010********0018",
      "token":"CCa1OXSRyvD6cCsAOxLyzjkMtVFovOg**...***l0d3zKok0HOus=",
      "branchId":"1"
   },
   "responseErrors":[
      
   ]
}

Failure Response

Case I

{
   "responseCode":"E007",
   "responseDescription":"TECHNICAL VALIDATION FAILED",
   "fieldErrors":[
      {
         "field":"originatorUniqueId",
         "message":"Duplicate request."
      }
   ]
}

Case II

{
   "responseCode":"400",
   "responseDescription":"PARAMETER VALIDATION ERROR",
   "fieldErrors":[
      {
         "field":"vpa",
         "message":"VPA should not less than 10-character."
      }
   ]
}

8.4. Transaction Posting

After the payment details are fetched successfully from the respective system, payment has to be confirmed with following details. The beneficiary details like account number, name or wallet user id will be provided in masked format for user confirmation before submitting the payment.

POST URL: /vpa/paywithvpa

Request Parameters

#	Parameter Name	Data Type	Constraint	Description	Presence
1	requestIdentifier	String	Length(20)	Request id provided by NPI	M
2	originatorUniqueId	String	Length(max. 30)	Originator unique identifier	M
3	vpa	String	Length(10)	Beneficiary identifier (VPA) for fund transfer	M
4	bankId	String	Length(max. 4)	Bank ID of /vpa/account/detail response	M
5	debtorAgent	String	Length(max. 4)	Debtor bank code in NCHL system	M
6	debtorBranch	String	Length(max. 4)	Debtor branch code in NCHL system	M
7	debtorAccountId	String	Length(max. 20)	Debtor account number	M
8	debtorName	String		Debtor account name	M
9	amount	BigDecimal		Transaction amount	M
10	remark	String	Length(max. 30)	Transaction remarks	M
11	token	String	Token		M

Token String = originatorUniqueId+ “,” +requestIdentifier+ “,” + vpa+ “,” +bankId+ “,” +debtorAgent+”,” + debtorBranch+ “,” + debtorAccountId+ “,” + amount+ “,” + userId

Response Parameters

#	Parameter Name	Data Type	Constraint	Description	Presence
1	requestIdentifier	String	Length(20)	Request id provided by NPI	M
2	originatorUniqueId	String	Length(max. 30)	Originator unique identifier	M
3	vpa	String	Length(10)	Beneficiary identifier (VPA) for fund transfer	M
4	debitStatus	String	Length(3)	Debit status	M
5	creditStatus	String	Length(3)	Credit status	M
6	npiBatchId	String		Corresponding batch id for transaction	M
7	npiTranactionId	String		Corresponding transaction id for transaction	M
8	Token	String		Token	M

Token String=originatorUniqueId+ “,” +requestIdentifier+ “,” + vpa+ “,” + debitStatus+ “,” +npiBatchId+ “,” + npiTransactionId+ “,” + userId

Sample Request

{
   "requestIdentifier":"20221103150555130N0h",
   "originatorUniqueId":"VPA-116",
   "vpa":"9855555555",
   "bankId":"2501",
   "debtorAgent":"0401",
   "debtorBranch":"53",
   "debtorAccountId":"0530039999999999",
   "debtorName":"Raj Shrestha",
   "amount":200,
   "remark":"Test VPA Payment",
   "token":"N2DEQvWpbDsDDtD17ZZ1lMbnHrlnFf5xz29**……**SFKrPOUPxEl6wvpf6GGxxYQ="
}

Success Response

{
   "requestIdentifier":"20221103150555130N0h",
   "originatorUniqueId":"VPA-116",
   "vpa":"9855555555",
   "debitStatus":"000",
   "creditStatus":"000",
   "npiBatchId":"712020253",
   "npiTransactionId":"12346404",
   "token":"Aa0BI2HDB6OcfPleNbh5/******……………****** +rXobHMrWWFJYpcQ3NlGfRL/Ag="
}

Note: For the finality of VPA based payment, kindly consider debit status (000) and credit status (000, DEFER,999).

Failure Response

Case-I

{ 
 "responseCode": "409", 
 "responseDescription": "Duplicate Request.", 
 "billsPaymentDescription": null, 
 "billsPaymentResponseCode": null, 
 "fieldErrors": [] 
}

Case-II

{
   "responseCode":"400",
   "responseDescription":"PARAMETER VALIDATION ERROR",
   "fieldErrors":[
      {
         "field":"vpa",
         "message":"VPA should not less than 10-character."
      }
   ]
}

8.5. VPA Transaction Reporting

8.5.1. By Date: Transaction reporting allows NPI users to fetch reports within period of 90 days.

POST URL: /vpa/transaction/detail

Request Parameters

{
 "fromDate": "2023-08-02",
 "toDate": "2023-09-01"
}

Success Response:

{
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"Report Fetched Successfully",
   "responseData":{
      "data":[
         {
            "vpa":"9813979589",
            "txnAmount":5353.28,
            "requestIdentifier":"20230814110116659QEH",
            "isoTxnId":465752,
            "txnDate":"2023-08-14",
            "bankId":"MER-89-PTC-1",
            "creditStatus":"1000",
            "debitStatus":"1001",
            "chargeAmount":null,
            "originatorUniqueId":"WNIC32944911393",
            "endToEndId":"Wallet Transfer 99917064016",
            "referenceId":"9813979589",
            "data1":null,
            "data2":null,
            "remarks":"Wallet Transfer 99917064016"
         },
         {
            "vpa":"Business travel",
            "txnAmount":500.00,
            "requestIdentifier":"EMT100011",
            "isoTxnId":465830,
            "txnDate":"2023-08-15",
            "bankId":"MER-1-APP-3",
            "creditStatus":"000",
            "debitStatus":"000",
            "chargeAmount":null,
            "originatorUniqueId":"232001166135EMT100011",
            "endToEndId":"Business travel",
            "referenceId":"Business travel",
            "data1":null,
            "data2":null,
            "remarks":null
         }
      ],
      "page":0,
      "totalResult":2,
      "totalPages":0
   },
   "responseErrors":[
      
   ]
}

Failure Response:

{
   "responseCode":"E007",
   "responseStatus":"FAILED",
   "responseMessage":"Transaction Not Found",
   "responseData":[
      
   ],
   "responseErrors":[
      
   ]
}

8.5.2. By Originator Unique Id: Transaction details are queried based on originator unique id.

POST URL: /vpa/transactiondetailbyid

Request Parameters

{
 "originatorUniqueId": "WNIC32944911393"
}

Success Response:

{
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"Report Fetched Successfully",
   "responseData":{
      "vpa":"9813979589",
      "txnAmount":5353.28,
      "requestIdentifier":"20230814110116659QEH",
      "isoTxnId":465752,
      "txnDate":"2023-08-14",
      "bankId":"MER-89-PTC-1",
      "creditStatus":"1000",
      "debitStatus":"1001",
      "chargeAmount":null,
      "originatorUniqueId":"WNIC32944911393",
      "endToEndId":"Wallet Transfer 99917064016",
      "referenceId":"9813979589",
      "data1":null,
      "data2":null,
      "remarks":"Wallet Transfer 99917064016"
   },
   "responseErrors":[
      
   ]
}

Failure Response:

{
   "responseCode":"E007",
   "responseStatus":"FAILED",
   "responseMessage":"Transaction Not Found",
   "responseData":[
      
   ],
   "responseErrors":[
      
   ]
}

8. Virtual Payment Address (VPA) Based Payment

8.1. Process Flow​

8.2. Fetch Participant Details​

8.3. Fetch Account Details​

8.4. Transaction Posting​

8.5. VPA Transaction Reporting​

8.5.1. By Date: Transaction reporting allows NPI users to fetch reports within period of 90 days.​

8.5.2. By Originator Unique Id: Transaction details are queried based on originator unique id.​

8.1. Process Flow

8.2. Fetch Participant Details

8.3. Fetch Account Details

8.4. Transaction Posting

8.5. VPA Transaction Reporting

8.5.1. By Date: Transaction reporting allows NPI users to fetch reports within period of 90 days.

8.5.2. By Originator Unique Id: Transaction details are queried based on originator unique id.