3. API Specification
3.1 Authentication and Authorization
OAuth 2.0 API authentication mechanism has been implemented for authentication and authorization process in NPI. The client needs to provide client specific credentials in the authorization header and user credentials in the body with grant type as password for token generation on first login or during refresh token expiration.
On successful authentication, system will provide access token and refresh token pair. Access tokens are used for accessing the resources and refresh tokens are used for obtaining and renewal of access tokens. Validity of access token is 300 seconds and validity of refresh token is 12 hours (which may vary as per NCHL Security Policy). Access tokens could be obtained by using non-expired refresh tokens in the body with grant type as refresh token.
Method to generate & use access and refresh token
Use the provided basic authentication credentials along with username/password and grant type as password to obtain a refresh token. Refresh token has validity of 12 hours for now, so store the refresh token for future access token requests. Do not use the access token obtained during this initial request.
Use the stored refresh token obtained from step 1 to generate new access token keeping grant type as refresh token. Access tokens are valid for 300 seconds. Use the obtained access token in the authorization header: Bearer {access_token} of all API resources requests within this period. On expiry of access token re-request using the stored refresh token.
On expiry of refresh token repeat the process from step 1.
| Method | URL |
|---|---|
| POST | (base URL)/oauth/token |
3.2 Token Generation Process
Generate token string as per the instruction provided in API specification.
Sign the message token from step 1 using the digital certificate private key (pfx file/KeyStore). The digital signature algorithm will be the SHA256withRSA.
Convert the signed token above in step 2 to base64 encoding.
Pass this signature string to the “token” field of the request message.
3.3 Create Withdraw Request
This API is used to initiate OTP request based on the parameters provided. Third party user must have user for authentication from NPI.
| Method | URL | Authorization |
|---|---|---|
| POST | (base URL)/api/v1/cardless/create-request | Bearer(access_token) |
Request Parameter
| # | Field Name | Data Type | Length | Description | Presence |
|---|---|---|---|---|---|
| 1 | amount | string | Transaction amount should be in rupees and multiples of 1000 | M | |
| 2 | mobileNumber | string | 10 | Mobile number of users | M |
| 3 | accountName | string | 50 | Customer A/C name. In case of wallet, this should be wallet pool A/C name. | M |
| 4 | accountNumber | string | 20 | Customer A/C number. In case of wallet, this should be wallet pool A/C number | M |
| 5 | branchId | string | 3 | Customer A/C branch. In case of wallet, this should be wallet pool A/C branch. | M |
| 6 | transactionUniqueId | string | 36 | Transaction ID which is used to reconcile between third party and NCHL. It must be unique for each request. | M |
| 7 | currencyCode | string | 3 | Currency of transaction. Example: NPR | M |
| 8 | remarks | string | 36 | Remarks for the transaction. | M |
Token String: Mobile Number+,”+transactionUniqueId+”,+amount+, NPI userId
Sample Request Payload:
{
"amount": 5000.0,
"mobileNumber": "98XXXXXXXX",
"accountName": "Ankit Neupane",
"accountNumber": "00100XXXXXXX",
"branchId": "1",
"bankId": "1000",
"transactionUniqueId": "b39a8e6f-d022-49e2-b21e-452178ad2746",
"remarks": "Towards the mountains",
"token":"dUD1Fmxb2l9NE+aTgCLuomlOFm0bpkmlE2XwpTDIF2r1tG1xZU5FfNj9SRJpQEQm5V+u7SF9aTXa0AsINnXYwcJiNT/Fd5K818SIsQ/ELXeAskbl3MZyV6GuY0Uh7n3RjIoZhJ3mdz0lbr9PZohSB8EQFAccj/yeZgSLGRAJgeg="
}
Sample Success Response:
{
"responseCode": "000",
"responseMessage": "Withdrawal request process successfully. You will be notified with SMS with more detail."
}
3.4 Cash Withdraw Request
This request initiates the cash withdrawal transactions processed through the acquiring switch to retail payment switch.
| Method | URL | Authorization |
|---|---|---|
| POST | (base URL)/cardless/withdraw/transaction | Bearer (access_token) |
| # | Field Name | Data Type | Length | Description | Presence |
|---|---|---|---|---|---|
| 1 | verificationCode | String | OTP received by the customer. | M | |
| 2 | mobileNumber | String | 10 | Mobile number of customers | M |
| 3 | amount | String | Amount entered during withdrawal request. | M | |
| 4 | bankCode | String | 4 | ATM Acquiring Bank Code | M |
| 5 | traceNumber | String | Trace Number | M | |
| 6 | referenceNumber | String | ATM reference number | M | |
| 7 | terminalId | String | ATM Terminal Id | M |
Sample Request Payload:
{
"verificationCode": "999277",
"mobileNumber": "9813XXXXXX",
"amount": 500000,
"bankCode": "PCBLNPKA",
"traceNumber": "TRACE015",
"referenceNumber": "CLW-058834591",
"terminalId": "PRIME2101"
}
Sample Success Response:
{
"status": "true",
"message": "Cash withdrawal Successful",
"code": "000",
"developerMessage": "null",
"link": "null",
"data": "{
"accountNumber": "0010XXXXXXXX",
"mobileNumber": "9813XXXXXX",
"bankCode": "PCBLNPKA",
"amount": 5000,
"bookingDate": "2024-05-09 11:27:16.676",
"referenceId": "CLW-058834591",
"terminalId": "PRIME2101",
"traceNumber": "TRACE015"
}",
}
3.5 Cardless Withdraw Report
| Method | URL | Authorization |
|---|---|---|
| POST | (base URL)/oauth/token | Bearer(access_token) |
| # | Field Name | Data Type | Length | Description | Presence |
|---|---|---|---|---|---|
| 1 | transactionUniqueId | String | 36 | Transaction Unique Id of that transaction. | M |
Sample Request Payload:
{
"transactionUniqueId": "b39a8e6f-d022-49e2-b21e-452178ad2746"
}
Sample Success Response
{
"responseCode": "000",
"responseData": [
{
"accountNumber": "001XXXXXXXXXXX",
"branchId": "1",
"bankId": "2501",
"accountName": "Ankit Neupane",
"amount": 5000,
"mobileNumber": "9813XXXXXX",
"expiryDate": "2024-05-09T06:58:25.029+00:00",
"customerIdentifier": "SABITA@999",
"status": "ACTIVE",
"txnId": "12809565",
"paymentStatus": "PAID",
"instrument": "MOBILE_BANKING",
"transactionUniqueId": "b39a8e6f-d022-49e2-b21e-452178ad2746",
"remarks": "Towards the mountains"
}
]
}
3.6 Cardless Withdraw Notification
To notify about the transaction status (success or failure) for reconciliation purposes. Status of transaction will be pushed to notification URL. Each request will be formatted in JSON and signed using private key. The receiver will verify the signature using public key provided by NCHL ensuring the integrity and authenticity of the request, preventing tampering during transmission. Notifications will be dispatched upon transaction processing, and a response is expected to confirm whether the notification was successfully delivered.
The notification API provided by the receiver should be secured using basic authentication. The credentials must be added in the header of each API call. Credentials should be combined into a single string in below format, then encoded using Base64.
| Method | URL | Authorization |
|---|---|---|
| POST | (base URL)/cardless/thirdparty/notification | Basic Base64(username:password) |
Request Details:
The request body will be a JSON object containing the transaction details:
| # | Field Name | Length | Description |
|---|---|---|---|
| 1 | transactionUniqueId | 36 | Transaction ID which is used to reconcile between third party and NCHL. It must be unique for each request. |
| 2 | debitStatus | 4 | Status of the debit operation. |
| 3 | debitDescription | 36 | Description of the debit status. |
| 4 | creditStatus | 4 | Status of the credit operation. |
| 5 | creditDescription | 36 | Description of the credit status. |
| 6 | rpsTransactionId | 10 | Unique identifier of transaction on NPI (RPS). |
| 7 | mobileNumber | 10 | Mobile number associated with the transaction. |
| 8 | remarks | 36 | User Remarks. |
| 9 | token | Signature token. |
Sample JSON Request
{
"transactionUniqueId": "card30",
"debitStatus": "000",
"debitDescription": "SUCCESS",
"creditStatus": "000",
"creditDescription": "SUCCESS",
"rpsTransactionId": 13185492,
"mobileNumber": "*****08459",
"remarks": " Towards the mountains ",
"paymentStatus": "PAID",
}
The JSON payload must be signed using private key. Upon receiving the notification, the receiver will use verify the public key provided by NCHL to ensure authenticity and integrity. After processing the notification, the receiver will send a response back to the sender to confirm whether the notification was successfully delivered. Response format can be any, but following in response is mandatory, for proper verification of withdraw Notification.
| # | Field Name | Data Type | Example | Description |
|---|---|---|---|---|
| 1 | status | String | SUCCESS | Notification Response status: SUCCESS or FAILED or TIMEOUT |
| 2 | message | String | Notification send successfully | A message providing additional context or remarks about the response. |