2. API SPECIFICATION

2.1. GENERAL PAYLOAD

Named request/response model WsTxnRecord will be used for passing information through the QR Parsing as well as Transaction Process; depending upon the phase the fields have variable use case. Further details of the fields are explained in detail:

Field	Type	Description
txn_id	String	Unique channel id for each transaction (validation trace id generated during dynamic QR)
channel	String	Client from where web socket connection request originates. GWQR | NQR
merchant_id	String	Terminal ID
ws_id	String	Unique Id to identify each client request and used for response
message	String	Different activity message.
status	String	Phase: QR Parsing ENTR PARSED Phase: QR Transaction COMPLETED FAILED
debit_status	String	Debit status field is only applicable on QR Transaction Phase. Phase: QR Transaction Success: 000 (Rest Failed)
credit_status	String	Credit status field is only applicable on QR Transaction Phase. Phase: QR Transaction Success: 000/999/DEFER (Rest Failed)

2.2 CONNECTION ESTABLISHMENT

In order to perform bi-directional web socket communication client must first initiate the connection request.

Direction	Client -> WS Request
URL	/nqrws

2.2.1 Subscribe

To get the data back from WS server, client must subscribe to given end point.

Direction	Client -> WS Request
URL	/user/nqrws/check-txn-status

2.2.2 Transaction Detail Request

Send information of transaction details such as merchant id and transaction id.

Direction	Request
URL	/nqrws/check-txn-status

Request Payload:

Field	Format	Description
merchant_id	String	Merchant PAN
request_id	String	Unique transaction id (validation trace id generated during dynamic QR)
username	String	Username (will be provided)
api_token	String	API Token (will be provided)

Example Payload:

{
   "merchant_id": "MER-980-APP-1",
   "request_id":"770342",
   "username":"username",
   "api_token":"WAxGtlKbhV3NE+d3DB3mfzgj2hD2oS6j46NuPJm/9yB1yhVsRM1tWfyj9yGdJv1GMlZTfbRWzybdiQAUQ+TryuAIbEfTXEPJ6DURIv5g6AbeCl7RitiyILRiKnPPiBPTMtv0R7v4bIr/o6qQBdYZL4BJ7fXFsOddium0RDmaQVLfjrc0qjxh/LXLOnSQcgyXtLgQGFIaLt84AGozYx6kpYv9kipo8DxWGJ7pdPl5y8NNvmzG7IEdaaHytKt/fd3ci3zF2kLBOdY/RNC34t0LFJwuPpf6C0dlk4c+MciAth9dzxHenXZ7x0seSrxttcB+gRcg/V61c1x02AfyD7lQ=="
}  

Response Structure:

Field	Format	Description
status	String	Web socket QR transaction status
channel	String	Client channel name
message	String	Information message
merchant_id	String	Merchant id
request_id	String	Unique transaction id
ws_id	String	Unique web socket id

Example Response:

{
 "status": "ENTR",
 "channel": "GWQR",
 "message": "Connection Established",
 "merchant_id": "MER-980-APP-1",
 "request_id": "10034234",
 "ws_id": "20230604074816685e7def11c-6fd7-4aa9-ab13-2c9f0c22299d"
}

API Token must be encrypted with public key and passed in the request for establishing connection. Public key will be provided by NCHL. The encryption algorithm should be “RSA/ECB/PKCS1Padding”.