4. Integration
4.1.Integration Overview
NPI Billers' UI offers three landing pages: All Billers, Biller Group, and Biller Form. The choice of which landing page to use depends on the specific requirements of the third-party application.
base_url:https://uat.connectips.com:7443/billers
4.2. Landing pages
4.2.1. All billers:
This landing page displays all the biller icons enabled for the third-party. URL: {base_url}/billers?landing_page=”biller-all”
4.2.2. Biller group:
This landing page displays all the biller icons enabled for the group. URL: {base_url}/billers?landing_page=”biller_group”&biller_group=Internet
4.2.3. Biller form:
This landing page displays biller form. URL: {base_url}/billers? landing_page=”biller_form”&biller_code=24
4.3. Query parameters
| Parameter | Mandatory | Default | Description |
|---|---|---|---|
| participant_code | Yes | The third-party participant code. | |
| landing_page | Yes | Specifies the desired landing page. Available options: 'biller-all', 'biller_group', and 'biller_form'. | |
| biller_group | Required if landing_page='biller_group' | Sets the biller group for the selected landing page. | |
| biller_code | Required if landing_page='biller_form' | Sets the respective biller code to display its form. | |
| token | Yes | See token generation | |
| channel | Yes | Defines the app platform: use 'mob' for mobile apps and 'web' for web apps. | |
| lang | No | en | Language for NPI Billers. Currently supports English ('en') and Nepali ('ne'). |
| display_mode | No | light | Sets the display mode, either 'light' or 'dark'. |
| os | Required if channel='mob' | Specifies the mobile OS: use 'android' for Android and 'ios' for iOS. | |
| session_id | Yes | Format: <participant_code>_<uuid>. A unique id used to identify the NPI Billers session. | |
| display_error | No | toast | Defines the error message display UI. Options: 'toast', 'embedded', or 'host_app'. |
| web_type | Optional, set if channel='web' | iframe | Defines the integration type for web apps. Set “iframe” for iframe integration. |
4.4.Token generation
JWT Payload should be valid JSON.
{
"participant_code": ”himalayan”,
“session_id”: “himalayan_4e20a191-753d-4efa-90bf-f4f538d8a4ba”,
“channel”: “web”
}
“participant_code”, “session_id”, and “channel” must match with corresponding query param “participant_code”, “session_id”, and “channel”. The JWT must be both signed (JWS) then encrypted (JWE). Please follow the steps mentioned here
4.5.Error Codes
| Error Code | Description |
|---|---|
| 600 | Session expired. |
| 601 | Session already created. Please create new session_id. |
| 700 | Missing query param ‘token’. |
| 701 | Missing query param ‘channel’. |
| 704 | Missing query param ‘os’. |
| 705 | Missing query param ‘session_id’. |
| 706 | Missing query param ‘participant_code’. |
| 707 | Missing query param ‘landing_page’. |
| 708 | Missing query param ‘biller_group’. |
| 709 | Missing query param ‘biller_code’. |
| 800 | ‘token’ validation failed. |
| 801 | Invalid query param ‘channel’. |
| 802 | Invalid query param ‘language’. |
| 803 | Invalid query param ‘display_mode’. |
| 804 | Invalid query param ‘os’. |
| 805 | Invalid “session_id”. “session_id” must be in <participant_code>_<uuid> format. |
| 806 | ‘participant_code’ validation failed. |
| 807 | Invalid query param ‘landing_page’. |
| 808 | ‘biller_group’ validation failed. |
| 809 | ‘biller_code’ validation failed. |
| 900 | “participant_code” mismatch between query param “participant_code” and “token” payload. |
| 901 | “session_id” mismatch between query param “session_id” and “token” payload. |
| 902 | “channel” mismatch between query param “channel” and “token” payload. |
| 100 | Exception occurred on our end. Please contact us. |
4.6. NPI Billers Messages
NPI Billers interacts with the host application by sending messages at various stages of the bill payment process. These messages include information such as errors, form payloads, and other relevant updates to facilitate smooth communication. 4.6.1. NPI Billers Message Format All messages are sent in following format.
{
"session_id": "himalayan_4e20a191-753d-4efa-90bf-f4f538d8a4ba",
"type": "submit_form_payload",
"data": “xxxxx”
}
session_id: String session_id value sent by the host application during the NPI Billers initialization. type: String
Message type. See message types
data: String | Object | null
Actual payload for the message. Data type can be different as type.
4.6.2. NPI Billers Message Types
| Message Type | Data | Description |
|---|---|---|
| submit_form_payload | data field contains npiObject | This message is triggered once the user confirms the transaction. The host app should then proceed to authorize the transaction using either a transaction PIN or biometric verification. Upon successful authorization, the app backend should invoke the NPI to post the payment. |
| session_expire | null | This message is triggered when NPI Billers session is expired. The host app should handle reinitialization of NPI Billers by creating and passing a new session_id. It depends on the third-party requirements. |
| error | type:error message: “” | This message is triggered when NPI Billers throws an error and display_error=”host_app”. The host app should display the error received. |
4.6.3. NPI object (npiObject)
npiObject is signed (JWS) then encrypted (JWE). Please follow the steps mentioned here for decryption and signature verification.
{
"cipsBatchDetail": {
"id": 2576,
"batchId": "bilbatch-2576",
"recDate": null,
"batchAmount": 100,
"batchCount": 1,
"batchChargeAmount": null,
"batchCrncy": "NPR",
"categoryPurpose": "ECPG",
"debtorAgent": "",
"debtorBranch": "",
"debtorName": "",
"debtorAccount": "",
"debtorAddress": null,
"debtorMobile": null,
"debtorEmail": null,
"channelId": null,
"rcreTime": null,
"rcreUserId": null,
"corporateId": null,
"initBranchId": null,
"debitAcid": "",
"batchFreeText1": "",
"batchFreeText2": "",
"batchFreeText3": "",
"batchFreeText4": ""
},
"cipsTransactionDetail": {
"id": 92,
"batchId": 0,
"recDate": "2025-01-09T06:40:17.230+00:00",
"amount": 100,
"chargeAmount": 0,
"chargeLiability": "CG",
"appTxnId": "12729664",
"merchantId": 120,
"appId": "NIMB-NTC-APP-1",
"appGroup": null,
"instructionId": "RT-2571",
"endToEndId": "9843578426",
"creditorAddress": null,
"creditorMobile": null,
"creditorEmail": null,
"creditorIdType": "",
"creditorIdValue": "",
"refId": "9843578426",
"remarks": "Nepal Telecom - PrePaid",
"particulars": "",
"addenda1": null,
"addenda2": null,
"addenda3": "",
"addenda4": "",
"freeCode1": "",
"freeCode2": "",
"freeText1": "",
"freeText2": "",
"freeText3": "",
"freeText4": "",
"freeText5": "",
"freeText6": "",
"freeText7": "",
"freeNum1": null,
"freeNum2": null,
"freeNum3": null,
"freeNum4": null,
"txnResponse": null,
"beneficiaryId": "",
"beneficiaryName": "",
"mode": 1,
"favTxnFlg": null,
"rcreUserId": "BILLER@999",
"rcreTime": "2025-01-09",
"orignBranchId": null,
"creditAcid": null,
"token": null,
"accountValidationMsg": null,
"freeString": null,
"debitBankLogo": null,
"creditBankLogo": null,
"system": null,
"responseResult": null,
"data": null,
"status": null,
"billValidatonTraceId": null
},
"fieldLabelMapping": [
{
"fieldName": "amount",
"fieldLabel": "Transaction Amount",
"mapField": "amount"
},
{
"fieldName": "refId",
"fieldLabel": "Mobile Number",
"mapField": "refId"
}
]
}
4.7.Payment confirm posting
After successful user authorization for the transaction, the third-party app backend posts the payment using the NPI /api/npibiller/confirmbillerpay.do API. The third-party app backend will receive the partial request payload which is NPI Object from NPI Billers. The third-party app backend creates new request payload by combining NPI Object, debit information, and token.
Base URL: Please reach out to NCHL team for the NPI API base URL
Post URL: /api/npibiller/confirmbillerpay.do
4.7.1. Payment confirm Request
Create request payload by combining NPI Object, debit information, and token.
{
"cipsBatchDetail": {},
"cipsTransactionDetail": {},
"token":"xxxxxxxxxxxxxxxxxx”
}
1) Copy cipsTransactionDetail from NPI Object
2) Copy cipsBatchDetail from NPI Object and set debit information
3) Generate token
4) Create final object as above format.
Batch Details
| # | Field Name | Data Type | Length | Presence | Description |
|---|---|---|---|---|---|
| 1 | batchId | String | 20 | Y | Unique Identification for the batch for later reconciliation. |
| 2 | batchAmount | BigDecimal | 14,2 | Y | The total sum of amount of all the transactions in the batch. |
| 4 | batchCount | Integer | - | Y | Total transactions in the batch. |
| 5 | batchCrncy | String | 3 | Y | Currency of the transaction. E.g. NPR |
| 6 | categoryPurpose | String | 4 | Y | Purpose of the transaction. E.g. RTPS, ECPG |
| 7 | debtorAgent | String | 4 | Y | Financial institution where the transactions initiating party account is held. |
| 8 | debtorBranch | String | 4 | Y | Financial institution branch where the transactions initiating party account is held. |
| 9 | debtorName | String | 140 | Y | Transaction initiation party account name. |
| 10 | debtorAccount | String | 20 | Y | Transaction initiation party account number. |
| 11 | debtorIdType | String | 4 | O | Transaction initiation party private ID type (e.g., Citizenship, PAN No., Passport, etc.). |
| 12 | debtorIdValue | String | 20 | O | Transactions initiation party identification number (e.g., Passport number, PAN No., etc.). |
| 13 | debtorAddress | String | 490 | O | Transactions initiation party postal address. |
| 14 | debtorPhone | String | 20 | O | Transactions initiation party debtor phone number. |
| 15 | debtorMobile | String | 20 | O | Transactions initiation party mobile number. |
| 16 | debtorEmail | String | 50 | O | Transactions initiation party email address. |
Sample Request Parameters:
{
"cipsBatchDetail": {
"id": 2576,
"batchId": "bilbatch-2576",
"recDate": null,
"batchAmount": 100,
"batchCount": 1,
"batchChargeAmount": null,
"batchCrncy": "NPR",
"categoryPurpose": "ECPG",
"debtorAgent": "4501",
"debtorBranch": "1",
"debtorName": "anil paudel",
"debtorAccount": "0060119198000014",
"debtorAddress": null,
"debtorMobile": null,
"debtorEmail": null,
"channelId": null,
"rcreTime": null,
"rcreUserId": null,
"corporateId": null,
"initBranchId": null,
"debitAcid": "",
"batchFreeText1": "",
"batchFreeText2": "",
"batchFreeText3": "",
"batchFreeText4": ""
},
"cipsTransactionDetail": {
"id": 92,
"batchId": 0,
"recDate": "2025-01-09T06:40:17.230+00:00",
"amount": 100,
"chargeAmount": 0,
"chargeLiability": "CG",
"appTxnId": "12729664",
"merchantId": 120,
"appId": "NIMB-NTC-APP-1",
"appGroup": null,
"instructionId": "RT-2571",
"endToEndId": "9843578426",
"creditorAddress": null,
"creditorMobile": null,
"creditorEmail": null,
"creditorIdType": "",
"creditorIdValue": "",
"refId": "9843578426",
"remarks": "Nepal Telecom - PrePaid",
"particulars": "",
"addenda1": null,
"addenda2": null,
"addenda3": "",
"addenda4": "",
"freeCode1": "",
"freeCode2": "",
"freeText1": "",
"freeText2": "",
"freeText3": "",
"freeText4": "",
"freeText5": "",
"freeText6": "",
"freeText7": "",
"freeNum1": null,
"freeNum2": null,
"freeNum3": null,
"freeNum4": null,
"txnResponse": null,
"beneficiaryId": "",
"beneficiaryName": "",
"mode": 1,
"favTxnFlg": null,
"rcreUserId": "BILLER@999",
"rcreTime": "2025-01-09",
"orignBranchId": null,
"creditAcid": null,
"token": null,
"accountValidationMsg": null,
"freeString": null,
"debitBankLogo": null,
"creditBankLogo": null,
"system": null,
"responseResult": null,
"data": null,
"status": null,
"billValidatonTraceId": null
},
"token": "xxxxxxxxxxxxx"
}
4.7.2. Payment confirm token generation
The token string is the combination of batch and transactions information and following will be the format.
BatchString=<BatchId>+","+<DebtorAgent>+","+<DebtorBranch>+","+<DebtorAccount>+","+<BatchAmount>+","+<Batch Currency (e.g. NPR)>
For each transaction
Transaction String=<Id>+","+<Instruction Id>+","+<End to EndId>+","+<App Id>+","+<Ref Id>+","+<Amount>
Token String=Batch String + "," + Transaction String+","+<userId>
Sign the token string using the digital certificate private key(pfx file/keystore).The digital signature algorithm will be the SHA256withRSA. Please note that private key used here is for NPI which is different than NPI Billers.
Convert the signed token above in step 2 to base64 encoding.
Pass this signature string to the “token” field of the request message.
4.7.3. Payment confirm Response
Sample Response Parameters:
{
"responseResult":{
"responseCode":"000",
"responseDescription":"SUCCESS",
"fieldErrors":[
]
},
"cipsBatchDetail":{
"id":712532255,
"batchId":"T13-12818780108",
"recDate":"2021-02-04T16:47:53.967+0000",
"channelId":"TECHM",
"ipsBatchId":null,
"fileName":null,
"batchAmount":1000,
"batchCount":1,
"batchChargeAmount":2.00,
"batchCrncy":"NPR",
"categoryPurpose":"ECPG",
"debtorAgent":"2601",
"debtorBranch":"1",
"debtorName":"PUSPA RAJ UPADHAYA",
"debtorAccount":"1234567812",
"debtorIdType":null,
"debtorIdValue":null,
"debtorAddress":null,
"debtorPhone":null,
"debtorMobile":null,
"debtorEmail":null,
"rcreUserId":"KHALTI@999",
"rcreTime":"2021-02-04T16:47:53.967+0000",
"debitStatus":"000",
"debitReasonCode":null,
"isoTxnId":435656,
"sessionSrlNo":null,
"settlementDate":null,
"corporateId":3,
"initBranchId":null,
"debitReasonDesc":null,
"txnResponse":null
},
"cipsTransactionDetail":{
"id":12816806,
"recDate":"2021-02-04T16:47:53.967+0000",
"instructionId":"T13-12818780108-1",
"endToEndId":"188759/314043524",
"amount":1000,
"chargeAmount":2.00,
"chargeLiability":"CG",
"purpose":null,
"creditorAgent":"0201",
"creditorBranch":"100",
"creditorName":"REVENUE FCGO TSA",
"creditorAccount":"1234567868",
"creditorIdType":null,
"creditorIdValue":null,
"creditorAddress":null,
"creditorPhone":null,
"creditorMobile":null,
"creditorEmail":null,
"addenda1":null,
"addenda2":null,
"addenda3":null,
"addenda4":null,
"freeCode1":"7778",
"freeCode2":null,
"freeText1":null,
"freeText2":null,
"rcreUserId":"KHALTI@999",
"rcreTime":"2021-02-04T16:47:53.967+0000",
"ipsBatchId":null,
"creditStatus":"000",
"reasonCode":null,
"refId":"187145/314043524",
"remarks":"Used for other purpose",
"particulars":"DIPAK SHRESTHA",
"merchantId":7,
"appId":"MER-7-APP-4",
"appTxnId":"2077-4155863",
"reversalStatus":null,
"isoTxnId":435656,
"batchId":712532255,
"orignBranchId":"100",
"reasonDesc":null,
"txnResponse":null
}
}
Note: For the successful payment, please consider the debit (000) and credit status (000, DEFER,999) in above response message and handle the response code as per NPI specification document.