2. API For Bulk Merchant Upload

2.1. API To Register Merchant On NEPALPAYQR

The "Merchant Bulk Upload on QR" feature helps to streamline and simplify the process of onboarding multiple merchants or businesses into NEPALPAYQR while seamlessly assigning them unique QR codes for identification and payment acceptance.

Post: /api/merchant/bulk-upload

Request parameters:

#	Data Items	Type	Length	Required	Remarks
1	fullname	String	25	M	Merchant Common Name
2	legalName	String		M	Full Name of the Merchant
3	merchantCategoryCode	String	4	M	Merchant Category Code (MCC)
4	district	String		M	Merchant Address
5	province	String		M	Merchant Address
6	registrationType	String		M	Registration type of merchant - sole-proprietorship - partnership - public - private
7	idDocNumber	String		M	Merchant PAN number.
8	ownerName	String		C	Required depends on registration type Required for - sole-proprietorship - private partnership
9	gender	enum		C	Required depends on registration type Required for - sole-proprietorship - private - partnership Values: - MALE - FEMALE
10	firstname	String		M	Merchant Owner Registered Name
11	middlename	String		O	Merchant Owner Registered Name
12	lastname	String		M	Merchant Owner Registered Name
13	mobileNumber	String		M	Merchant Owner Mobile Number
14	email	String		M	Merchant Owner Email Address
15	accountNumber	String		M	Merchant Account Number
16	accountName	String		M	Merchant Account Name
17	bankCode	String	4	M	Merchant Bank Code
18	currency	String	3	M	Currency symbol (e.g. NPR)
19	user	String		M	NPI User ID
20	identificationCode	String		M	Acquirer Code
21	subIdentificationCode	String		M	WAL in case of wallet

Sample Request

{
   "merchantDetailBulk":[
      {
         "merchantDetailDto":{
            "fullname":"Nepal Farm House",
            "legalName":"Nepal Farm House Limited",
            "idDocNumber":"505693548",
            "registrationType":"private",
            "merchantCategoryCode":"5021",
            "district":"Kathmandu",
            "province":"3",
            "merchantOwnerDetailsDto":{
               "ownerName":"Ramesh Malla",
               "gender":"MALE"
            }
         },
         "userDetailDtos":[
            {
               "firstname":"Saurav",
               "middlename":"",
               "lastname":"Khatri",
               "mobileNumber":"98XXXXXXX",
               "email":"test1@gmail.com.np"
            }
         ],
         "accountDetailDtos":[
            {
               "accountNumber":"XXXXXXXXXXXXXX",
               "accountName":"Pankaj Singh",
               "bankCode":"1121",
               "branchCode":"2",
               "currency":"NPR"
            }
         ]
      },
      {
         "merchantDetailDto":{
            "fullname":"Nepal Wood House",
            "legalName":"Nepal Wood House Limited",
            "idDocNumber":"51616161",
            "registrationType":"private",
            "merchantCategoryCode":"5021",
            "district":"Kathmandu",
            "province":"3",
            "merchantOwnerDetailsDto":{
               "ownerName":"Hira Shrestha",
               "gender":"FEMALE"
            }
         },
         "userDetailDtos":[
            {
               "firstname":"Rjish ",
               "middlename":"",
               "lastname":"Singh",
               "mobileNumber":"98XXXXXXX",
               "email":"test1@gmail.com.np"
            }
         ],
         "accountDetailDtos":[
            {
               "accountNumber":"XXXXXXXXXXXXXX",
               "accountName":"Rashmi Paula",
               "bankCode":"0521",
               "branchCode":"2",
               "currency":"NPR"
            }
         ]
      }
   ],
   "requestUserDetailDto":{
      "user":"TEST@",
      "identificationCode":"00021000",
      "subIdentificationCode":"WAL"
   },
   "token":"HmKKt047G+Wflk9a2jLBV3F7ecAgE4lJqRQGqQYBOJu+wVcjI/hdYHQTJ4h1ES4/Up7a9/ng5U7ca/4Y1pSulx0FaSxhczbnFjsbTILPP7/GmgtxtdPiWIswsmnBXM0EAYnJZhAtFXUWmSALPctjCnBWoUdAZ80OUx3IYEQ2QEM="
}

Token Generation Process:

Token string generation

The token string is created by appending the merchant and user detail fields. Following will be the procedure for token string generation: For each Merchant Detail data section, follow format, including the enclosed curly bracers:

<idDocNumber>:<idDocNumber>,<merchantCategoryCode><mobileNumber>, <email>,<accountNumber>,<currency>,<bankCode>

For NPI User Detail data section, follow format, including the enclosed curly bracers:

requestUserDetailDto:<identificationCode>, <user>

For the finalized session token, follow format:

Token String = <MerchantDetailSection-1>,....,<MerchantDetailSection-N>,<UserDetailSection>

1. Generate signed hash value of token string using private key of provided certificate.
2. Send the generate hash value in “token” field.

Sample Token String:

{"505693548":"505693548,5021,9843705813,sauravkhatri@nchl.com.np,0100200000009020,NPR,0301","r
equestUserDetailDto":"00021000,WAL,SAURAV@999"}

Sample Response

{
   "responseCode":"000",
   "responseMessage":"Merchants successfully uploaded.",
   "responseData":[
      {
         "merchantCode":"1000NOUOFMB",
         "qrString":"01021129270023NCHL000210001000NOUOFMB52045021530352454010560105802NP5920NepalClearingHouse6009Kathmandu6244010100306Store10709Terminal10812Billpayment64060002en63045AC6",
         "fullName":"Nepal Clearing House"
      }
   ],
   "responseErrors":null,
   "responseStatus":null
}

Failed Response

{
   "timeStamp":"2023-10-04 01:58:47",
   "statusCode":"400",
   "status":null,
   "messages":[
      {
         "field":"merchantDetailBulk[0].merchantDetailDto.panNumber",
         "message":"Merchant with pan number '52873162' already exist."
      }
   ],
   "responseMsg":"Duplicate Merchant Found",
   "responseData":null
}

2.2. API To Download QR String

The "API to Download QR String" is a crucial component of our application's functionality that allows the acquirer to retrieve QR code strings for various purposes. This API endpoint serves as a bridge between our system and external applications or devices, enabling seamless integration and generation of NQR of the enrolled merchant’s

Post: /api/merchant/info

Sample Request

{
   "merchantCode":"1000NOUOFMB",
   "requestUserDetailDto":{
      "user":"SAURAV@999",
      "identificationCode":"00021000",
      "subIdentificationCode":"WAL"
   },
   "token":"HkfZqIsPSaqK7jy0JfPgrBI8vpESUl9cy1GXTXHw23MI6MTKpTgbSSEcPRIz9IJzaRCUkQYChTncNeoHTCR5ItuXv2gert3YsJoUZ03FHst4KqJ1ZNy1/ze3lMsShzOSJ7nCRPcwyx0xzPbTYTUXPYWLYjVqgxIwT6eZCFpcBgs="
}

Sample Response

{
   "responseCode":"000",
   "responseMessage":null,
   "responseData":{
      "merchantCode":"1000NOUOFMB",
      "acquirerId":"00021000",
      "legalName":"Nepal Clearing House Limited",
      "createdAt":"2024-01-25T11:05:32.907+00:00",
      "status":"APPROVED",
      "qrString":"01021129270023NCHL000210001000NOUOFMB52045021530352454010560105802NP5920NepalClearingHouse6009Kathmandu6244010100306Store10709Terminal10812Billpayment64060002en63045AC6"
   },
   "responseErrors":null,
   "responseStatus":null
}

TOKEN STRING: merchantCode,identificationCode,user

Eg:1000NOUOFMB,00021000,SAURAV@999

2.3. API To Fetch Transaction Reports

NEPALPAY QR Network members will have access to various reporting API related to Transaction and Reconciliation report, session query, etc. for the purpose of reporting and reconciliation of the transactions and payments.

Post: /nQR/v1/settledsession

This reporting API is used to fetch the list of sessions in Retail Payment Switch(RPS) and their status based on settlement data and session serial. Sessions with status SETTLED to be considered for the reconciliation of QR transactions.

Request parameters

#	Data Items	Type	Length	Required	Remarks
1	sessionSrlno	Integer		C	Session number to enquiry the status
2	dateSettled	String		C	YYYY-MM-dd Format date to get all the sessions settled on that date.

Response parameters

#	Data Items	Type	Length	Required	Remarks
1	sessionSrlno	D		M	Session number
2	Status	String		M	Session Status (e.g. “ACTIVE”,” SETTLED”). In order to cancel a transaction, the session must be in “ACTIVE” status
3	dateSettled	String		C	YYYY-MM-dd Format date to get all the sessions settled on that date.

Sample request:

{
"dateSettled":"2021-11-15"
}

Sample response:

 {
   "timestamp":"2022-01-16T07:33:08.383+0000",
   "responseCode":"200",
   "responseStatus":"SUCCESS",
   "responseMessage":null,
   "responseBody":[
      {
         "sessionSrlNo":1559,
         "status":"GENERATED",
         "settlementDate":"2021-12-18",
         "dateSettled":null
      },
      {
         "sessionSrlNo":1563,
         "status":"SETTLED",
         "settlementDate":"2021-12-18",
         "dateSettled":null
      }
   ]
}

2.3.1 Reconciliation report specifications

Post: /nQR/v1/report

This reporting API is used to fetch the list of all transactions of settled session based on session serial of particular issuer & acquirer.

Request Parameters

#	Data Items	Type	Length	Required	Remarks
1	sessionSrlno	Integer		M	Session number to enquiry the status
2	issuerId or acquirerId	String		M	NEPALPAY Issuer Id

Response Parameters

#	Data Items	Type	Length	Required	Remarks
1	sessionSrlno	String			Session number for the transaction
2	recDate	Date			Date of transaction recording
3	instructionId	String	20		Unique reference id to trace the request by issuer/acquirer
4	nQrTxnId	String	20		Unique payment transaction id generated by NCHL.
5	acquirerId	String			Acquirer of the QR code
6	issuerId	String			Issuer id
7	network	String			Network of the QR code
8	issuerNetwork	String			Network of the issuer.
9	amount	Numeric	(12,2)		Amount
10	interchangeFee	Numeric	(10,2)		Charge if applicable else 0.00
11	transactionFee	Numeric	(10,2)		IF additional cost to be paid by the customer for the transaction. else 0.00
12	debitStatus	String			Payer Account Debit status
13	creditStatus	String			Receiver Account Credit status
14	PayerName	String	200		Name of the payer
15	transactionType	String			PMT-Payment, RFND-Refund
16	payerMobileNumber				Mobile No of Payer
17	merchantName	String
18	merchantTxnRef	String
19	terminal	String			Terminal id of the QR code
20	merchantBillNo	String			Bill No of merchant

Request sample:

{
 "sessionSrlNo":"1542", 
 "issuerId or acquirerId ":"00004501"
}

Response Sample:

{
   "timestamp":"2021-08-10T11:14:41.893+0545",
   "responseCode":"200",
   "responseMessage":"SUCCESS",
   "responseBody":[
      {
         "nQrTxnId":"2107230000000003XBI",
         "tranType":"PMT",
         "instructionId":"HBLQR-1191982838",
         "issuerId":"00000701",
         "acquirerId":"00000701",
         "amount":2200.11,
         "transactionFee":0.00,
         "interchangeFee":15.00,
         "merchantName":"Merchant Name",
         "merchantBillNo":"44454",
         "merchantTxnRef":null,
         "payerName":"Kiran Maharjan",
         "payerMobileNumber":"+977-9849752010",
         "debitStatus":"000",
         "creditStatus":"DEFER",
         "sessionSrlNo":1214,
         "recDate":"2021-07-23",
         "terminal":"MOB",
         "network":"NQR",
         "issuerNetwork":"NQR"
      },
      {
         "nQrTxnId":"2107230000000005LGB",
         "tranType":"PMT",
         "instructionId":"MBLQR-4589756",
         "issuerId":"00001501",
         "acquirerId":"00000701",
         "amount":10000.00,
         "transactionFee":0.00,
         "interchangeFee":53.25,
         "merchantName":"Merchant Name",
         "merchantBillNo":"0",
         "merchantTxnRef":"56555",
         "payerName":"Sudip Shah",
         "payerMobileNumber":"+977-9851011596",
         "debitStatus":"000",
         "creditStatus":"CNCL",
         "sessionSrlNo":1214,
         "recDate":"2021-07-23",
         "terminal":"CIPS",
         "network":"NQR",
         "issuerNetwork":"NQR"
      },
      {
         "nQrTxnId":"2107230000000004BIJ",
         "tranType":"RFND",
         "instructionId":"MOCO_RFND-12358",
         "issuerId":"00001601",
         "acquirerId":"00000701",
         "amount":500.00,
         "transactionFee":0.00,
         "interchangeFee":0.00,
         "merchantName":"Merchant Name",
         "merchantBillNo":"0",
         "merchantTxnRef":"21072300000000423KIO",
         "payerName":"Rakesh Pokheral",
         "payerMobileNumber":"+977-9849752010",
         "debitStatus":"000",
         "creditStatus":"000",
         "sessionSrlNo":1214,
         "recDate":"2021-07-23",
         "terminal":"WAL",
         "network":"NQR",
         "issuerNetwork":"NQR"
      },
      {
         "nQrTxnId":"2107230000000002FRR",
         "tranType":"PMT",
         "instructionId":"EVRSTQR-4545544",
         "issuerId":"00001001",
         "acquirerId":"00000701",
         "amount":300.25,
         "transactionFee":5.25,
         "interchangeFee":2.50,
         "merchantName":"Merchant Name",
         "merchantBillNo":"jjhd6",
         "merchantTxnRef":null,
         "payerName":"Jeevan Shrestha",
         "payerMobileNumber":"+977-9851752010",
         "debitStatus":"000",
         "creditStatus":"DEFER",
         "sessionSrlNo":1214,
         "recDate":"2021-07-23",
         "terminal":"MOB",
         "network":"NQR",
         "issuerNetwork":"XXX"
      }
   ]
}

2.4. API To Fetch Merchant Category Code

Post: /api/merchant/merchantcategorycodes

{
   "requestUserDetailDto":{
      "user":"SAURAV@999",
      "identificationCode":"00021000",
      "subIdentificationCode":"WAL"
   },
   "token":"TSorsyJY3g57B313hEKOfGJFBbw0W8mS8ClHv8l4zwSRleEtmJgaEdXp/3hzlF9ON4owmLb3Jpmem4rAnrZA0NwvsaBETVw+ZujQupuM/avjAXXLo2rfX61W/fYshupOKcWW7CapaSJw4QHmJlxdlilKxy1W3isG2POcfd4DlHc="
}

TOKEN STRING: identificationCode,user Eg:00021000,SAURAV@999

2.5. Annexure

Following are the list of response codes used in Open NPI that could be technical and business. HTTP Reason codes FORBIDDEN, BAD REQUEST and INTERNAL SERVER ERROR are exceptional cases which requires the exact technical setups and message structures mentioned in the document. These HTTP statuses contains same response message format as mentioned below with response code. All technically valid messages will be responded with HTTP status OK which has a fixed format and doesn’t change. Technical Response Format (FORBIDDEN, BAD REQUEST and INTERNAL SERVER ERROR):

{
"responseCode": "<Response Code>",
"responseDescription": "<Response Messages>",
"fieldErrors": [],
}

Technical Error Codes
Reason Code	Reason Description	Remarks
000	Success	Success Enrollment, Merchant Fetch.
E003	Invalid Request Token	Digital Signature in the token is not matching
E007	Technical Validation Failed	Technical invalid request to the API. Please check response Description for further details.
E001	Invalid IP Address	IP address from NPI API is not whitelisted
E010	Merchant Not Found	The record of the merchant is not found
B106	Invalid Acquirer	Acquirer does not exist