1. Introduction

1.1 BACKGROUND

As per the mandate from Nepal Rastra Bank (NRB), NCHL has established the infrastructure for interoperability of card-based transactions, implementation of domestic card scheme for Nepal, and scale-up of the existing retail payment systems/platforms to enable non-card-based interoperability as part of National Payment Switch (NPS) project. The main objective of the NPS is for enabling payment eco-system for major players in the card and retail payments market, positioning Nepal as a financial hub for both domestic and international payments, leveraging market synergy.

The PSP/Wallet interoperability is the one of instrument of Retail Payment switch, a part of National Payment Switch (NPS), that facilitates for enabling multiple use cases such as wallet-to-wallet transfer, account to wallet load, wallet to account transfer, and receiving remittance & social security to the wallet users via National Payment Interface (NPI).Additionally, as per the latest circular from NRB, PSPs are also eligible to participate in cross-border payments through the National Payment Switch. As the operator of National Payment Switch , NCHL is responsible for creating a healthy, robust and scalable payment eco-system adhering to all the regulatory compliance with the enforcement of stringent security measures. In this context, it is required to establish a standard and uniform integration approach with all member PSPs/wallet to ensure end to visibility of payment transaction with the implementation of comprehensive know you customer (KYC) mechanism.

1.2 PURPOSE OF THE DOCUMENT

This document has been prepared and issued as a standard API specification for PSP/Wallet Interoperability for enabling the various use cases within the NPI. In addition, it has been developed to facilitate PSPs for Cross-Border payments, standardize and streamline the customer validation process, ensuring regulatory compliance, enhancing security, and improving operational efficiency across all service providers. The intended audience for this document comprises mainly technical resources or partners of the BFIs, members of NCHL, and service providers with technical expertise in system setup and development, ensuring end-to-end visibility.

1.3 KEY OBJECTIVES

The main objectives of this technical specification documents are as follows:

1. Establish the standard and uniform integration mechanism with all member PSPs.
2. To meet the KYC and compliance requirement for both domestic and Cross-Border payments.
3. To manage and mitigate risks associated with fraud and non-compliance.
4. To facilitate interoperability across different wallets and service providers.
5. To support scalability and future expansion of services.

1.4 USER VALIDATION API

This API is used to validate the wallet user prior to the payment transaction based on the details provided in the validation request. PSPs are required develop the validation API as per the below specification and provide all details as specified in the response requirements.

Method	End-Points	Authorization	Header Parameter
POST	(base url)+ /validate-user	Authorization: Basic	X-Signature

Request Parameters

Field	Data Type	Optional	Description
userIdentifier	String	M	Username, phone, or email as per the wallet nature.
amount	Numeric	M	Amount to be loaded (Decimal value with exactly two positions after the decimal point).
Channel	String	M	Source of request: CIPS -> connectIPS MB -> mobile Banking REMIT -> Remittance channel CROSS-BORDER -> for cross border payment WALLET -> Request From wallet OTHERS -> others if any

Response Parameter

Field	Data Type	Optional	Description
responseCode	String	M	https: 200 OK 000 for Success; else failed
responseMessage	String	M	Response message description
validationTraceId	String	M	Unique ID generated from the wallet to trace the transaction
kycStatus	String	M	KYC Status of customer VERIFIED | UNVERIFIED
accountStatus	String	M	Account status: ACTIVE, BLOCKED, SUSPENDED
allowedLimit	String	M	Pending Allowed limits for load wallet
transactionDate	String	M	Transaction date in format: YYYY-MM-DD HH:MM:SS.SSS
vpaAddress	String	C	Linked Bank VPA ID for cross-border payment
userIdentifier1	String	M	Username, phone, or email
userIdentifier2	String	O	Wallet VPA
customerFullName	String	M	Customer full name
userType	String	M	NORMAL | AGENT
responseErrors
fieldName	String	C	Error code
fieldDescription	String	C	Error description details for the request

Sample Request

{
    "userIdentifier":"9851114610",
    "amount":5000.00,
    "channel":"CIPS| MOB| REMIT|CROSS-BORDER| WALLET | OTHERS"
}

Sample Response - Success

{
   "responseCode":"000",
   "responseMessage":"SUCCESS",
   "validationTraceId":"1234567890",
   "kycStatus":"VERIFIED|UNVERIFIED",
   "accountStatus":"ACTIVE|BLOCKED|SUSPENDED",
   "allowedTxnLimit":1500.00, 
   "allowedTxnCount":10,
   "transactionDate":"yyyy-MM-dd HH:mm:ss.SSS",
   "partnerVPA":"9811111111@NIMB",
   "userInfo": {
       "userIdentifier1":"9813979589",
       "userIdentifier2":"9813979589@NIMB",
       "customerFullName":"Bishal Panthi",
       "userType":"NORMAL|AGENT"
   },
   "responseErrors":null
}

userInfo: Map<String, String> map;

userIdentifier: Customer identifier like username

customerFullName: Full name of customer

userType: Type of user

Based on regulatory requirement further details could be added in future and corresponding keys will be provided separately.

Sample Response - Failed

{
    "responseCode":"T001",
    "responseMessage":"FAILED",
    "message":"Error Message",
    "responseErrors": [
{
       "fieldName":"1",
       "fieldDescription":"Error message"
    }
]
}

1.5 PAYMENT CONFIRMATION API This API is used to post the payment confirmation transaction to the respective PSP/Wallet after the necessary the transaction is processing in Retail Payment Switch (RPS). PSPs are required to develop an API for payment confirmation as per the below specification.

Method	End-Points	Authorization	Header Parameter
POST	base url + /payment-request	Authorization: Basic	X-Signature

Request Parameters:

Field	Data Type	Optional	Description
userIdentifier	String	M	Username, phone, or email as per the wallet nature.
amount	Numeric	M	Amount to be loaded (Decimal value with exactly two positions after the decimal point).
channel	String	M	Source of request: CIPS -> connectIPS MB -> mobile Banking REMIT -> Remittance channel CROSS-BORDER -> cross border payment WALLET -> Request From wallet OTHERS -> others if any
purpose	String	M	LOAD -> Fund transfer to wallet CAMPAIGN -> Campaign related REFUND -> Refund related R2P -> Request To Pay OTHERS -> Others if any
transactionDate	Date	M	Transaction Date and time
transactionId	String	M	RIPS transaction Id
validationTraceId	String	M	Validation trace Id returned at customer validation
userType	String	M	NORMAL | AGENT
tranRemarks	String	O	The purpose of the transaction

Response Parameters

Field	Data Type	Optional	Description
responseCode	String	M	000 for SUCCESS; ENTR for PROCESSING; Else FAILED
responseMessage	String	M	Response message description
validationTraceId	String	M	Unique ID generated from the wallet to trace the transaction
addenda1	String	O	Any value to be displayed to the user through the channel
Message	String	O	Payment confirmation message
transactionId	String	M	RIPS transaction Id
responseErrors
fieldName	String	C	Error code
fieldDescription	String	C	Error description details for the payment request

Sample Request

{
  "validationTraceId":"1234567890",
  "amount":5000.00,
  "userIdentifier":"9851XXXXXX",
  "channel":"CIPS",
  "purpose":"LOAD",
  "transactionDate":"yyyy-MM-dd HH:mm:ss.SSS",
  "userType":"NORMAL|AGENT",
  "transactionId":12457848,
  "tranRemarks":"Bill Payment"
}

Sample Response - Success

{
  "responseCode":"000",
  "responseMessage":"SUCCESS",
  "message":"Payment Posting successful",
  "validationTraceId":"1234567890",
  "addenda1":"FreeText",
  "transactionId":12457848,
  "responseErrors":null
}

Sample Response - Failed

{
    "responseCode":"T001",
    "responseMessage":"FAILED",
    "message":"Error Message",
    "responseErrors": [
{
       "fieldName":"1",
       "fieldDescription":"Error message"
    }
]
}