5. API Specifications

5.1. API Security Guidelines for NPI Integration

The National Payment Interface APIs are secured through the following best practices to reinforce the industry security standard:

• Token-based Access Control
• Digital Signature

5.1.1 Token-based Access Control

The primary API authentication method is OAuth2 framework using Access Tokens. The OAuth 2.0 authorization framework is a protocol that allows a third-party application access to the protected resources, without necessarily revealing their long-term credentials or even their identity. The client needs to provide client specific credentials (Basic authentication) in the authorization header and user credentials (User authentication) in the body with grant type as password for refresh and access token pair generation on the first stage or during refresh token expiration.

⚠️These tokens contain API access privileges, they must be kept secretly.

API Authorization:

The generated access token by one of the above methods can be used to access the available resources. This can be done by setting the Authorization HTTP Header value as Bearer [access token].

The default expiration time for the access token is 300 seconds, and for the refresh token, it is 12 hours.

A dynamic method for retrieving new tokens is to be applied. For example, if the access token expires or is invalid, you will receive a 401 Unauthorized response. If the refresh token is expired or invalid, you will receive a 400 Bad Request response.

Auth API Endpoints:

We provide one primary API endpoint to obtain the access token. This endpoint supports two Authorization Grant methods:

URL	Grant Type	Description
/oauth/token	password	Retrieve Access Token and Refresh Token using the provided API username/password and client credentials.
/oauth/token	refresh_token	Retrieve Access Token using the corresponding Refresh Token only.

Method to generate & use access and refresh token:

1. Use the provided basic authentication credentials along with the API username/password and set the grant type as password to obtain a refresh token. The refresh token will have a longer validity period (e.g., 12 hours), so store it for future access token retrieval. It is strictly prohibited to use access token obtained during this initial request.
2. Use the stored refresh token from step #1 to generate a new access token, setting the grant type as refresh_token and using basic authentication credentials only. Access tokens are valid for a short period (e.g., 300 seconds). Use this access token to make resource requests within this time. Once the access token expires, re-request a new access token using the stored refresh token.
3. When the refresh token expires, repeat the process from step 1.
4. Pass the new access token as a Bearer Token in the Authorization header when accessing API resources.
5. Token renewal can generally be based on the expiry time of both the access token (e.g., after 300 seconds) and refresh token (e.g., after 12 hours). However, relying solely on fixed expiry times for token renewal is insufficient due to time gaps between the expiry and renewal and for seamless API access. Instead, you should initiate the renewal process based on the API’s response codes, which can indicate that the tokens are no longer valid.
6. When the access token has expired or is invalid, the API will return a 401 Unauthorized response. In this case, immediately use the stored refresh token (from step #1 above) to obtain a new access token.
7. If the refresh token itself has expired, it must be renewed before you can obtain a new access token. Attempting to use an expired or invalid refresh token will result in a 400 Bad Request response. In such cases, renew the refresh token first (step #1 above) before proceeding with the access token request (step #2 above).

POST URL For Authentication:/oauth/token

5.2. Digital Signature

Message/token signing in NPI integration is a crucial security mechanism that involves adding a unique digital signature token to each request and response payload, ensuring the authenticity, non-repudiation and integrity of the transmitted data. This process relies on cryptographic algorithms and shared keys to generate and verify these signatures, preventing unauthorized access, data tampering, and enhancing trust between NPI and its members.

A signature token is generated taking the financial information from the request & response payload. The token is further digitally signed by the client’s private key (pfx) using SHA256withRSA algorithm. The resulting signed token is encoded in base 64 format and include in “token” tag within request and response payloads.

Below is the high level proces flow for creating and requesting the digital certificate for the message signing purpose.

Step 1: Create Keystore and Generate CSR file:

keytool -genkey -keysize 2048 -keyalg RSA -sigalg SHA256withRSA -alias TEST -keystore TEST.jks

Enter keystore password: yourpassword
Re-enter new password: yourpassword
What is your first and last name: TEST
What is the name of your organizational unit: TEST
What is the name of your organization: TEST
What is the name of your city or locality: Kathmandu
What is the name of your state of province: Bagmati
What is the two-letter country code for this unit: NP
Is CN= TEST TEST, OU= TEST, O=TEST, L=Kathmandu,ST=Kathmandu, C=NP correct? yes
Enter key password for <TEST>: yourpassword   
Re-enter new password: yourpassword

keytool -certreq -alias TEST -keyalg RSA -file TEST.csr -sigalg SHA256withRSA -keystore TEST.jks

Step 2: Check that a Keystore was created

keytool -list -v -keystore TEST.jks -alias TEST
Enter keystore password:

Note:

- PLEASE SHARE THE GENERATED .csr FILE TO NCHL AFTER THIS 2ND STEP!!!
- Continue below steps after receiving TEST.cer file from NCHL. This TEST.cer file is used for signature verification of request payload sent by NCHL for NPI.

Step 3: Import .cer and NCHL root and issuer CA to keystore (NCHL root/issuer CA are attached herewith)

keytool -importcert -keystore TEST.jks -alias nchlrootca -file nchlrootca_2022.crt
keytool -importcert -keystore TEST.jks -alias nchlissuerca -file nchlissuerca_2022.crt
keytool -importcert -keystore TEST.jks -alias TEST -file TEST.cer

## <BASEURL>.cer is the SSL certificate. A different SSL certificate will be provided by NCHL.
## not required for testing

keytool -importcert -keystore TEST.jks -alias <BASEURL> -file <BASEURL>.cer

Step 4: Convert keystore to PFX file.

keytool -importkeystore -srckeystore TEST.jks –destkeystore TEST.p12 -deststoretype PKCS12 –srcalias TEST -srcstorepass *** -deststorepass *** -destkeypass ***
keytool -v -importkeystore -srckeystore TEST.jks -srcalias TEST -destkeystore TEST.p12 -deststoretype PKCS12
openssl pkcs12 -in TEST.p12 -nocerts -out TEST.pem -nodes
openssl pkcs12 -export -in TEST.pem -inkey TEST.pem -out keystore.p12 -name your_alias -CAfile ca-chain.pem -caname root

###Use this .p12 file (Convert it to .pfx) for signature generation.

Note: Upon expiry of the certificate , repeat the same process of the certificate generation.

5.3. Account Validation

Account validation is used for validating creditor account before initiating the actual transaction. Validating creditor account beforehand reduces the transactions rejection ratio. After the account is validated the actual financial transactions APIs are required to be called. It validates the existence of the account, status and account name match details. This section describes the required information for account validation through NPI.

POST URL: /api/validatebankaccount

Request Parameter:

#	Field Name	Data Type	Length	Description	Presence
1	bankId	String	4	Assigned bank id	Y
2	accountId	String	20	Bank account number.	Y
3	accountName	String	140	Bank Account name.	Y

Response Parameter:

#	Field Name	Data Type	Length	Description	Presence
1	bankId	String	4	Customer bank id	Y
2	branchId	String	4	Actual branch id.	Y
3	accountId	String	20	Bank account number.	Y
4	accountName	String	140	Bank account name.	C
5	currency	String	3	Bank account currency.	Y
6	responseCode	String	4	Response Code.	Y
7	responseMessage	String	140	Response Message.	Y
8	matchPercentage	Integer	3	Match percentage.	Y
9	baseUrl	String	100	Base Url	C
10	username	String	20	User name.	c
11	password	String	20	User password	C

Excepted Status Codes:

BadRequest

InternalServerError

NotFound

Request Message Example:

{
"bankId":"0401",
"accountId" : "08110017501011",
"accountName" : "MANISHA DHAUBANJAR"
}

Sample response example:

{
 "bankId": "0401",
 "branchId": "81",
 "accountId": "08********4512",
 "accountName": null,
 "currency": "NPR",
 "responseCode": "000",
 "responseMessage": "Account successfully validated.",
 "matchPercentate": 100,
 "baseUrl": null,
 "userName": null,
 "password": null
}

Sample response example I:

{
 "bankId": "0401",
 "branchId": "81",
 "accountId": "08********4512",
 "accountName": null,
 "currency": "NPR",
 "responseCode": "999",
 "responseMessage": "Some difference in beneficiary account name observed. Transaction once sent isirreversible, please reconfirm the beneficiary account number.",
 "matchPercentate": 94,
 "baseUrl": null,
 "userName": null,
 "password": null
}

Sample response example II:

{
 "bankId": "0401",
 "branchId": "81",
 "accountId": "28*******1564"
 "accountName": null,
 "currency": "NPR",
 "responseCode": "523",
 "responseMessage": "Beneficiary account name mismatch.",
 "matchPercentate": 40,
 "baseUrl": null,
 "userName": null,
 "password": null
}

Explanation on Response Codes:

#	Response Code	Description	Remarks
1	000	Account successfully validated. Account 100% Match.	Process the transaction to NPI.
2	999	Some difference in beneficiary account name observed. Refer the account name percentage (match Percentage) in response.	If the match percentage is > 80, process the transaction to NPI. Otherwise stop the transaction for further processing.
3	Not (000 & 999)	Issue with the beneficiary account. Please refer the response message.	Stop the transaction for further processing to NPI.

5.4. Transaction APIs

NPI supports real time and non-real time transactions. Both the debit and credit legs are completed in a single session in real time transaction. Whereas, in non-real time transaction, debit leg is completed in real-time but credit leg(s) are completed on deferred basis. Following are the API details of the transactions supported in NPI.

5.4.1. Real Time Transactions (postcipsbatch)

This API is used for posting fund transfer transaction in connectIPS e-Payment system in real time basis. Since the nature of transaction is real time, the postcipsbatch method can contain only single transaction in a batch. The execution of both debit and credit legs happens in a real time and provides the response accordingly within a single session. Below is the process flow diagram for the postcipsbatch method.

Process Flow:

Initiating participant will push the transactions to NPI. Such transaction can be only one-to-one.
NPI will then perform its technical validations. And then forward the request to the core switch system.
connectIPS system will send a debit request to debtor bank. Debit authorization by the member shall be provided to its bank as the part of the initial enrollment.
NPI receives the ISO response from the debtor bank. The debit status with code 000 will be treated as debit success and for rest of the status, it will be treated as debit rejected/failed.
Based on the success debit response, the connectIPS system will route the transactions to the creditor bank for crediting the beneficiary account.
NPI receives the ISO response from the creditor bank. The credit status with ISO status code as 000, 999, null or DEFER are treated as success. Status 000: Credit success Status 999: Credit ISO time out where it is not sure whether the account has been credited or not, which requires the manual reconciliation from creditor bank. Once it is verified from the bank, the status will be updated to 000 or Failed (which requires transaction refunding to the initiating bank). Status DEFER: As per the business requirement for some of the Creditor/ Merchant payments. Note: For both 999 and DEFER, the final status can be fetched using the transaction reporting API as listed below. (Collections having high volume), instead of individual transaction credit, consolidation credit is initiated as a single ISO message on an intermittence basis. Frequency of such consolidation can be configurable (which is currently setup as twice a day at 11:45 AM and 14:45 PM). Once the credit is successful at the creditor bank, the transaction status will be updated as 000.

Example Image

Transaction status (both credit and debit) are sent back to the NPI.
Initiating participant can fetch the transaction details using transaction reporting API at any point of time.

POST URL: /api/postcipsbatch

Following points should be consider while posting the transactions through postcipsbatch.

Both debtor and creditor bank should be the member of connectIPS e-Payment system.
Postcipsbatch supports both On-Us (same bank) and Off-Us (interbank) transactions.
On-Us and Off-Us transactions are to be sent in different batches.
Sender will have to ensure that the channel specific transaction limits (as per NRB) is complied with. The current per transaction limit for postcipsbatch is 2 million for Off-Us transactions (interbank as per transaction limit of connectIPS) and 200 Million for On-Us transactions (same bank as per transaction limit of NCHL-IPS).
The transactions per batch limit will be 1.
Allowed category purpose for postcipsbatch is ECPG.

Request Parameters:

The request parameters for this method are created to align the format of ISO 20022 message format which is currently being used in NCHL-IPS system. Hence the payment information is segregated as batch and transaction details.

Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	batchId	String	20	Unique Identification for the batch for later reconciliation.	Y
2	batchAmount	BigDecimal	14,2	The total sum up amount of all the transactions in the batch	Y
3	batchCount	Integer	-	Total transactions in the batch	Y
4	batchCrncy	String	3	Currency of the transaction. E.g. NPR	Y
5	categoryPurpose	String	4	Purpose of the transaction. E.g. RTPS, ECPG	Y
6	debtorAgent	String	4	Financial institution where the transactions initiating party account is held.	Y
7	debtorBranch	String	4	Financial institution branch where the transactions initiating party account is held.	Y
8	debtorName	String	140	Transaction initiation party account name.	Y
9	debtorAccount	String	20	Transaction initiation party account number.	Y
10	debtorIdType	String	4	Transaction initiation party private id type for ex. Citizenship, pan no, passport etc.	O
11	debtorIdValue	String	20	Transactions initiation party identification number for ex. Passport number, pan no. etc.	O
12	debtorAddress	String	490	Transactions initiation party postal address	O
13	debtorPhone	String	20	Transactions initiation party debtor phone number+<country code>-<area code>-<Phone Number>	O
14	debtorMobile	String	20	Transactions initiation party mobile number	O
15	debtorEmail	String	50	Transactions initiation party email address.	O

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	instructionId	String	30	Unique identification for the transaction for reconciliation purpose later.	Y
2	endToEndId	String	30	Identification reference for both sender and receiver.	Y
3	amount	BigDecimal	13,2	The amount to be transferred through this transaction.	Y
4	purpose	String	4	The initiating party will assign the purpose of the transactions. List of purpose category is available in the product document.	O
5	creditorAgent	String	4	Financial institution where the receiving party's accounts are held.	Y
6	creditorBranch	String	4	Financial institution branch where the receiving party's account is held.	Y
7	creditorName	String	140	Receiving party Account name.	Y
8	creditorAccount	String	20	Receiving party account number.	Y
9	creditorIdType	String	4	Receiving party private identification type (e.g., Citizenship, PAN no, passport, etc.).	O
10	creditorIdValue	String	20	Receiving party identification value.	O
11	creditorAddress	String	490	Receiving party postal address.	O
12	creditorPhone	String	20	Receiving party phone number in the format +<country code>-<area code>-<Phone Number>.	O
13	creditorMobile	String	20	Receiving party mobile number in the format +<country code>-<area code>-<Phone Number>.	O
14	creditorEmail	String	50	Receiving party valid email address.	O
15	addenda1	Integer	15	Information that is used to provide the extra information about the transaction. The value can be set as mandatory as per configuration of category purpose.	C
16	addenda2	Date			C
17	addenda3	String	35		C
18	addenda4	String	35		C
19	freeCode1	String	20	Extra information that can be appended to the transactions to be more specific about the purpose of transactions for reconciliation purpose. These fields will be significant only up to the initiating party bank and will not be routed to the beneficiary bank.	O
20	freeCode2	String	20		O
21	freeText1	String	100		O
22	freeText2	String	100		O
23	remarks	String	100	Remarks field	O

Token Generation Process:

1. Token string generation The token string is created by appending the financial fields in batch and transactions information. Following will be the procedure for token string generation:

Batch String= <BatchId>+","+<DebtorAgent>+","+<DebtorBranch>+","+<DebtorAccount>+","+<BatchAmount>+","+<Batch Currency (e.g. NPR)>

Transaction String=<Instruction Id>+","<Creditor Agent>+","+<CreditorBranch>+",+<CreditorAccount> +","+<Transaction Amount>; 

Token String=Batch String + Transaction String+","+<user Id>

2. Sign the message token from step 1 using the digital certificate private key (pfx file/keystore). The digital signature algorithm will be the SHA256withRSA.
3. Convert the signed token above in step 2 to base64 encoding.
4. Pass this signature string to the “token” field of the request message.

Expected Status Codes: OK

BadRequest

InternalServerError

NotFound

Forbidden

Request Message Example:

{
  "cipsBatchDetail": {
    "batchId": "KHA-198706",
    "batchAmount": 200.25,
    "batchCount": 1,
    "batchCrncy": "NPR",
    "categoryPurpose": "ECPG",
    "debtorAgent": "1701",
    "debtorBranch": "1",
    "debtorName": "Test Technical Member",
  "debtorAccount": "0010********0018",
    "debtorIdType": "0001",
    "debtorIdValue": "123456",
    "debtorAddress": "Kathmandu Nepal",
    "debtorPhone": "+977-01-425****",
    "debtorMobile": "+977-98********",
    "debtorEmail": "test@test.com"
  },
  "cipsTransactionDetailList": [
    {
      "instructionId": "KHA-198706-1",
      "endToEndId": "Payment Description",
      "amount": 200.25,
      "creditorAgent": "9935",
      "creditorBranch": "1",
      "creditorName": "Rojan Nepal",
         "creditorAccount":"0010*******374",
      "creditorIdType": "0001",
      "creditorIdValue": "5689755562",
      "creditorAddress": "Bhaktapur Nepal",
      "creditorPhone": "+977-01-66*****",
      "creditorMobile": "+977-98********",
      "creditorEmail": "creditor1@test.com.np",
      "addenda1": 8965,
      "addenda2": "2018-09-10",
      "addenda3": "Addenda info3",
      "addenda4": "Addenda info4"
    }
  ],
  "token": "D1xAD6zEHvRpAbd6rUUekdAPpc+RvGnaL8bKbKUf9MVKrjrr8zZN2JLer87PM5s0UVlYXh7KvUW8s0GwjAlPTmZkDWr3dIHlwVZqVOCqf23Ji13BjqhrAtwxPOq9Bjtbb3Pe+l4dcuSj6RZiBv7SoVkYV0a4BkiGORL8U7lAv62Vi/00pFEDcfibqvtAluRzoDsboJh3+n0tmxai68+UOzPLKPQ0ofg7cgoTR3xUYVX8kdkR9FkSRM+os5DIbB1WN21spAo23sRhxS6GX4AYABhYYmwp7+aTAbgc0C4VR6epyIfGYKigjmRRXsnVFyevsbBatLiKgh9u5Kd/1kzY9w=="
}

Response Parameters

Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	responseCode	String	-	Debit transaction processing API response. For example, 000 for success, 1001 for bank not reachable, 999 for debit timeout, and so on. (Refer section 6 below)	Y
2	responseMessage	String	500	Debit status description.	Y
3	batchId	String	20	Unique Identification for the batch for later reconciliation. (Generated by the NPI member)	Y
4	debitStatus	String	10	Debit status (000 for success, 999 for timeout and so on) (Refer ISO return reason sheet).	Y
5	id	Integer	-	Unique Identification for the batch generated in NCHL side.	Y

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	responseCode	String	-	Credit transaction processing API response. For example, 000 for success, 1001 for bank not reachable, 999 for debit timeout, and so on. (Refer section 6 below)	Y
2	responseMessage	String	500	Credit status description.	Y
3	instructionId	String	20	Unique Identification for the transaction for later reconciliation. (Generated by the NPI member)	Y
4	creditStatus	String	10	Credit status (ACSP for success, RJCT for Rejected and so on) (Refer ISO return reason sheet).	Y
5	id	Integer	-	Unique Identification for the transaction generated in NCHL side.	Y

Response Example:

{
  "cipsBatchResponse": {
    "responseCode": "000",
    "responseMessage": "SUCCESS",
    "batchId": " KHA-198706",
    "debitStatus": "000",
    "id": 42
  },
  "cipsTxnResponseList": [
    {
      "responseCode": "000",
      "responseMessage": " SUCCESS",
      "id": 36,
      "instructionId": "KHA-198706-1",
      "creditStatus": "000"
    }
  ]
}

5.4.2. Non-Real Time Transactions (postnchlipsbatch)

This postipsbatch is used for posting non-real time fund transfer transactions through NCHL-IPS System. It handles both the cases of single transaction and batch-based credit transactions. However, the debit of the batch amount will be executed instantly. And once the debit is successful, transaction will be posted to NCHL-IPS system for credit legs by a batch process. Below is the process flow diagram for the postnchlipsbatch method.

Process Flow:

Example Image

Initiating participant will push the transactions to NPI. Such transaction could be one-to-one or batch based.
NPI will then perform its technical validations. And then forwards the request to the core switch system.
connectIPS system will send a debit request to debtor bank, which will be executed immediately based on the batch amount. Debit authorization by the member shall be provided to its bank as the part of the initial enrollment.
NPI receives the ISO response from the debtor bank. The debit status with code 000 will be treated as debit success and for rest of the status it will be treated as debit rejected/failed.
Based on the success debit response, a batch process will route the transactions to the creditor bank through NCHL-IPS system for crediting the beneficiary account.
connectIPS system syncs the transaction status with NCHL-IPS system. Once the transactions are routed to the NCHL-IPS system, there will be multiple credit status like GEN, SENT, ACTC, ACSP, ACSP and RJCT until the transaction is settled. ACSC and RJCT are the final status as credit accepted and rejected respectively.
Transaction status (both credit and debit) are sent back to NPI.
Initiating participant can fetch the transaction details using transaction reporting API at any point of time.
Beneficiary accounts will be credited once the bank Nostro settlement is competed at Nepal Rastra Bank. The number of settlements and timing will be as per the NCHL-IPS operating procedure (which are currently at 12:30 PM, 1:30 PM, 2:30 PM and 4:00 PM)

POST URL: /api/postnchlipsbatch

Following points should be consider while posting the transactions to postnchlipsbatch.

Debtor bank must be the member of connectIPS e-Payment system however creditor bank can be the member of NCHL-IPS system.
Postnchlipsbatch supports only the Off-Us (interbank) transactions.
The transaction count limit and transaction amount limit is as defined by NCHL-IPS system, which is based on the category purposes. Addenda information are also mandatory for some of the category purpose (refer to product note for details).
Number of transactions within a batch (batch limit) is 10,000.

Request Parameters:

Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	batchId	String	20	Unique Identification for the batch for later reconciliation.	Y
2	batchAmount	BigDecimal	14,2	The total sum up amount of all the transactions in the batch.	Y
3	batchCount	Integer	-	Total transactions in the batch.	Y
4	batchCrncy	String	3	Currency of the transaction. E.g., NPR	Y
5	categoryPurpose	String	4	Purpose of the transaction. E.g., RTPS, ECPG	Y
6	debtorAgent	String	4	Financial institution where the transactions initiating party account is held.	Y
7	debtorBranch	String	4	Financial institution branch where the transactions initiating party account is held.	Y
8	debtorName	String	140	Transaction initiation party account name.	Y
9	debtorAccount	String	20	Transaction initiation party account number.	Y
10	debtorIdType	String	4	Transaction initiation party private id type for ex. Citizenship, pan no, passport etc.	O
11	debtorIdValue	String	20	Transactions initiation party identification number for ex. Passport number, pan no. etc.	O
12	debtorAddress	String	490	Transactions initiation party postal address.	O
13	debtorPhone	String	20	Transactions initiation party debtor phone number +<country code>-<area code>-<Phone Number>	O
14	debtorMobile	String	20	Transactions initiation party mobile number +<country code>-<area code>-<Phone Number>	O
15	debtorEmail	String	50	Transactions initiation party email address.	O

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	instructionId	String	30	Unique identification for the transaction for reconciliation purpose later.	Y
2	endToEndId	String	30	Identification reference for both sender and receiver.	Y
3	amount	BigDecimal	13,2	The amount to be transferred through this transaction.	Y
4	purpose	String	4	The initiating party will assign purpose of the transactions. List of purpose category is available in product document.	O
5	creditorAgent	String	4	Financial institution where the receiving party accounts is held.	Y
6	creditorBranch	String	4	Financial institution branch where the receiving party account is held.	Y
7	creditorName	String	140	Receiving party Account name.	Y
8	creditorAccount	String	20	Receiving party account number.	Y
9	creditorIdType	String	4	Receiving party private identification type for ex. Citizenship, pan no, passport etc.	O
10	creditorIdValue	String	20	Receiving party identification value.	O
11	creditorAddress	String	490	Receiving party postal address.	O
12	creditorPhone	String	20	Receiving party phone number in the format +<country code>-<area code>-<Phone Number>.	O
13	creditorMobile	String	20	Receiving party mobile number in the format +<country code>-<area code>-<Phone Number>.	O
14	creditorEmail	String	50	Receiving party valid email address.	O
15	addenda1	Integer	15	Information that is used to provide the extra information about the transaction. The value can be set as mandatory as per configuration of category purpose. Extra information that can be append to the transactions to be more specific about the purpose of transactions for reconciliation purpose. These fields will significant only up to the initiating party bank and will not be routed to the beneficiary bank.	C
16	addenda2	Date	-		C
17	addenda3	String	35		C
18	addenda4	String	15		C
19	freeCode1	String	15		0
20	freeCode2	String	15		0
21	freeText1	String	15		0
22	freeText2	String	15		0

Token Generation Process:

1. Token string generation The token string is created by appending the financial fields in batch and transactions information. Following will be the procedure for token string generation:

Batch String=

Batch String: "<BatchId>,<DebtorAgent>,<DebtorBranch>,<DebtorAccount>,<BatchAmount>,<BatchCurrency>,<CategoryPurpose>

For each transaction

 Transaction String: "<Instruction Id>,<CreditorAgent>,<CreditorBranch>,<CreditorAccount>,<Transaction Amount> 

 Token String: <BatchString>,<TransactionString>,<userId>

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

Expected Status Codes:
OK
BadRequest
InternalServerError
NotFound
Forbidden

Request Message Example (Single Batch):

{
  "nchlIpsBatchDetail": {
    "batchId": "KHA-198706",
    "batchAmount": 200.25,
    "batchCount": 1,
    "batchCrncy": "NPR",
    "categoryPurpose": "CUST",
    "debtorAgent": "1701",
    "debtorBranch": "1",
    "debtorName": "Test Technical Member",
  "debtorAccount": "0010********0018",
    "debtorIdType": "0001",
    "debtorIdValue": "123456",
    "debtorAddress": "Kathmandu Nepal",
    "debtorPhone": "+977-01-425****",
    "debtorMobile": "+977-98********",
    "debtorEmail": "test@test.com"
  },
  "nchlIpsTransactionDetailList": [
    {
      "instructionId": " KHA-198706-1",
      "endToEndId": "Payment Description",
      "amount": 200.25,
      "creditorAgent": "9935",
      "creditorBranch": "1",
      "creditorName": "Rojan Nepal",
         "creditorAccount":"0010*******374",
      "creditorIdType": "0001",
      "creditorIdValue": "5689755562",
      "creditorAddress": "Bhaktapur Nepal",
      "creditorPhone": "+977-01-66*****",
      "creditorMobile": "+977-98********",
      "creditorEmail": "creditor1@test.com.np",
      "addenda1": 8965,
      "addenda2": "2018-09-10",
      "addenda3": "Addenda info3",
      "addenda4": "Addenda info4"
    }
  ],
  "token": "D1xAD6zEHvRpAbd6rUUekdAPpc+RvGnaL8bKbKUf9MVKrjrr8zZN2JLer87PM5s0UVlYXh7KvUW8s0GwjAlPTmZkDWr3dIHlwVZqVOCqf23Ji13BjqhrAtwxPOq9Bjtbb3Pe+l4dcuSj6RZiBv7SoVkYV0a4BkiGORL8U7lAv62Vi/00pFEDcfibqvtAluRzoDsboJh3+n0tmxai68+UOzPLKPQ0ofg7cgoTR3xUYVX8kdkR9FkSRM+os5DIbB1WN21spAo23sRhxS6GX4AYABhYYmwp7+aTAbgc0C4VR6epyIfGYKigjmRRXsnVFyevsbBatLiKgh9u5Kd/1kzY9w=="
}

Request Message Example (Multiple Batch):

{
   "nchlIpsBatchDetail":{
      "batchId":"TEST20250803",
      "batchAmount":20,
      "batchCount":2,
      "batchCrncy":"NPR",
      "categoryPurpose":"CUST",
      "debtorAgent":"2501",
      "debtorBranch":"1",
      "debtorName":"Ankit Neupane",
        "debtorAccount": "0010********0018",
      "debtorIdType":"0001",
      "debtorIdValue":"123456",
      "debtorAddress":"Kathmandu Nepal",
      "debtorPhone":"+977-01-425****",
      "debtorMobile":"+977-98********",
      "debtorEmail":"test@test.com"
   },
   "nchlIpsTransactionDetailList":[
      {
         "instructionId":"TEST20250803-1",
         "endToEndId":"TEST20250803-1",
         "amount":15,
         "creditorAgent":"4501",
         "creditorBranch":"23",
         "creditorName":"shreya karki",
         "creditorAccount":"0010*******374",
         "creditorIdValue":"5689755562",
         "creditorAddress":"Bhaktapur Nepal",
         "creditorPhone":"+977-01-665****",
         "creditorMobile":"+977-98********",
         "creditorEmail":"creditor1@gmail.com",
         "addenda1":"8965",
         "addenda2":2131
      },
      {
         "instructionId":"TEST20250803-2",
         "endToEndId":"TEST20250803-2",
         "amount":5,
         "creditorAgent":"4501",
         "creditorBranch":"23",
         "creditorName":"KESHAB G.C",
         "creditorAccount":"023011050000749",
         "creditorIdValue":"5689755562",
         "creditorAddress":"Bhaktapur Nepal",
         "creditorPhone":"+977-01-665****",
         "creditorMobile":"+977-98********",
         "creditorEmail":"creditor1@gmail.com",
         "addenda1":"8965",
         "addenda2":2131
      }
   ],
   "token":"Gq2F0hemhaE5tpFcASCaaUY7HTzFdMbp2JyaN6l8y7co9AjbX/KMNZVE8HKJiCZ9ShsrRxJUVbo45DCZIB2YuCXyVtcMZZ74j9JwGrq1NzkV7Hb9GOaesXFKXfpJqzuXebEKpm+ohbO1lVTB/hFPIFpW6vBpwI2N4gPTGyVO4yg="
}

Response Parameters

Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	responseCode	String	-	Debit transaction processing API response. For example, 000 for success, 1001 for bank not reachable, 999 for debit timeout, and so on. (Refer section 6 below)	Y
2	responseMessage	String	500	Debit status description.	Y
3	batchId	String	20	Unique Identification for the batch for later reconciliation. (Generated by the NPI member)	Y
4	debitStatus	String	10	Debit status (000 for success, 999 for timeout and so on). (Refer ISO return reason sheet)	Y
5	id	Integer	-	Unique Identification for the batch generated in NCHL side.	Y

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	responseCode	String	-	Credit transaction processing API response. For example, 000 for success, 1001 for bank not reachable, 999 for debit timeout, and so on. (Refer section 6 below)	Y
2	responseMessage	String	500	Credit status description.	Y
3	instructionId	String	20	Unique Identification for the transaction for later reconciliation. (Generated by the NPI member)	Y
4	creditStatus	String	10	Credit status (ACSP for success, RJCT for Rejected, and so on). (Refer ISO return reason sheet)	Y
5	id	Integer	-	Unique Identification for the transaction generated in NCHL side.	Y

Response Example:

{
  "cipsBatchResponse": {
    "responseCode": "000",
    "responseMessage": "SUCCESS",
    "batchId": " KHA-198706",
    "debitStatus": "000",
    "id": 42
  },
  "cipsTxnResponseList": [
    {
      "responseCode": "ENTR",
      "responseMessage": " PENDING FOR POSTING IN NCHL-IPS",
      "id": 36,
      "instructionId": "KHA-198706-1",
      "creditStatus": "ENTR"
    }
  ]
}

5.4.3. Aggregated Service APIs

These are related to the consolidated service APIs of the creditors including Government, SemiGovernment, large corporates and other creditors/merchants that are enrolled by the member BFIs of NCHL and then extended to the others for integrating in their channels.

Refer to the separate NPI Aggregated Service API document for further details.

5.5. Transaction Reporting APIs

For reporting and reconciliation of the transactions which are processed through NPI, the following APIs will be provided. These APIs will also require the access token to access the resources and the token generation process will be same as for the transaction processing.

Based on transactions date: These APIs provide the list of transaction details based on the provided date range.
/api/getcipstxnlistbydate --> For cips transactions.
/api/getnchlipstxnlistbydate --> For ips transactions.

Sample request message:

{ 
"txnDateFrom":"2018-11-01", 
"txnDateTo":"2018-12-06" 
} 

Based on batch Id: These APIs provide the transaction details based on the batch id

/api/getcipstxnlistbybatchid --> For cips transactions.
/api/getnchlipstxnlistbybatchid --> For ips transactions.

Sample request message:

{ 
"batchId":"123456" 
}

Based on Instruction Id: These APIs provide the transaction details based on the instruction id and batch id.
/api/getcipstxnbyinstructionid --> For cips transactions.
/api/getnchlipstxnlistbyinstructionid --> For ips transactions.

Sample request message:

{ 
"batchId":"123456", 
"instructionId":"instr-123456" 
} 

Sample Transaction Report Response: Below are the sample transaction responses generated using instruction id for both CIPS and NCHLIPS.

Response Parameters for CIPS transactions

Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	id	Integer	-	Unique Identification for the batch generated in NCHL side.	Y
2	batchId	String	20	Unique Identification for the batch sent by the NPI member used for reconciliation.	Y
3	recDate	Date	-	Date (YYYY-MM-DD)	Y
4	isoTxnId	Integer	-	CBS ISO reference id.	Y
5	batchAmount	BigDecimal	14,2	The total sum up amount of all the transactions in the batch.	Y
6	batchCount	Integer	-	Total transactions in the batch.	Y
7	batchChargeAmount	BigDecimal	12,2	Total charge to be paid for the transaction.	Y
8	batchCrncy	String	3	Currency of the transaction. E.g., NPR	Y
9	categoryPurpose	String	4	Purpose of the transaction. E.g., RTPS, ECPG	Y
10	debtorAgent	String	4	Debtor agent code in NCHL systems.	Y
11	debtorBranch	String	4	Debtor branch where the transactions initiating party account is held.	Y
12	debtorName	String	140	Transaction initiation party account name.	Y
13	debtorAccount	String	20	Transaction initiation party account number.	Y
14	debtorIdType	String	4	Transaction initiation party private id type for ex. Citizenship, pan no, passport etc.	O
15	debtorIdValue	String	20	Transactions initiation party identification number for ex. Passport number, pan no. etc.	O
16	debtorAddress	String	490	Transactions initiation party postal address.	O
17	debtorPhone	String	20	Transactions initiation party debtor phone number +<country code>-<area code>-<Phone Number>.	O
18	debtorMobile	String	20	Transactions initiation party mobile number +<country code>-<area code>-<Phone Number>.	O
19	debtorEmail	String	50	Debtor’s email address.	O
20	chhanelId	String	10	Specification of the channel used to perform the transaction; Technical member (TECHM), Web Fund Transfer (WEBFT) etc.	O
21	debitStatus	String	10	Response code for debit leg of the transaction.	Y
22	debitReasonCode	String	10	Response code returned by the debtor agent for debit leg of the transaction.	O
23	ipsBatchId	String	13	Unique ACH batch id generated by NCHL for ACH routing.	Y
24	fileName	String	100	ACH routing file name.	O
25	rcreTime	Date	-	Date with timestamp.	O
26	rcreUserId	String	50	Transaction creation id.	O
27	sessionSeq	String	20	ACH session sequence number.	Y
28	settlementDate	Date	-	ACH transaction settlement date.	Y
29	debitReasonDesc	String	200	Debit description. (If debit status is 000, debitReasonDesc is SUCCESS, if timeout 999, then TIMEOUT, PLEASE CONFIRM WITH BANK BEFORE RE-POSTING and so on.)	Y
30	txnResponse	String	335	Transaction reference number returned by debtor bank.	>O

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	id	Integer	-	Unique Identification for the transaction generated in NCHL side	Y
2	batchId	String	20	Unique Identification for the batch generated by NCHL for reconciliation.	Y
3	isoTxnId	Integer	-	CBS ISO reference id.	O
4	recDate	Date	-	Date (YYYY-MM-DD)	Y
5	instructionId	String	30	Unique identification for the transaction sent by NPI member for reconciliation purpose later.	Y
6	endToEndId	String	30	Value sent by NPI member for end to end recompilation.	Y
7	amount	BigDecimal	13,2	The amount to be transferred through this transaction.	Y
8	chargeAmount	BigDecimal	12,2	Total charge to be paid for the transaction.	Y
9	chargeLiability	String	2	Charge bearing party.	Y
10	purpose	String	4	Purpose of the transaction.	O
11	merchantId	Integer	-	Merchant ID is a unique identifier to identify merchant in the system. Merchant ID will be provided by NCHL upon registering merchant for connectIPS Core Module on banks’ request.	O
12	appId	String	15	Unique identification, which will be used to identify the account details of the merchant’s application. A merchant can have multiple applications based on different banks' accounts used for various shopping sites. Application Id will be provided by NCHL after registration.	O
13	appTxnId	String	20	-NA	O
14	creditorAgent	String	4	Creditor agent code in NCHL systems.	Y
15	creditorBranch	String	4	Creditor agent branch where the receiving party account is held.	Y
16	creditorName	String	140	Receiving party Account name.	Y
17	creditorAccount	String	20	Receiving party account number.	Y
18	creditorIdType	String	4	Receiving party private identification type for ex. Citizenship, pan no, passport etc.	O
19	creditorIdValue	String	20	Receiving party identification value.	O
20	creditorAddress	String	490	Receiving party postal address.	O
21	creditorPhone	String	20	Receiving party phone number in the format +<country code>-<area code><Phone Number>.	O
22	creditorMobile	String	20	Receiving party mobile number in the format +<country code>-<area code><Phone Number>.	O
23	creditorEmail	String	50	Receiving party valid email address.	O
24	addenda1	Integer	15	Information that is used to provide the extra information about the transaction. The value can be set as mandatory as per configuration of category purpose.	O
25	addenda2	Date	-		O
26	addenda3	String	35		O
27	addenda4	String	35		O
28	creditStatus	String	10	Response code received from creditor agent’s CBS	Y
29	reasonCode	String	10	Creditor status reason code	O
30	reversalStatus	String	20	Transaction reversal status in case debit success and credit failed.	C
31	refId	String	100	Payment Description	O
32	remarks	String	50	Payment Description	O
33	particulars	String	100	Same as instruction id	O
34	freeCode1	String	20	Extra information that can be appended to the transactions to be more specific about the purpose of transactions for reconciliation purpose. These fields will significant only up to the initiating party bank and will not be 37 routed to the beneficiary bank.	O
35	freeCode2	String	20
36	freeText1	String	100
37	freeText2	String	100
38	freeText3	String	250
39	freeText4	String	250
40	freeText5	String	250
41	freeText6	String	250
42	freeText7	String	250
43	beneficiaryId	String	50	-	O
44	beneficiaryName	String	100	Transaction receiving party	O
44	ipsBatchId	Integer	-	NA	O
45	rcreUserId	String	50	Transaction creation userId	O
46	rcreTime	Date	-	Date with timestamp	Y
47	reasonDesc	String	200	Credit description. (If credit status is 000, reasonDesc is SUCCESS, if timeout 999, then TIMEOUT, PLEASE CONFIRM WITH BANK BEFORE RE-POSTING and so on.)	Y
48	txnResponse	String	335	Transaction reference received from the creditor bank.	O
49	isoTxnId	Integer	-	CBS ISO reference id.	O
50	orignBranchId	String	4	Original branch id of the credit account.	Y

Case I (CIPS Debit/Credit Success)

{ 
 "id": 1340, 
 "batchId": 1357, 
 "isoTxnId": 1998, 
 "recDate": "2020-01-22", 
 "instructionId": "MACHHA-REV-3", 
 "endToEndId": "Payment Description", 
 "amount": 10.00, 
 "chargeAmount": 2.00, 
 "chargeLiability": "CG", 
 "purpose": null, 
 "merchantId": 1, 
 "appId": "MER-1-APP-3", 
 "appTxnId": "1340", 
 "creditorAgent": "1711", 
 "creditorBranch": "5", 
 "creditorName": "Creditor Name", 
"creditorAccount": "1225236632", 
 "creditorIdType": null, 
 "creditorIdValue": null, 
 "creditorAddress": null, 
 "creditorPhone": null, 
"creditorMobile": null, 
 "creditorEmail": null, 
 "addenda1": null, 
 "addenda2": null, 
 "addenda3": null, 
 "addenda4": "+977-98********", 
 "creditStatus": "000", 
 "reasonCode": null, 
 "reversalStatus": null, 
 "refId": "Payment Description", 
 "remarks": null, 
 "particulars": "MACHHA-REV-3", 
 "freeCode1": null, 
 "freeCode2": null, 
"freeText1": null, 
 "freeText2": null, 
 "beneficiaryId": null, 
 "beneficiaryName": null, 
"ipsBatchId": null, 
 "rcreUserId": "LAXMI@1701", 
 "rcreTime": "2020-01-22T06:05:30.181+0000", 
 "reasonDesc": "SUCCESS", 
 "txnResponse": "", 
 "cipsBatchDetail": { 
 "id": 1357, 
 "batchId": "MACHHA-REV1", 
 "recDate": "2020-01-22", 
"isoTxnId": 1998, 
 "batchAmount": 10.00, 
 "batchCount": 1, 
 "batchChargeAmount": 2.00, 
 "batchCrncy": "NPR", 
 "categoryPurpose": "ECPG", 
 "debtorAgent": "5511", 
 "debtorBranch": "1", 
 "debtorName": "Test Technical Member", 
 "debtorAccount": "12165161616", "debtorIdType": null, 
 "debtorIdValue": null, 
 "debtorAddress": "Kathmandu Nepal", 
 "debtorPhone": null, 
 "debtorMobile": "+977-98********",
 "debtorEmail": "test@test.com", 
 "channelId": "TECHM", 
 "debitStatus": "000", 
 "debitReasonCode": null, 
 "ipsBatchId": null, 
 "fileName": null, 
 "rcreTime": "2020-01-22T06:05:30.181+0000", 
 "rcreUserId": "LAXMI@1701", 
 "sessionSrlNo": 5, 
 "settlementDate": null, 
 "debitReasonDesc": "SUCCESS", 
 "txnResponse": "FT2002270067" 
 } 
}  

Case II (CIPS Credit Rejected)

{ 
"creditStatus":"114",
"reasonCode": null, 
 "reversalStatus": "000", 
 "reasonDesc": "Invalid account number "
 "cipsBatchDetail": { 
 "debitStatus": "000", 
 "debitReasonDesc": "SUCCESS", 
 } 
} 

Case III (CIPS Debit Rejected)

{
  "creditStatus": "1000",
  "reasonCode": null,
  "reasonDesc": "Debit Failure.",
  "cipsBatchDetail": {
    "debitStatus": "907",
    "debitReasonCode": "907",
    "debitReasonDesc": "Card issuer inoperative (When Bancs Connect cannot contact FINACLE and cannot do stand-in processing.) (DCC should reject transaction and do local authorization)",
    "txnResponse": ""
  }
}

Case IV (CIPS Credit Rejected (Temenos Banks))

{
    "creditStatus": "-01",
    "reasonCode": null,
    "reversalStatus": null,
    "reasonDesc": "Please Check the Transaction Response",
    "txnResponse": "NORMAL ACCT MUST BE IN OUR COMPANY, DEBIT.ACCT NO:1:1=DEBIT AND CREDIT ACCOUNT POSITION TYPE N",
    "cipsBatchDetail": {
        "debitStatus": "000",
        "debitReasonCode": null,
        "debitReasonDesc": "SUCCESS",
        "txnResponse": ""
    }
}

Case V (CIPS Debit Rejected (Temenos Banks))

{
    "creditStatus": "1000",
    "reasonDesc": "Debit Failure.",
    "txnResponse": "",
    "cipsBatchDetail": {
        "debitStatus": "-01",
        "debitReasonCode": null,
        "debitReasonDesc": "Please Check the Transaction Response",
        "txnResponse": "FT2002270069//1/NO, DEBIT.ACCT.NO: 1:1=MISSING ACCOUNT - RECORD"
    }
}

Note: Only debit/credits status related information are shown above. Rest of the parameters will be same as above.

Response Parameters for IPS(ACH) transactions Batch Details:

#	Field Name	Data Type	Length	Description	Presence
1	id	Integer	-	Unique Identification for the batch generated in NCHL side.	Y
2	batchId	String	20	Unique Identification for batch sent by NPI member for reconciliation.	Y
3	recDate	Date	-	Date (YYYY-MM-DD)	O
4	isoTxnId	Integer	-	CBS ISO reference id.	O
5	batchAmount	BigDecimal	14,2	The total sum up amount of all the transactions in the batch.	Y
6	batchCount	Integer	-	Total transactions in the batch.	Y
7	batchChargeAmount	BigDecimal	12,2	Total charge to be paid for the transaction.	Y
8	batchCrncy	String	3	Currency of the transaction. E.g., NPR	Y
9	categoryPurpose	String	4	Purpose of the transaction as available in NCHL-IPS system	Y
10	debtorAgent	String	4	Debtor agent code in NCHL systems.	Y
11	debtorBranch	String	4	Debtor branch where the transactions initiating party account is held.	Y
12	debtorName	String	140	Transaction initiation party account name.	Y
13	debtorAccount	String	20	Transaction initiation party account number.	Y
14	debtorIdType	String	4	Transaction initiation party private id type for ex. Citizenship, pan no, passport etc.	O
15	debtorIdValue	String	20	Transactions initiation party identification number for ex. Passport number, pan no. etc.	O
16	debtorAddress	String	490	Transactions initiation party postal address	O
17	debtorPhone	String	20	Transactions initiation party debtor phone number +<country code>-<area code><Phone Number>.	O
18	debtorMobile	String	20	Transactions initiation party mobile number +<country code>-<area code><Phone Number>.	O
19	debtorEmail	String	50	Debtor’s email address.	O
20	channelId	String	10	Specification of the channel used to perform the transaction; Technical member (TECHM), Web Fund Transfer (WEBFT) etc.	O
21	debitStatus	String	10	Response code for debit leg of the transaction.	Y
22	debitReasonCode	String	10	Response code returned by the debtor agent for debit leg of the transaction.	O
23	ipsBatchId	String	13	Unique ACH batch id generated by NCHL for ACH routing.	Y
24	fileName	String	100	ACH routing file name.	O
25	rcreTime	Date	-	Date with timestamp.	O
26	rcreUserId	String	50	Transaction creation id.	O
27	sessionSeq	String	20	ACH session sequence number.	Y
28	settlementDate	Date	-	ACH transaction settlement date.	Y
29	debitReasonDesc	String	200	Debit description. (If debit status is 000, debitReasonDesc is SUCCESS, if timeout 999, then TIMEOUT, PLEASE CONFIRM WITH BANK BEFORE REPOSTING and so on.)	Y
30	txnResponse	String	335	Reference number returned by debtor bank.	O

Transaction Details:

#	Field Name	Data Type	Length	Description	Presence
1	id	Integer	-	Unique Identification for the transaction generated in NCHL side	Y
2	batchId	String	20	Unique Identification for the batch generated by NCHL for reconciliation.	Y
3	isoTxnId	Integer	-	CBS ISO reference id.	O
4	recDate	Date	-	Date (YYYY-MM-DD)	Y
5	instructionId	String	30	Unique identification for the transaction sent by NPI member for reconciliation purpose later.	Y
6	endToEndId	String	30	Value sent by NPI member for end to end recompilation.	Y
7	amount	BigDecimal	13,2	The amount to be transferred through this transaction.	Y
8	chargeAmount	BigDecimal	12,2	Total charge to be paid for the transaction.	Y
9	chargeLiability	String	2	Charge bearing party.	Y
10	purpose	String	4	Purpose of the transaction.	O
11	merchantId	Integer	-	Merchant ID is a unique identifier to identify merchant in the system. Merchant ID will be provided by NCHL upon registering merchant for connectIPS Core Module on banks’ request.	O
12	appId	String	15	Unique identification, which will be used to identify the account details of the merchant’s application. A merchant can have multiple applications based on different banks' accounts used for various shopping sites. Application Id will be provided by NCHL after registration.	O
13	appTxnId	String	20	-NA	O
14	creditorAgent	String	4	Creditor agent code in NCHL systems.	Y
15	creditorBranch	String	4	Creditor agent branch where the receiving party account is held.	Y
16	creditorName	String	140	Receiving party Account name.	Y
17	creditorAccount	String	20	Receiving party account number.	Y
18	creditorIdType	String	4	Receiving party private identification type for ex. Citizenship, pan no, passport etc.	O
19	creditorIdValue	String	20	Receiving party identification value.	O
20	creditorAddress	String	490	Receiving party postal address.	O
21	creditorPhone	String	20	Receiving party phone number in the format +<country code>-<area code><Phone Number>.	O
22	creditorMobile	String	20	Receiving party mobile number in the format +<country code>-<area code><Phone Number>.	O
23	creditorEmail	String	50	Receiving party valid email address.	O
24	addenda1	Integer	15	Information that is used to provide the extra information about the transaction. The value can be set as mandatory as per configuration of category purpose.	O
25	addenda2	Date	-		O
26	addenda3	String	35		O
27	addenda4	String	35		O
28	creditStatus	String	10	ACH settlement code (ENTR, GEN, SENT, ACTC, ACSP, ACSC/ RJCT)	Y
29	reasonCode	String	10	Reason code in case credit leg is rejected.	O
30	reversalStatus	String	20	Reversal status in case debit success and credit leg failed.	C
31	refId	String	100	Payment description	O
32	remarks	String	50	Payment description	O
33	particulars	String	100	Instruction id	O
34	freeCode1	String	20	Extra information that can be appended to the transactions to be more specific about the purpose of transactions for reconciliation purpose. These fields will be significant only up to the initiating party bank and will not be routed to the beneficiary bank.	O
35	freeCode2	String	20		O
36	freeText1	String	100		O
37	freeText2	String	100		O
38	beneficiaryId	String	50	-NA	O
39	beneficiaryName	String	100	Transaction receiving party	O
40	ipsBatchId	Integer	-	Unique batch id generated by NCHL for ACH routing.	Y
41	rcreUserId	String	50	Transaction creation id.	O
42	rcreTime	Date	-	Date with timestamp.	O
43	ipsTxnId	String	16	Unique transaction id generated by NCHL for ACH routing.	Y
44	reasonDesc	String	200	Credit description. (If credit status is ACSC, reasonDesc is Empty, if RJCT, reasonDesc is “Account does not exist” or some other reason.)	Y
45	txnResponse	String	335	Transaction reference returned by creditor bank.	O

Case VI (IPS Debit/Credit Success)

{
    "id": 146,
    "batchId": 89,
    "isoTxnId": null,
    "recDate": "2020-01-22",
    "instructionId": "STRESS_TXN_144052",
    "endToEndId": "Payment Description",
    "amount": 10.00,
    "chargeAmount": 2.00,
    "chargeLiability": "CG",
    "purpose": null,
    "merchantId": null,
    "appId": "MER-1-APP-3",
    "appTxnId": null,
    "creditorAgent": "5263",
    "creditorBranch": "75",
    "creditorName": "Bijay Dahal",
    "creditorAccount": "123456789",
    "creditorIdType": "0001",
    "creditorIdValue": "5689755562",
    "creditorAddress": "Bhaktapur Nepal",
    "creditorPhone": "+977-01-66*****",
    "creditorMobile": "+977-98********",
    "creditorEmail": "creditor1@test.com.np",
    "addenda1": 8965,
    "addenda2": "2018-09-10",
    "addenda3": "Addenda info3",
    "addenda4": "Addenda info4",
    "creditStatus": "ACSC",
    "reasonCode": null,
    "reversalStatus": null,
    "refId": null,
    "remarks": null,
    "particulars": null,
    "freeCode1": null,
    "freeCode2": null,
    "freeText1": null,
    "freeText2": null,
    "beneficiaryId": null,
    "beneficiaryName": null,
    "ipsBatchId": "1701200122GMT",
    "rcreUserId": "LAXMI@1701",
    "rcreTime": "2020-01-22T10:01:47.291+0000",
    "ipsTxnId": "1701200122GMT00B",
    "reasonDesc": "",
    "txnResponse": "",
    "nchlIpsBatchDetail": {
        "id": 89,
        "batchId": "STRESS_642180",
        "recDate": "2020-01-22",
        "isoTxnId": 2015,
        "batchAmount": 10.00,
        "batchCount": 1,
        "batchChargeAmount": 2.00,
        "batchCrncy": "NPR",
        "categoryPurpose": "CUST",
        "debtorAgent": "5521",
        "debtorBranch": "5",
        "debtorName": "Test Technical Member",
  "debtorAccount": "0010********0018",
        "debtorIdType": "0001",
        "debtorIdValue": "123456",
        "debtorAddress": "Kathmandu Nepal",
        "debtorPhone": "+977-01-425****",
        "debtorMobile": "+977-98********",
        "debtorEmail": "test@test.com",
        "channelId": "TECHM",
        "debitStatus": "000",
        "debitReasonCode": null,
        "ipsBatchId": "1701200122GMT",
        "fileName": null,
        "rcreTime": "2020-01-22T10:01:47.291+0000",
        "rcreUserId": "LAXMI@1701",
        "sessionSeq": null,
        "settlementDate": null,
        "debitReasonDesc": "SUCCESS",
        "txnResponse": ""
    }
}

Case VII (IPS Credit Rejected)

{
  "creditStatus": "RJCT",
  "reasonCode": "502",
  "reasonDesc": "Account Not Found",
  "txnResponse": "",
  "nchlIpsBatchDetail": {
    "debitStatus": "000",
    "debitReasonCode": null,
    "debitReasonDesc": "SUCCESS",
    "txnResponse": ""
  }
}

Case VIII (IPS Debit Rejected)

{
  "creditStatus": "1000",
  "reasonCode": null,
  "reasonDesc": "Debit Failure.",
  "txnResponse": "",
  "nchlIpsBatchDetail": {
    "debitStatus": "114",
    "debitReasonCode": null,
    "debitReasonDesc": "Invalid account number",
    "txnResponse": ""
  }
}

Note: Only debit/credits status related information are shown above. Rest of the parameters will be same as above

5.6. Other APIs

Below are the lists of other supporting APIs to extract the list and/or setups from the core system.

1. /api/getbranchlist: To get the branch list for both ips.

Sample Response:

[
   {
      "branchId":"59",
      "bankId":"6001",
      "branchName":"Narayangadh Branch"
   },
   {
      "branchId":"280",
      "bankId":"1601",
      "branchName":"Durbar Marg Branch"
   }
]

2. /api/getcipsbranchlist: To get the branch list for both cips.

Sample Response:

[
   {
      "branchId":"59",
      "bankId":"6001",
      "branchName":"Narayangadh Branch"
   },
   {
      "branchId":"280",
      "bankId":"1601",
      "branchName":"Durbar Marg Branch"
   }
]

3. /api/getcipsbanklist: To get the CIPS bank list

Sample Response:

[
   {
      "bankId":"2601",
      "bankName":"Prabhu Bank Limited"
   },
   {
      "bankId":"2301",
      "bankName":"NIC Asia Bank Limited"
   },
   {
      "bankId":"9945",
      "bankName":"Kanchan Development Bank Ltd"
   }
]

4. /api/getbanklist: To get the IPS bank list.

Sample Response:

[
   {
      "bankId":"7502",
      "bankName":"Excel Development Bank Ltd."
   },
   {
      "bankId":"2301",
      "bankName":"NIC Asia Bank Limited"
   }
]

5. /api/getbranchlist/{bankId}: To get the branch list of the provided bank. Eg: /getbranchlist/1901

Sample Response

[
   {
      "branchId":"33",
      "bankId":"1901",
      "branchName":"Panipokhari Branch"
   },
   {
      "branchId":"70",
      "bankId":"1901",
      "branchName":"Tamghas Branch"
   }
]

6. /api/getcipschargelist/MER-1-APP-3: To get the cips and ips charge slab as per the merchant id that will be applied to Debtor. Eg. MER-1-APP-3 is for fund transfer.

Sample Response:

[
   {
      "scheme":"P2P",
      "currency":"NPR",
      "maxAmt":500,
      "minChargeAmt":2,
      "maxChargeAmt":2,
      "percent":0
   },
   {
      "scheme":"P2P",
      "currency":"NPR",
      "maxAmt":5000,
      "minChargeAmt":5,
      "maxChargeAmt":5,
      "percent":0
   },
   {
      "scheme":"P2P",
      "currency":"NPR",
      "maxAmt":50000,
      "minChargeAmt":10,
      "maxChargeAmt":10,
      "percent":0
   },
   {
      "scheme":"P2P",
      "currency":"NPR",
      "maxAmt":200000000,
      "minChargeAmt":15,
      "maxChargeAmt":15,
      "percent":0
   }
]

7. /api/getacvalidationenabledbanklist : To get the bank list having account validation features enabled.

Sample Response:

[
   {
      "bankId":"4501",
      "bankName":"Sanima Bank Ltd."
   },
   {
      "bankId":"1501",
      "bankName":"Machhapuchchhre Bank Limited"
   }
]

8. /api/getreversalenabledbanklist : To get the bank list having auto reversal feature enabled.

Sample Response:

[
   {
      "bankId":"4501",
      "bankName":"Sanima Bank Ltd."
   },
   {
      "bankId":"1501",
      "bankName":"Machhapuchchhre Bank Limited"
   }
]

9. /api/bank-account/details: To get the list of added bank accounts for technical NPI members.

Sample Response:

{
   "timestamp":"Sun Sep 17 09:56:06 NPT 2023",
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"Account Details Fetched.",
   "data":[
      {
         "entryId":"4750",
         "bankId":"7516",
         "branchId":"1",
         "accountName":"Test Account",
        "accountId": "28*******1564"
         "bankName":"Best Company Ltd.",
         "status":"ACCEPTED",
         "rcreTime":"2022-07-27T06:48:02.566+0000"
      },
      {
         "entryId":"4864",
         "bankId":"9931",
         "branchId":"71",
         "accountName":"P.U.-SEWA AAYOG OFFICE",
         "accountId": "28*******1564"
         "bankName":"Mahalaxmi Bikas Bank Ltd.",
         "status":"ACCEPTED",
         "rcreTime":"2022-08-01T09:31:35.104+0000"
      }
   ]
}

10. /api/debit-cap/details: To get the details of debit cap which is assigned to the particular bank of the NPI member.

Sample Response:

{
   "timestamp":"2023-09-15 02:18:13",
   "responseCode":"000",
   "responseStatus":"SUCCESS",
   "responseMessage":"Debit Cap Detail Fetched.",
   "responseData":[
      {
         "debitCap":1000000.00,
         "clrBalAmount":1000000.00,
         "bankName":"Nabil Bank Ltd.",
         "sessionId":4458
      },
      {
         "debitCap":1000000.00,
         "clrBalAmount":1000000.00,
         "bankName":"Siddhartha Bank Limited",
         "sessionId":4458
      }
   ]
}

11. /api/tp/auto-release/details: To get details on category purpose and maximum auto-release amount for different banks. This endpoint will return data showing the maximum amount that can be auto-released/debited without any manual intervention required from the NPI member’s debtor bank. This endpoint is applicable in the case of non-real-time payment only.

Sample Request: { "bankCode": "2301" }

Sample Response:

{
   "data":[
      {
         "categoryPurpose":"SSFC",
         "bankCode":"2301",
         "maxAutoReleaseAmount":"200,000,000.00",
         "currency":"NPR",
         "bankName":"NIC Asia Bank Limited",
         "status":"Approved"
      },
      {
         "categoryPurpose":"SALA",
         "bankCode":"2301",
         "maxAutoReleaseAmount":"5,000,000.00",
         "currency":"NPR",
         "bankName":"NIC Asia Bank Limited",
         "status":"Approved"
      },
      {
         "categoryPurpose":"SALC",
         "bankCode":"2301",
         "maxAutoReleaseAmount":"50,000,000.00",
         "currency":"NPR",
         "bankName":"NIC Asia Bank Limited",
         "status":"Approved"
      },
      {
         "categoryPurpose":"SUPP",
         "bankCode":"2301",
         "maxAutoReleaseAmount":"100,000,000.00",
         "currency":"NPR",
         "bankName":"NIC Asia Bank Limited",
         "status":"Approved"
      },
      {
         "categoryPurpose":"GOVT",
         "bankCode":"2301",
         "maxAutoReleaseAmount":"500,000,000.00",
         "currency":"NPR",
         "bankName":"NIC Asia Bank Limited",
         "status":"Approved"
      }
   ],
   "message":"Success",
   "status":true
}

Response parameters details:

S. No.	Field Name	Data Type	Length	Description
1	categoryPurpose	String	4	Category purpose for payment
2	bankCode	String	4	Bank code for which the category details is fetched
3	maxAutoReleaseAmount	String	13,2	Amount that can be directly debited from NPI member’s debtor account without approval from the bank
4	Currency	String	3	Currency related to the category purpose
5	bankName	String	100	Bank name for which the category details is fetched
6	status	String	-	Status of the amount limitation which has been set by the particular bank
7	Message	String	-	API response message
8	status	Boolean	-	API status

12. Balance enquiry

The balance enquiry endpoint can be consumed prior to posting payments in either real time or non-real time services. Only technical members whose account(s) are whitelisted by NCHL and whose debit authority has been obtained from the respective bank(s) are allowed to enquire their available balance.

POST URL for balance enquiry: /api/account/balance

Request Parameters:

S.no	Field Name	Data Type	Length	Presence	Description
1	bankId	String	4	Y	4 Digit NCHL Bank Code
2	branchId	String	4	Y	Branch Code. Default HO branch to be sent
3	accountId	String	20	Y	Account Number as listed in NCHL-NPI. (Whitelisted source account by NCHL)

Case Successful:

Request:

{ 
 "bankId": "2501", 
 "branchId": "53",
 "accountId": "12xxxxxxxxxxxxxxxxxx45" 
}

Success Response:

{
"responseCode": "000", 
"bankId": "2501", 
"branchId": "53", 
"accountId": "12xxxxxxxxxxxxxxxxxx45",
"currency": "NPR", 
"totalBal": 61579.82, 
"availBal": 60579.82, 
"abPartTranType": "CR", 
"lbPartTranType": "CR"
} 

Failed Response:

{ 
"responseCode": "E010", 
"responseMessage": "RECORD NOT FOUND:- INVALID TECHNICAL MEMBER.", 
"data": null, 
"classfielderrorlist": [] 
}`

Response Parameters:

S.No	Field Name	Data Type	Length	Description	Presence
1	responseCode	String	3	API response code. Response code 000 for success and E10 for failure	Y
2	bankId	String	4	4 Digit NCHL Bank Code.	Y
3	branchId	String	4	Branch Code.	Y
4	accountId	String	20	Account Number as Listed in NCHL NPI. (Whitelisted source account by NCHL)	Y
5	Currency	String	3	Currency of the account.	Y
6	TotalBal	Numeric	-	Total balance in the account.	Y
7	availBal	Numeric	-	Available balance for transaction.	Y
8	abPartTranType	String	2	Available balance type.	Y
9	lbPartTranType	String	2	Ledger balance type.	Y
10	responseMessage	String	200	Response message is obtained in case of failure. It is conditional.	C

5. API Specifications

5.1. API Security Guidelines for NPI Integration​

5.1.1 Token-based Access Control​

5.2. Digital Signature​

5.3. Account Validation​

5.4. Transaction APIs​

5.4.1. Real Time Transactions (postcipsbatch)​

5.4.2. Non-Real Time Transactions (postnchlipsbatch)​

5.4.3. Aggregated Service APIs​

5.5. Transaction Reporting APIs​

5.6. Other APIs​

5.1. API Security Guidelines for NPI Integration

5.1.1 Token-based Access Control

5.2. Digital Signature

5.3. Account Validation

5.4. Transaction APIs

5.4.1. Real Time Transactions (postcipsbatch)

5.4.2. Non-Real Time Transactions (postnchlipsbatch)

5.4.3. Aggregated Service APIs

5.5. Transaction Reporting APIs

5.6. Other APIs