Analyse API

Trident's Analyse API is used to perform Risk analysis using the data, that is, transaction and user profile details shared by the Calling application. Clients or banks can call Trident Analyse API before sending transaction to the network (VISA, Mastercard, NPCI, etc.) to get the risk recommendation (within 100 milliseconds).

Endpoint

Endpoint URL Format: <domainname>/analyse/request
Example Endpoint URL:

http://127.0.0.1:8443/analyse/request

Method: POST
Content-Type: application/json

Request Parameters

Parameter	Description	Example
instanceId `mandatory`	`String (4 digits)` - Instance ID is provided (four-digit) during client onboarding. This is a fixed value in all the requests.	8888
channelId `mandatory`	`String (Alphanumeric)` - Payment channel - cards, P2P/UPI, Net Banking, BNPL, wallets or non-financial. Acceptable values are provided during client onboarding.	3DS
txnSourceType `mandatory`	`String (Alphanumeric)` - Sub-category of payment channel. For example, for cards channel, transaction source type can be Credit Card, Debit Card or Prepaid Card. Acceptable values are provided during client onboarding.	Purchase
async `mandatory`	`String (true/false)` - Determines communication mode. The values can be: false (default): Analyze API is working in synchronous mode. Calling application must wait for the response from Trident (P99 of 100 ms). true: Analyze API is working in asynchronous mode. Trident can process multiple requests at the same time. This allows time-consuming requests to be processed in the background while smaller requests are serviced immediately.	false
details `mandatory`	`String (true/false)` - Request for a detailed risk analysis output. The values can be: false (default): - Trident provides a summarized risk analysis result. true - Trident provides detailed risk analysis. For the list of response parameters for each of this scenario, refer to Response parameters .	false
partRequest `mandatory`	`String (true/false)` - Whether full evaluation data in this request (or part). The values can be any of the following: false - Evaluation data shared in this request is not in multi part format. true - Evaluation data shared in this request is in multi part format.	false
lastDrop `mandatory`	`String (true)` - Always set to true.	true
acctNumber `mandatory`	`String (Alphanumeric)` - Unique payment instrument ID. For example, card number for card transactions or payer VPA for UPI transactions.	4346781238815413
txnTimestamp `mandatory`	`String (yyyyMMddHHmmss)` - UTC timestamp of the transaction.	20231015123045
clientTxnRefId `mandatory`	`String (Alphanumeric)` - Unique ID for the transaction created by the client's system.	TXN12345UNIQUE
purchaseAmount `mandatory`	`String (Amount in minor unit)` - Purchase amount of the transaction. Expressed in minor unit/implied decimal format. For example, a purchase amount of rupees one hundred and 50 paisa is expressed as 10050.	10050
purchaseCurrencyCode `mandatory`	`String (Alphanumeric)` - ISO 4217 currency code for the purchase amount.	356 for INR
Custom parameters
merchantId `optional`	`String (Alphanumeric)` - Unique ID for the merchant.
merchantName `optional`	`String (Alphanumeric)` - Name of the merchant.	John Doe
merchantCountryCode `optional`	`String (3-digit numeric code)` - Merchant's country ISO 3166 code.	356
ip `optional`	`String (IPV4 or IPV6)` - Customer's IP address.	172.27.0.1 or FE80:CD00::211E:729C
customerName `optional`	`String (Alphanumeric)` - Customer name.	Joe Doe
customerMobile `optional`	`String (Numeric)` - Customer's mobile number.	9123456789
customerEmail `optional`	`String (Alphanumeric)` - Customer's email ID.	[email protected]

📘
Custom parameters:
Trident supports any number of additional custom parameters on the basis of client use case. Exact list of parameters are agreed with the client during onboarding.

Sample request

curl -X POST "http://127.0.0.1:8443/analyse/request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "instanceId": "8888",
    "channelId": "3DS",
    "async": "false",
    "details": "true",
    "txnSourceType": "Purchase",
    "partRequest": "true",
    "lastDrop": "true",
    "acctNumber": "4346781238815413",
    "txnTimestamp": "20231015123045",
    "ip": "172.27.0.1",
    "merchantCountryCode": "356",
    "purchaseAmount": "10000",
    "cardType": "Debit",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    "mobileNumber": "9123456789",
    "clientTxnRefId": "TXN12345UNIQUE"
  }'

Response parameters

When details = false

Parameter	Description	Example
nodeID	`String` -Server node identifier that processed the request.	172.31.2.145::8443
clientId	`String (UUID)` - Unique transaction ID generated by Trident.	201809_86642221-1801-49aa-ad12-c409c0317451
ruleRating	`Integer` - Total risk score for the transaction. Lower scores indicate higher risk.	(-)60
ruleSuggestion	`String` - Trident's risk suggestion based on the risk evaluation table configured for the calling application.	ACCEPT
stepUp	`String` (true/false) - Indicates if additional authentication is recommended.	true
accId	`String`Unique identifier associated with the transaction eg. 3DS is 16 digit Card Number
id	Transaction identifier (typically matches clientId).	20250610101345_1777_3DS_fbc9fe7e-c769-4812-84bc-3df7f87afb9e
observationSummary	`JSON` - Contains pairs of triggered rules along with their corresponding scores in a key-value format. For more information, refer to observationSummary JSON object Note: The key-value pair in this JSON object are rules and respective score which was applied for the specific transaction. Hence, the list of key-value pairs are dynamic and will be different for each transaction.	Refer to observations JSON object

observationSummary JSON object

Sample object

"observationSummary": {
        "FirstTimeMerchant": "-30",
        "FirstTimeBrowser": "-30",
        "FirstTransaction": "-30",
        "MCM3": "-95",
        "FirstTimeIP": "-30",
        "LowAmountTransaction": "10"
    }

When details = true

Parameter	Description	Example
ruleSuggestion	`String` - Trident's risk suggestion based on the risk evaluation table configured for the calling application.	ACCEPT
ruleRating	`Integer` - Total risk score for the transaction. Lower scores indicate higher risk.	(-)60
clientId	`String (UUID)` - Unique transaction ID generated by Trident for tracking purposes.	201809_86642221-1801-49aa-ad12-c409c0317451
stepUp	`String (true/false)` - Indicates if additional authentication is recommended.	true
nodeId	`String` - Server node identifier that processed the request.	172.31.2.145::8443
frictionLess	`String (true/false)` - Indicates if the transaction requires/does not require an additional factor of authentication.	false
accId	Account identifier associated with the transaction
id	Transaction identifier (typically matches clientId)
observations	`Object` - Gives the observation summary. Contains an array object of all the rules executed for the transaction, where each object details a particular rule which was executed. This is in key-value format. For more information, refer to observations JSON object.	Refer to observations JSON object

observations JSON object

Sample object

"observations":[
        {
            "ratingAdded": 0,
            "requestId": "1",
            "ruleName": "3DS31_multiple failed txn on card",
            "ruleId": "RULE::1777::3DS::1743771871100",
            "observation": "'cardNo' COUNT_IN_TIME_FAILED_PRIMARY_ID_MIN 'cardNo|5|5' = false ",
            "analyzedData": " cardNo EVALUATE_TRANSACTION COUNT|cardNo|>=|5|ALL|FAILURE|5|MIN Count = 0;",
            "clientId": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
            "comment": null,
            "falseAlarm": null,
            "exceptionCase": 0,
            "startTime": 1749531409843,
            "endTime": 1749531409843,
            "mode": 1,
            "instanceId": "1777",
            "cardPrefix": null,
            "ttl": 0,
            "timestamp": null,
            "exceptionDetail": null,
            "methodType": "",
            "monthName": "",
            "ruleAliasName": "3DS31",
            "description": "count of failed txns attempts for the same card. >=5 in 5 min",
            "policyDecision": null,
            "policyDecisionLevel": null,
            "authMode": null,
            "observationData": {},
            "isHour": null,
            "blockEntityList": "",
            "entityBlockUpto": null,
            "blockedRule": false,
            "extimatedTimeTaken": 0
        },
        {
            "ratingAdded": 10,
            "requestId": "1",
            "ruleName": "3DS015",
            "ruleId": "RULE::1777::3DS::1707288825777",
            "observation": "'purchaseAmount' <= '150000' = true 'purchaseAmount' >= '1000' = true ",
            "analyzedData": "",
            "clientId": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
            "comment": null,
            "falseAlarm": null,
            "exceptionCase": 0,
            "startTime": 1749531409854,
            "endTime": 1749531409854,
            "mode": 1,
            "instanceId": "1777",
            "cardPrefix": null,
            "ttl": 0,
            "timestamp": null,
            "exceptionDetail": null,
            "methodType": "",
            "monthName": "",
            "ruleAliasName": "LowAmountTransaction",
            "description": "Low Amount Transaction >=10 INR and Less than = 1500 INR",
            "policyDecision": null,
            "policyDecisionLevel": null,
            "authMode": null,
            "observationData": {},
            "isHour": null,
            "blockEntityList": "",
            "entityBlockUpto": null,
            "blockedRule": false,
            "extimatedTimeTaken": 0
        }
    ]

Field descriptions

Field	Description	Example Value
ruleName	The name of the rule which was executed	3DS023
ruleId	The unique rule identifier	RULE::1777::3DS::1707280384671
ruleAliasName	Alias to the rule with a rule name	FirstTimeMerchant
description	The description of the configured rule	First ever transaction on Merchant id from card.
ratingAdded	The rule score being added to the overall score. This rule rating will be weighed by the exemption weight applied from rule exemption.	-30
requestId	Deprecated	1
startTime	The rule execution start time. This is in Unix time format.	1748511188668
endTime	The rule execution end time. This is in Unix time format.	1748511188669
estimatedTimeTaken	The estimated time taken in executing the rule	1
observation	The output of the rule execution whether it has been triggered or not.	'merchantId' COUNT_PAST_SUCCESS_INSTANCES_PRIMARY_ID 'cardNo\|==\|0' = true
analyzedData	This parameter will be dependent on the rule operator being used. If analyze Data is available in the operator then the running value of the count/sum will be shown.	COUNT_PAST_SUCCESSINSTANCES(cardNo)= :0
clientId	Unique transaction ID generated by Trident for tracking purposes.	20250529150308_1777_3DS_1b7f16bf-42c8-4982-831b-47243e9afa05
comment	Deprecated
falseAlarm	Deprecated
exceptionCase	This flag identifies whether the rule was exempted by using rule exemptions. If the flag 1 then the rule is exempted or if the flag is 0 there is no rule exemption.	0
mode	Identifies whether the rule is running in: 1: Live mode 0: Test mode Only scores of live rules are considered for total risk score of the transaction.	1
instanceId	Trident instance identifier that identifies the instance setup to analyze risk for a particular client.	1777
cardPrefix	The prefix of the card for issuer use cases	9804
ttl	The time to live period of the observation	0
timestamp	The time stamp when the rule was triggered in server. This is in UNIX format.	1748511188668
exceptionDetail	The error code object is shown if rule is not executed correctly	Rule Not Executed correctly
methodType	Deprecated
monthName	Deprecated
policyDecision	Deprecated
policyDecisionLevel	Deprecated
authMode	Deprecated
isHour	Indicates if it is an hourly rule.	true/false
blockEntityList	Block entity list in rule level	Block
entityBlockUpto	Entity block expiry in rule level	6/6/2025 20:20
blockedRule	Deprecated

Sample response

When details = false

{
    "nodeId": "192.168.108.191::8095",(Add)
    "clientId": "20250610101345_1777_3DS_fbc9fe7e-c769-4812-84bc-3df7f87afb9e",
    "ruleRating": -205,
    "ruleSuggestion": "DENY",
    "stepUp": "true",(Add)
    "accId": "null",(Add)
    "id": "20250610101345_1777_3DS_fbc9fe7e-c769-4812-84bc-3df7f87afb9e"(Add),
    "frictionLess": "false"(Add),
    "observationSummary": {(Add)
        "FirstTimeMerchant": "-30",
        "FirstTimeBrowser": "-30",
        "FirstTransaction": "-30",
        "MCM3": "-95",
        "FirstTimeIP": "-30",
        "LowAmountTransaction": "10"
    }
}

When details = true

{
    "nodeId": "192.168.108.191::8095",
    "clientId": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
    "ruleRating": -205,
    "ruleSuggestion": "DENY",
    "stepUp": "true",
    "accId": "null",
    "id": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
    "frictionLess": "false",
    "observations":[
        {
            "ratingAdded": 0,
            "requestId": "1",
            "ruleName": "3DS31_multiple failed txn on card",
            "ruleId": "RULE::1777::3DS::1743771871100",
            "observation": "'cardNo' COUNT_IN_TIME_FAILED_PRIMARY_ID_MIN 'cardNo|5|5' = false ",
            "analyzedData": " cardNo EVALUATE_TRANSACTION COUNT|cardNo|>=|5|ALL|FAILURE|5|MIN Count = 0;",
            "clientId": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
            "comment": null,
            "falseAlarm": null,
            "exceptionCase": 0,
            "startTime": 1749531409843,
            "endTime": 1749531409843,
            "mode": 1,
            "instanceId": "1777",
            "cardPrefix": null,
            "ttl": 0,
            "timestamp": null,
            "exceptionDetail": null,
            "methodType": "",
            "monthName": "",
            "ruleAliasName": "3DS31",
            "description": "count of failed txns attempts for the same card. >=5 in 5 min",
            "policyDecision": null,
            "policyDecisionLevel": null,
            "authMode": null,
            "observationData": {},
            "isHour": null,
            "blockEntityList": "",
            "entityBlockUpto": null,
            "blockedRule": false,
            "extimatedTimeTaken": 0
        },
        {
            "ratingAdded": 10,
            "requestId": "1",
            "ruleName": "3DS015",
            "ruleId": "RULE::1777::3DS::1707288825777",
            "observation": "'purchaseAmount' <= '150000' = true 'purchaseAmount' >= '1000' = true ",
            "analyzedData": "",
            "clientId": "20250610102649_1777_3DS_1bd33ea1-7eb5-49be-b737-c89017efa345",
            "comment": null,
            "falseAlarm": null,
            "exceptionCase": 0,
            "startTime": 1749531409854,
            "endTime": 1749531409854,
            "mode": 1,
            "instanceId": "1777",
            "cardPrefix": null,
            "ttl": 0,
            "timestamp": null,
            "exceptionDetail": null,
            "methodType": "",
            "monthName": "",
            "ruleAliasName": "LowAmountTransaction",
            "description": "Low Amount Transaction >=10 INR and Less than = 1500 INR",
            "policyDecision": null,
            "policyDecisionLevel": null,
            "authMode": null,
            "observationData": {},
            "isHour": null,
            "blockEntityList": "",
            "entityBlockUpto": null,
            "blockedRule": false,
            "extimatedTimeTaken": 0
        }
    ]
}