API Reference
Start typing to search…

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

StringUnique 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

ParameterDescriptionExample
ruleSuggestionString - Trident's risk suggestion based on the risk evaluation table configured for the calling application.ACCEPT
ruleRatingInteger - Total risk score for the transaction. Lower scores indicate higher risk.(-)60
clientIdString (UUID) - Unique transaction ID generated by Trident for tracking purposes.201809_86642221-1801-49aa-ad12-c409c0317451
stepUpString (true/false) - Indicates if additional authentication is recommended.true
nodeIdString - Server node identifier that processed the request.172.31.2.145::8443
frictionLessString (true/false) - Indicates if the transaction requires/does not require an additional factor of authentication.false
accIdAccount identifier associated with the transaction
idTransaction identifier (typically matches clientId)
observationsObject - 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_SUCCESS_INSTANCES_(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
        }
    ]
}