evaluate API
evaluate API
aa82test
This API call evaluates risk associated with this transaction and returns an advice accordingly. The risk evaluation is based on various factors including the DeviceID, the IP address of user machine, MFP signature collected from user machine. It provides a RiskAdvice and a new DeviceID.
Actions to be taken by the calling application:
- The output DeviceID should be stored on user machine in some form. A common way is storing it as an HTTP cookie. HTTP cookies risk being deleted when user deletes all of the cookies on the computer.
- Retrieve the DeviceID from user machine and set it using setDeviceID.
- If RiskAdvice is equal to INCREASEAUTH, perform secondary authentication and pass the results of the secondary authentication to RiskFort using PostEvaluate.
To evaluate risk, send a POST request to the following URL:
http://REST Server: REST Server Port/ risk-restapi/ca/advanced-auth/risk/evaluate
Method
POST
Headers
- Content-Type: application/ld+json (required)
JSON Payloads
evaluate Request
{ "callerId": "string", "deviceId": { "type": "string", "value": "string" }, "deviceSignature:": "string", "ipAddress": "string", "action": "string", "channel": "string", "orgName": "string", "userId": "string", "additionalInput": [ { "name": "string", "value": "string" } ] }
In the evaluate request JSON payload, all the parameters other than 'userId' are optional.
evaluate Response - Success
{ "deviceId": "string", "riskAdvice": "string", "riskScore": "integer", "ruleAnnotation": "string", "matchedRuleMnemonic": "string", "transactionId": "string", }
The following table describes the items that are returned:
Item | Description |
deviceId | The deviceIdCookie which is stored in user machine browser. Generated by the CA Risk Authentication Server. |
riskAdvice | One of the following:
|
riskScore | An interger indicating the level of risk calculated by the product. Typically 0 through 100. |
ruleAnnotation | The result of execution of all rules (or the reason for score and advice). |
matchedRuleMnemonic | The rules that matched and the reason that the product marked the transaction as a risk. |
transactionID | A unique identifier for the response. |
- A header token named 'pss' sends back the 'state' information that must be passed between evaluate and post evaluate.This is the state token header that must be passed back to postEvaluate in order to tie the two calls together.
Example Responses
The following shows an example of a successful evaluate call using the Accept:application/json HTTP header:
{ "deviceId": "m9qKeGgwXt0JuFPe5q9FFOodZdNUvHGXgABukQnZjlGa9dK/Fz53unCWESAVkE1C", "riskAdvice": "ALERT", "riskScore": 50, "ruleAnnotation": "UNKNOWNUSER=Y;MFPMISMATCH=Y;UNKNOWNDEVICEID=Y;USERDEVICENOTASSOCIATED=Y;EXCEPTION=N;TRUSTEDIP=N;UNTRUSTEDIP=N;USERVELOCITY=N;DEVICEVELOCITY=N;", "matchedRuleMnemonic": "UNKNOWNUSER", "trasactionID": "1:123" "_links": { "self": { "href": "http://localhost:8080/risk-restapi/ca/advanced-auth/risk/evaluate" }, "postEvaluate": { "href": "http://localhost:8080/risk-restapi/ca/advanced-auth/risk/postEvaluate" } } }
The following shows an example of a successful evaluate call using the Accept:application/ld+json HTTP header:
{ "@context": { "@vocab": "http://schema.org/", "hydra": "http://www.w3.org/ns/hydra/core#", "schema": "http://schema.org" }, "@type": "EvaluateRiskResponse", "deviceId": "tbac4rK42V+3bVp8HMGOlhIZBTOKmHQOosjtcb3JmpNc2dVWgU2IE6SqT8xIratq", "riskAdvice": "ALERT", "riskScore": 50, "ruleAnnotation": "UNKNOWNUSER=Y;MFPMISMATCH=Y;UNKNOWNDEVICEID=Y;USERDEVICENOTASSOCIATED=Y;EXCEPTION=N;TRUSTEDIP=N;UNTRUSTEDIP=N;USERVELOCITY=N;DEVICEVELOCITY=N;", "matchedRuleMnemonic": "UNKNOWNUSER", "trasactionID": "1:123" "@id": "http://localhost:8080/risk-restapi/ca/advanced-auth/risk/evaluate", "hydra:operation": [ { "@type": "EvaluateRiskAction", "hydra:method": "POST", "hydra:expects": { "@type": "EvaluateRiskRequest", "hydra:supportedProperty": [ { "hydra:property": "action" }, { "hydra:property": "additionalInput", "rangeIncludes": { "rdfs:subClassOf": "List", "hydra:supportedProperty": [] } }, { "hydra:property": "callerId" }, { "hydra:property": "channel" }, { "hydra:property": "deviceId", "rangeIncludes": { "rdfs:subClassOf": "DeviceID", "hydra:supportedProperty": [ { "hydra:property": "type" }, { "hydra:property": "value" } ] } }, { "hydra:property": "deviceSignature" }, { "@type": "PropertyValueSpecification", "hydra:property": "ipAddress", "valuePattern": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$" }, { "hydra:property": "orgName" }, { "@type": "PropertyValueSpecification", "hydra:property": "userId", "valueMaxLength": 256, "valueMinLength": 1 } ] } } ], "postEvaluate": { "@id": "http://localhost:8080/ca/advanced-auth/risk/postEvaluate", "hydra:operation": [ { "@type": "PostEvaluateRiskAction", "hydra:method": "POST", "hydra:expects": { "@type": "PostEvaluateRiskRequest", "hydra:supportedProperty": [ { "hydra:property": "additionalInput", "rangeIncludes": { "rdfs:subClassOf": "List", "hydra:supportedProperty": [] } }, { "hydra:property": "associationName" }, { "hydra:property": "secondaryAuthenticationStatus" } { "hydra:property":"transactionId" } ] } } ] } }
evaluate Response - Error
{ errorCode: <string>, errorSubcode: <string>, errorMessage: <string> }
Where:
- Error Responses are returned only in cases where the HTTP status response code is not 200
- The current Java APIs pass back the errorCode and sometimes pass back the errorSubcode
Response Codes and Error Messages
HTTP Response Codes
Code | Reason | Notes |
200 | Success | |
400 | Invalid Request | Any Java SDK error |
Error Messages
See API Error Messages for a list.