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
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.	201809_86642221-1801-49aa-ad12-c409c0317451
observationSummary	`JSON` - List of risk evaluations

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` - Contains pairs of triggered rules along with their corresponding scores in a key-value format. For more information, refer to observations JSON object	Refer to observations JSON object
exceptions	`Array` - List of exceptions encountered during processing, if any.	[401 501]

observations JSON object

Sample object

"observations": [
{
"ratingAdded": -1000,
"requestId": "1",
"ruleName": "CARD5COUNTRY",
"ruleId": "RULE::1999::3DS::1619763562147",
"observation": "merchantCountry New Value FIRST_ENTITY_VALUE_CHANGE",
"analyzedData": "cardNo, New Value(merchantCountry):UK",
"clientId": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
"comment": null,
"falseAlarm": null,
"exceptionCase": 0,
"startTime": 1619802131631,
"endTime": 1619802131676,
"mode": 1,
"instanceId": "1999",
"cardPrefix": null,
"ttl": 0,
"timestamp": null,
"exceptionDetail": null,
"methodType": "",
"monthName": "",
"ruleAliasName": "CARD5COUNTRY",
"description": "CARD5COUNTRY",
"policyDecision": null,
"policyDecisionLevel": null,
"authMode": null,
"observationData": {},
"isHour": null,
"blockEntityList": "",
"entityBlockUpto": null,
"blockedRule": false,
"extimatedTimeTaken": 45
}

Field descriptions

Field	Description	Example
ratingAdded	The risk score value added by this rule evaluation. Negative values indicate higher risk.	-1000
requestId	Identifier for the transaction request	1
ruleName	Name of the rule that was evaluated	CARD5COUNTRY
ruleId	Unique identifier for the rule in format RULE::{instanceId}::{moduleId}::{timestamp}	RULE::1999::3DS::1619763562147
observation	Brief description of the rule observation result	merchantCountry New Value FIRST_ENTITY_VALUE_CHANGE
analyzedData	Detailed information about the data analyzed by the rule	cardNo, New Value(merchantCountry):UK
clientId	Unique identifier for the client/transaction	20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642
comment	Optional comment added to this rule observation	null
falseAlarm	Indicates if this rule observation was marked as a false alarm	null
exceptionCase	Indicates if this rule observation is an exception case (0 = not an exception)	0
startTime	Timestamp when rule evaluation started (in milliseconds since epoch)	1619802131631
endTime	Timestamp when rule evaluation ended (in milliseconds since epoch)	1619802131676
mode	Operational mode of the rule (0 = monitoring, 1 = enforcement)	1
instanceId	Identifier for the system instance	1999
cardPrefix	Card number prefix for bank identification	null
ttl	Time-to-live value for caching (in seconds)	0
timestamp	Alternative timestamp field	null
exceptionDetail	Detailed information if an exception occurred during rule evaluation	null
methodType	Type of method used for the transaction	(empty string)
monthName	Name of the month for periodic rule evaluations	(empty string)
ruleAliasName	Alternative name/alias for the rule	CARD5COUNTRY
description	Description of the rule's purpose	CARD5COUNTRY
policyDecision	Decision made by the policy engine	null
policyDecisionLevel	Level at which the policy decision was made	null
authMode	Authentication mode used for the transaction	null
observationData	Additional structured data from the rule observation	{}
isHour	Hour specification for time-based rules	null
blockEntityList	List of entities to block based on this rule	(empty string)
entityBlockUpto	Duration until the entity remains blocked (in minutes)	null
blockedRule	Indicates if this rule resulted in an entity block	false
extimatedTimeTaken	Estimated processing time for the rule evaluation (in milliseconds)	45

Sample response

When details = false

{
  "clientId": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
  "ruleRating": -1000,
  "ruleSuggestion": "DENY",
  "id": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
  "observationSummary": 
  {
        "FirstTimeMerchant": "-30",
        "FirstTimeOperatingSystem": "-30",
        "FirstTimeIP": "-30",
        "LowAmountTransaction": "20"
  }
}

When details = true

{
  "nodeId": "127.0.0.1::8088",
  "clientId": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
  "ruleRating": -1000,
  "ruleSuggestion": "DENY",
  "stepUp": "true",
  "accId": "null",
  "id": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
  "frictionLess": "false",
  "observations": [
    {
      "ratingAdded": -1000,
      "requestId": "1",
      "ruleName": "CARD5COUNTRY",
      "ruleId": "RULE::1999::3DS::1619763562147",
      "observation": "merchantCountry New Value FIRST_ENTITY_VALUE_CHANGE",
      "analyzedData": "cardNo, New Value(merchantCountry):UK",
      "clientId": "20210430182211_1999_3DS_1a9cc7f1-dfe4-40b7-b9a7-c3fb0e4e3642",
      "comment": null,
      "falseAlarm": null,
      "exceptionCase": 0,
      "startTime": 1619802131631,
      "endTime": 1619802131676,
      "mode": 1,
      "instanceId": "1999",
      "cardPrefix": null,
      "ttl": 0,
      "timestamp": null,
      "exceptionDetail": null,
      "methodType": "",
      "monthName": "",
      "ruleAliasName": "CARD5COUNTRY",
      "description": "CARD5COUNTRY",
      "policyDecision": null,
      "policyDecisionLevel": null,
      "authMode": null,
      "observationData": {},
      "isHour": null,
      "blockEntityList": "",
      "entityBlockUpto": null,
      "blockedRule": false,
      "extimatedTimeTaken": 45
    },
    // Additional observations truncated for brevity
  ]
}

Endpoint

Request Parameters

📘Custom parameters:

Sample request

Response parameters

When details = false

When details = true

observations JSON object

Sample object

Field descriptions

Sample response

When details = false

When details = true

📘
Custom parameters: