APIs Security
This section will explain how clients can add security in APIs and callback.
At Brick, security is our top priority. We are presenting world-class data security which has also been certified ISO/IEC 27001:2013, We are enabling recommendations from NIST's Federal Information Processing Standards (FIPS) with secure cryptography.
We have enabled security layers in both Incoming and Outgoing requests
- Incoming Request Validation
- Outgoing Request Validation
Incoming Request Validation(Client IP Whitelist)
Clients can enable the Incoming request validation and provide the list of Static IPs in brick dashboard, Based on enablement Brick system will only accept requests from the provided IPs.
Enablement of Incoming requests in up to clients, It's an Optional Step. If clients want to enhance the security then they can enable it from the Brick dashboard. But from the Brick side, it's always suggested to enable the security in Incoming Request Validation.
Explanation of edge cases
- Behavior-based on enablements
- If a client has enabled the IP Whitelist
- If the request is coming from the provided IP - Accept the request and Pass to the next step
- If the request is not coming from the provided IP - Reject the request with an error
{ "status":401, "error":{ "code": "ip_not_whitelisted" "message": "Request is not coming from whitelisted IP", "action": "Please use whitelist IPs or disabled whitelist functionality from Brick dashboard" "reason": "Source IP is not whitelisted in Brick servers" }, "metadata": { "source": {{API/Widget/Dashboard/SDK/Portal}}, "entity": "{{Auth}}" }, "data":null }
- If a client has not enabled the IP Whitelist
- No validation of source IPs in the API request
- If a client has enabled the IP Whitelist
- Client IP Validation will be available for all APIs, ie: Disbursement, Acceptance, or any other Payment APIs.
- Clients can manage configuration for Sandbox and Production, So by having separate configurations clients can test the feature in Sandbox environments.
- Clients can manage separate configurations for all Sub-Accounts, So it's up to clients to enable / Disable IP Whitelist for any Sub-account.
Management of Whitelist IPs
Client can enable Whitelist IPs from Brick Dashboard, Client can log in and will see the configuration section in the left panel. Under the configuration section, there will tab named as Callback URL. Clients can manage the whitelist IPs configuration under callback URL tab.
Once clients enable it then they can add a list of Static IPs from Brick Dashboard. Clients can provide up to 10 IPs.
Outgoing Request Validation
Clients can enable validation on Outgoing requests (Callbacks).
- Brick will provide the configuration in the dashboard for clients to enable security enhancement for outgoing requests.
- We will provide 2-factor encryption for clients in outgoing requests.
- First Encryption
- If clients have enabled security enhancement for outgoing requests (callback) then first encryptions will be automatically enabled.
- Clients have to provide the secret key in the dashboard.
- We will use SHA-256 encryption method.
- Second encryption (optional)
- If Clients want a second layer of encryption then they can enable it from the dashboard (please make sure first layer encryption is already enabled)
- If Clients have enabled the second layer of encryption then they have to download the public key from the Brick dashboard.
- We will use RSA Key 2048 Public-Private keys.
- First Encryption
Explanation of Details
-
Behavior-based on enablements
-
If outgoing request validation is disabled
- No change, Client will receive the raw data in callback request.
-
If Clients enable a single layer of encryption
-
Client can enable single layer encryption from Brick Dashboard, The Client can log in and will see the configuration section in the left panel. Under the configuration section, there will tab named Callback URL. Clients can manage the configuration under the callback URL tab.
- Clients need to add a secret key in the Brick dashboard and save the details.
- Clients also need to handle the validation flow in their system before enabling it from the Brick dashboard. Validation process is given below.
-
We will send two header keys in the callback, Below are the headers
- X-SIGNATURE - It is an encrypted value that will use during the validation process.
- X-TIMESTAMP - Timestamp of request
-
-
If clients enable a double layer of encryption
-
Client can enable callback signature encryption from Brick Dashboard, The Client can log in and will see the configuration section in the left panel. Under the configuration section, there will tab named Callback URL. Clients can manage the configuration under the callback URL tab.
- Double layer / Second layer of encryption will be implemented once first layer of encryption is already enabled.
- Clients need to download the Public key from the Brick dashboard.
- Clients also need to handle the validation flow in their system before enabling it from the Brick dashboard. Validation process is given below.
-
We will send two header keys in callback
- X-SIGNATURE - It is an encrypted value that will use during the validation process.
- X-TIMESTAMP - Timestamp of request
-
-
-
Outgoing Request Validation will be available for all APIs, ie: Disbursement, Acceptance, or any other APIs.
-
Clients can manage its configuration for Sandbox and Production, So by having separate configurations clients can test the feature in Sandbox environments.
-
Clients can manage separate configurations for all Sub-Accounts, So it's up to clients to enable / Disable Outgoing request validation for any Sub-account.
Process of Validation
-
Single layer encryption
-
When Client do a transaction using Brick API, they will receive a callback header & body (sample) as per the below example. Process of validation is below
- Clients needs to create one variable (i.e. message) via given Pattern
{{callback body}}|{{X-TIMESTAMP}}
- For the callback body inside that variable, convert into Escape JSON (\”value\”)
- Encrypt the variable (i.e. message) using the original Secret Key that clients input on Brick Dashboard for 1st Layer Encryption.
- If the message field matches with X-SIGNATURE from callback headers, It means that callback coming from Brick system and you can accept it, Otherwise feel free to reject it and inform to brick team.
Note - Please make sure that you will conduct the validation process at your backend system not on the client side system
header X-TIMESTAMP = "2006-07-17T15:04:05-07:00" X-SIGNATURE = "43e92fccd40c0b72b49ac0c015dc04b6e76bd8aac65065504a5e629adfa4b85a" request body { "data": { "id": "CL_5d3deb2d2fc24c7b84ed6066c909a87f", "referenceId": "nan-test-23", "description": "Test Initial VA Close", "amount": "10000", "status": "expired", "createdAt": "2024-07-17T12:38:11.000+07:00", "paymentId": "PAY_96d8e27937c4e9faa5c618da5b9e0755", "bankShortCode": "PERMATA", "accountNo": "7136010000013340", "displayName": "nanda test" } } message = "{\"data\":{\"id\":\"CL_5d3deb2d2fc24c7b84ed6066c909a87f\",\"referenceId\":\"nan-test-23\",\"description\":\"Test Initial VA Close\",\"amount\":\"10000\",\"status\":\"expired\",\"createdAt\":\"2024-07-17T12:38:11.000+07:00\",\"paymentId\":\"PAY_96d8e27937c4e9faa5c618da5b9e0755\",\"bankShortCode\":\"PERMATA\",\"accountNo\":\"7136010000013340\",\"displayName\":\"nanda test\"}}|2006-07-17T15:04:05-07:00"
- Clients needs to create one variable (i.e. message) via given Pattern
-
-
Double layer encryption
- Execute 1st layer encryption based on above. Afterward, you will obtain the encrypted result (let’s name it: 1st layer result)
- Encrypt 1st layer result using RSA Key 2048 Public key that you downloaded from Brick dashboard, then it will generate 2nd layer result
- If the 2nd layer result field matches with X-SIGNATURE from callback headers, It means that the callback coming from the Brick system and you can accept it, Otherwise feel free to reject it and inform to brick team.
Note - Please make sure that you will conduct the validation process at your backend system not on the client side system
Brick can also provide Static IP to clients so clients can whitelist in their system to validate the source of the callback. After the whitelisting, Clients should only accept callbacks from Brick Static IP
Updated 2 months ago