1. Introduction
1.1 Merchant QR Generation
Merchant QR generation process includes the interface between the merchant system and NEPALPAY QR network. This interface specification describes a technical level communication of data exchange between the merchant system and the NEPAYPAY QR system.
1.1.1. Authentication and Authorization
Basic Authentication is a common method of authenticating to an API. The client sends HTTP requests with the Authorization header that contains the Basic word followed by a space and a base64-encoded username: password string.
Header key = 'Authorization'
Value = 'Basic '+ base 64 encoding of a username and password separated by a colon.
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Example:
curl --location 'https://<host: port>/qr/generateQR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGxhem1hdDpBYmNkQDEyMw==' \
--data '{
"pointOfInitialization": 12,
"acquirerId": "00002501",
"merchantId": "2501ELFDRY2",
"merchantName": "Plazma Tech",
"merchantCategoryCode": 4121,
"merchantCountry": "NP",
"merchantCity": "Kathmandu",
"merchantPostalCode": "4600",
"merchantLanguage": "en",
"transactionCurrency": 524,
"transactionAmount": "10.00",
"valueOfConvenienceFeeFixed": "0.00",
"billNumber": "012345",
"referenceLabel": null,
"mobileNo": null,
"storeLabel": "Store1",
"terminalLabel": "Terminal1",
"purposeOfTransaction": "Bill payment",
"additionalConsumerDataRequest": null,
"loyaltyNumber": null,
"token": "a1e0pTCtdgqny2BBPgKT/9EaLrRA0J99PYlNyjM5887nkebzvaKtsHT/aciZxXmqsnYMnktXJmseFIsiyE+06476RXrQaCNLEZ4LvsraSz5VWrb/ysA5HgFMqcXyRVCYkC4Ye5Uqbi87wbEyj1bb6Cb2yqDAOGm4uGmn7T5W9Gc="
}'
Post: /qr/generateQR
Request from Merchant to NPI for QR generation.
| # | Data Items | Type | Length | Required | Remarks |
|---|---|---|---|---|---|
| 1 | pointOfInitialization | Integer | 2 | M | Point of Initiation Method (Use 11 for static QR and 12 for Dynamic QR) |
| 2 | acquirerId | String | M | Acquirer of the QR code | |
| 3 | merchantId | String | m | Creditor Id/ Merchant Code | |
| 4 | merchantName | String | 25 | M | Merchant Name |
| 5 | merchantCategory | Numeric | 4 | M | Merchant Category Code |
| 6 | merchantCity | String | M | City | |
| 7 | merchantCountry | String | M | Country code | |
| 8 | merchantPostalCode | String | M | Merchant’s Zip Code/Pin Code/Postal Code | |
| 9 | transactionCurrency | Integer | 3 | M | Currency code (eg. 524 for Nepali rupee) |
| 10 | transactionAmount | Numeric | (12,2) | M | Amount. 0.00 if none. |
| 11 | valueOfConvenienceFeeFixed | Numeric | (10,2) | O | Transaction Fee, if the transaction costs additional fee for the customer. |
| 12 | billNumber | String | 25 | O | Bill No of merchant. 0 if none. |
| 13 | referenceLabel | String | 25 | O | |
| 14 | storeLabel | String | 25 | O | Store label of the QR code. |
| 15 | terminalLabel | String | 25 | O | Terminal id of the QR code.0 if none. |
| 16 | purposeOfTransaction | String | 25 | O | Purpose of transaction. |
| 17 | addnField1-addnField10 | String | 25 | O | Additional fields 1 to 10 for additional usages. |
| 18 | Token | String | M | SHA 256 Signture Token |
Request Sample:
{
"pointOfInitialization":12,
"acquirerId":"00001701",
"merchantId":"17012UVSTIR",
"merchantName":"BBSM",
"merchantCategoryCode":5021,
"merchantCountry":"NP",
"merchantCity":"Kathmandu",
"merchantPostalCode":"4600",
"merchantLanguage":"en",
"transactionCurrency":524,
"transactionAmount":"0.00",
"valueOfConvenienceFeeFixed":"0.00",
"billNumber":"012345",
"referenceLabel":null,
"mobileNo":null,
"storeLabel":"1524525335",
"terminalLabel":"Terminal1",
"purposeOfTransaction":"Bill payment",
"additionalConsumerDataRequest":null,
"loyaltyNumber":null,
"token":"PcK7JFPfEUvtGouuShjQgten7HQsAxxGVZJ+38ORzEOCEMV3Dlt7V0M7g+HUBfn0+oHZqAsb2pzTQHWEQPLmPOGR4lVEoy581vYmN5PfMLSQqb/UxixT1O4X6ZFeV9sVivP3Y1gVfILPIzRm2CfML4BTHhDlpNvoOQ840nvNn2E="
}
TokenString: acquirerId+”, “+merchantId +”, “+merchantCategoryCode+”, “+transactionCurrency+”, “+
transactionAmount+”, “+billNumber+”, “+userId"
Note: userId is a NPI user provided to the merchant.
Successful Response:
{
"timestamp": "2022-05-23 04:25:26",
"responseCode": "000",
"responseStatus": "SUCCESS",
"responseMessage": "QR String generated successfully.",
"data": {
"validationTraceId": "2205260000001900KIY",
"qrString": "00020100020101021229270023NCHL0000170117012UVSTIR52045021530352454040.0056040.005802NP5904BBSM6009Kathmandu6271010100306Khalti0709Terminal10812Billpayment512300192205260000001900KIY6304607F"
}
}
The highlighted section above is the sub tag 51 of field 62 which is validation id generated by NCHL during QR generation. This validation trace id will be used for end to end reporting and reconciliation.
Response
| # | Data Items | Type | Length | Required | Remarks |
|---|---|---|---|---|---|
| 1 | validationTraceId | String | 20 | M | Unique QR validation Id provided by NCHL during QR generation.It will be used for end to end reporting and reconciliation |
| 2 | qrString | String | QR string to be used for QR generation and display. |
Unsuccessful Response
You will get error details in responseResult (i.e. responseCode, responseDescription and fieldErrors) respectively
Successful Response When qrImage Tag Is True:
The highlighted section above is the sub tag 51 of field 62 which is validation id generated by NCHL during QR generation. This validation trace id will be used for end to end reporting and reconciliation.
| # | Data Items | Type | Length | Required | Remarks |
|---|---|---|---|---|---|
| 1 | validationTraceId | String | 20 | M | Unique QR validation Id provided by NCHL during QR generation.It will be used for end to end reporting and reconciliation. |
| 2 | qrString | String | QR string to be used for QR generation and display. | ||
| 3 | qrImage | String | C | Base64 encoded QR Image. |
{
"timestamp": "2024-01-09 11:44:40",
"responseCode": "000",
"responseStatus": "SUCCESS",
"responseMessage": "QR String generated successfully.",
"data": {
"qrString": " 00020100020101021229270023NCHL000023012301JR0R2KT52044111530105406290.14560105802NP5907BigMart6009Kathmandu62830109ABC0001540312Bikash Saran0409A123412340710ConnectIPS512300192401090000204270ZTV6304EC0E",
"validationTraceId": "2401090000204270ZTV",
"qrImage": "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"
}
}
Sample QR Image:
To generate the QR image, decode the output of qrImage tag above with base64 to Image.
Failed Response
{
"responses": [
{
"responseCode": "400",
"responseDescription": "PARAMETER VALIDATION ERROR",
"fieldErrors": [
{
"field": "pointOfInitialization",
"message": "Please use (11 for static QR and 12 for dynamic QR)."
}
]
},
{
"responseCode": "E003",
"responseMessage": "INVALID TOKEN",
"data": "",
"classfielderrorlist": []
}
]
}
Not Found
{
"responseCode": "E010",
"responseMessage": "RECORD NOT FOUND:- Merchant not found!",
"data": null,
"classfielderrorlist": []
}
Internal Server Error-500
{
"responseCode": "E999",
"responseMessage": "ERROR",
"data": null,
"classfielderrorlist": []
}
In case of service not available
{
"timestamp": "2022-05-26 04:07:22",
"responseCode": "E999",
"responseMessage": "ERROR",
"data": null
}