Dynamic Trigger Soundbox(With Encryption):
Introduction:
This API retrieves a payload from a bank server, validates it based on the bank name, and decrypts it if necessary. For plaintext payloads, it proceeds directly. It fetches mapping data (if applicable) or skips this step for banks without a database. The API publishes a message, triggers the soundbox to announce the transaction amount, and attempts to store the transaction in the history table. If storage fails, it pushes the data to Pub/Sub, except for banks without a database
Encryption/Decryption Flow:
This new flow follows a better security layer which includes payload as well as headers encryption-decryption.
1. Every API call will comprise of newly encrypted header_secrets and a pass_key in the headers and the encrypted payload with the response body also being encrypted using AES-256 encryption.
2. ISU team will share the Pass key, Client ID, Client Secret, API user name and Encryption Key for encrypting the Header Secrets and request-response Payload separately.
3. Every API call should comprise of two headers i.e. pass_key and header_secrets.
| Parameter | Description | Data_type |
|---|---|---|
| header_secrets | Encrypted header_secret containing client_id, client_secret and timestamp(Epoch) | String |
| pass_key | A separate pass_key for each client. | String |
4. The header_secrets is the encrypted header data which is a JSON body containing the client_id, client_secret and epoch, encrypted with an AES encryption key shared by ISU team.
5. The header_secrets JSON should contain the following data:
| Parameter Key | Description | Data_type |
|---|---|---|
| client_id | API user’s client_id, to be provided by ISU team. | String |
| client_secret | API user’s client_secret key, to be provided by ISU team. | String |
| epoch | A timestamp up to seconds e.g. 1727954878 | String |
1. Sample JSON header_secrets to be encrypted:
2. Every request payload should be encrypted using the same encryption Key used for header encryption using AES256 algorithm and should be shared in the following format:
The Client will get the below Response:
The above response payload needs to be decrypted using the same shared Encryption Key for Request-Response Payload.
Notes:
- A check has been implemented at the Gateway end where the epoch is validated and throws an epoch timeout error if the epoch is more than 5 mins old.
- Encrypt the header JSON data using the Encryption Key for Header Secrets using AES256 algorithm and share it in the header_secrets key in the header. It is required to generate every time while consuming the API. In Header also required to send a pass_key which is shared by the API Gateway team.
- The key that will be used to encrypt the payload and header_secrets are the same.
- While the same key can be used to decrypt the response JSON.
- AES Encryption key will be client specific i.e. separate for each client.
- Algorithms for the encryption and decryption will be shared from the API Gateway team separately.
- Only the success responses will be sent in an encrypted format from the gateway end, other responses will be sent in normal JSON or as it is.
Client Specific Keys:
| Clients | Header Encryption, AES Keys | Payload Encryption and Decryption AES Keys |
|---|---|---|
| Client A |
|
Key a |
| Client B |
|
Key b |
| Client C |
|
Key c |
| Client D |
|
Key d |
Sample Curl Command:
curl --location 'https://api-preprod.iserveu.tech/encrV2/apiuser/user/endpoint' \
--header 'header_secrets: pl1S9rCtOH1/
kGkGNSfBSC3913SuEMq39syKL0OPC435bqZNq7wvn8lqbRnkbWchSRoFD72UM8CYmie5UGQrZh8y57Jw
mGubQT/SIGy7tYkWEu/
14MvpxX2oB4uNRuIYLrJD2zL0WA1gNM0+EHko0x9kfDXP1jF7IKubah9F9RkEOvzUJaI+hFQ3qrDv9vE57JLw
ecYG1/V/8irDvmRJug==' \
--header 'pass_key: l29o3OZFWoE8qEKah9rnrNEvquSytJqEKah9DVEPVR' \
--header 'Content-Type: application/json' \
--data '{
"RequestData":
"S7klEFPI7bWmnTB7FrFIO4YVx7Hu982zVUMAWOBGvXEiRVyKO1RyGNS0huzvBeuvQJFRkCnkbWchSRoFD
72UM8CYmie5UGQrZh8y57JwmGubQT/SIGy7tYkWEu/
14MvpxX2oB4uNRuIeq4tLEkjP5DcaWNg60ODFmaZiDznK1Q0RfmwI="
}'
Dynamic Trigger Soundbox:
Headers
Columns with values:
Request Body Parameters
| Field Name | Description | Data type | Mandatory/Optional/ Conditional |
| column1 | Transaction id E.g. - 7656789878ee |
VARCHAR | Mandatory |
| column3 | tid(device serial no.) E.g. - 123456787654 |
VARCHAR | Optional |
| column7 | language E.g. - ENGLISH |
VARCHAR | Optional |
| column8 | Transaction amount, you have to give in format like rupees.paisa(19.00) E.g. - 19.00 |
VARCHAR | Mandatory |
| column12 | Transaction type E.g. - UPI,mATM,POS |
VARCHAR | Optional |
| column15 | status E.g. - success||failed |
VARCHAR | Mandatory |
| column2 | mid E.g. - test@isu |
VARCHAR | Mandatory |
Sample Request Body
Response Body Parameters
| Parameters | Description | Data type |
| status | Status category (0/1). success = 0, failed = 1 | VARCHAR |
| message | Response message (success/fail) | VARCHAR |
| statusDesc | Status Description | VARCHAR |
| data | Fetched Data | VARCHAR |
Sample Response Body
SUCCESS:
Failed cases:
If merchant_vpa is missing:
In case the device is not active:
Error in the case of publishing a message:
Error getting YPP external server error:
Invalid Device type:
Response Status Codes
| Status Code | Status | Description | HTTP Status Code |
| 0 | SUCCESS | Message successfully sent | 200 |
| 1 | FAILED |
|
400 |
Error Codes and Description:
| Error Codes | Error Description |
| ERR0001 | If merchant_vpa is not found in the database. |
| ERR0002 | Device is not active |
| ERR0003 | Database Error |
| ERR0004 | Error while publishing |
| ERR0005 | Unhandled server error |
| ERR0006 | YPP server error |
| ERR0007 | Invalid device type |
| ERR0008 | Invalid Base url |
