OneSpan Developer: Transaction Validation Endpoint

Hakim Aldaoub, December 9, 2020
OneSpan Developer: Transaction Validation Endpoint

OneSpan Intelligent Adaptive Authentication (IAA) offers the Transaction Validation endpoint to handle monetary events in an adaptive way. Whenever a request is triggered towards Transaction/Validate API, Risk Analytics (RA) will respond to capture the appropriate authentication method of the end-user, based on the risk associated with the transaction. In today’s blog, we will explain how to prepare the request for a monetary transaction using the Sandbox Interactive API and show the possible RA responses to that event. 

Before We Begin

Prior to exploring the Transaction Validation endpoint, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Check out our previous blog, OneSpan Cloud Solutions In Action - MyBank Web Portal Demo, Part 1 for instructions on how to do so.

You should also be sure to have at least one registered user prior to trying this call. To learn how to register a user, check out “OneSpan Developer: Intelligent Adaptive Authentication - User Registration".

Endpoint URL

The request URL for this API call will resemble the example below:

https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users/
{[email protected]}/transactions/validate

You won’t need to provide this URL during the tutorial. It is only to show the structure of the URL. The URL will be automatically assigned in the Interactive API when calling the webservice. 

Try It Out

In order to experiment with the Transaction Validation API, navigate to the IAA Sandbox Interactive API document in your OneSpan Community account. In the Open API Swagger editor, expand the “Transactions” resource. You will then find an entry for the Transactions/Validate HTTP Post method as shown in the image below:  

OneSpan-BlogImage[Transaction-Validation-Endpoint]1

URL Path Parameters:

For the purpose of the Transaction/Validate API call, there is a required path parameter for the unique user identifier. It will be formatted as [email protected] An example of the userID is “iaa_user”. It is the userID that has been activated on the trusted device. The portion of the parameter following the “@” sign is the user domain. This entry should be replaced with the “Sandbox User” string shown below, which is present in your Sandbox details section under the “Intelligent Adaptive Authentication” tab of your Sandbox homepage.

OneSpan-BlogImage[Transaction-Validation-Endpoint]2

Transaction Validation Request Body

Under the “Request Body” section of the Transaction/Validate endpoint, select "AdaptiveTransactionValidationInput" object type from the dropped down menu as shown below. You will then get an example of the JSON request payload required by the Transaction Validation endpoint

OneSpan-BlogImage[Transaction-Validation-Endpoint]3

The request body will look like the example below of the Transaction/Validate endpoint’s required fields.
{
  "objectType": "AdaptiveTransactionValidationInput",
  "accountRef": "ACC123",
  "amount": "1064.99",
  "cddc": {
    "browserCDDC": {
      "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}",
      "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7"
    }
  },
  "currency": "EUR",
  "data": {
    "transactionMessage": {
      "dataFields": [
        {
          "key": {
            "text": "Transaction Value"
          },
          "value": {
            "text": "EUR 1064.99"
          }
        }
      ]
    }
  },
  "relationshipRef": "iaa_user",
  "sessionID": "4ed23ea44f23",
  "transactionType": "ExternalTransfer",
  "clientIP": "192.168.0.1",
  "creditorBank": "MYBANK",
  "creditorIBAN": "BE68539007547034",
  "creditorName": "John Doe",
  "creditorOtherInstruction": "0",
  "debtorIBAN": "BE71096123456769",
  "timeout": 60
}

Request Payload

It contains two mandatory JSON objects shown in the table:

JSON Required Data Fields Description Field Data Type
objectType* This is to declare the object type for the transaction in the request payload is for the purpose of Intelligent Adaptive Authentication solution.

Type: Enum

Example: “[ AdaptiveTransactionValidationInput]”

accountRef*


Reference to the bank account of the customer making the transaction

Type: JSON nested object
minLength: 1
maxLength: 250
Example: Checking_Account_CH53
amount* The amount value of the transaction Type: string
pattern: ^-?[0-9]{1,10}(\.[0-9]{1,2})?$
example: 999.99
cddc* Client Device Data Collector meta data. The two fields browserCDDC and mobileCDDC are mutually exclusive and collectively exhaustive. Type: string
Example: “browserCDDC” or “mobileCDDC”
relationshipRef* The Relationship reference of the user ID. Type: string
minLength: 1
maxLength: 150
Example: iaa_user
staticPassword* The initial static password assigned to the user. Type: string
minLength: 8
maxLength: 255
example: Test1234
sessionID* Application session identifier formatted as a hexadecimal string; common for all transactions related to the same session Type: string
pattern: ^[0-9a-fA-F]+$
minLength: 2
maxLength: 100
example: 4ed23ea44f23
transactionType* This crucial field specify the transaction type to be sent in the request. Defining the transaction type will allow the flexibility for the different transaction to be handled uniquely from Risk Analytics side Type: string
Example: ExternalTransferBillPayments,
MobileInternalTransfer

Calling the Endpoint

At this point, we are ready to make a RESTful call to the Transaction/Validate endpoint using the IAA interactive Sandbox API. To make the call, click on the “Try it out” button shown in the screenshot below and located to the right of the HTTP POST method section. Once requested, you will receive the response body back in a JSON format. It will be similar to the response payload described in the following section.

OneSpan-BlogImage[Transaction-Validation-Endpoint]4

Response Payload

Below is an example of the returned response body with a 200 response code which indicates a successful transaction.
{
  "requestID": "413b2c39-2d67-4293-9adb-25601731b062",
  "riskResponseCode": 0,
  "sessionStatus": "accepted",
  "requestMessage": "0000F8B81D"
}

Response Body Fields’ Description

The “requestID” is the first field in the response, it is a string of 36 characters used to keep a reference of the preceding API call. This ID could be useful for debugging and referencing.

The “riskResponseCode” field is the response code from Risk Analytics. The value ‘0’ in the response above indicates that the request was accepted and the user had been authenticated successfully without any extra measures required. Below is a list of other possible values that can be returned by Risk Analytics. Also, additional values can be configured through the Risk Analytics Presentation Service.

Risk Analytics Behaviour Risk Response Code (Integer)
Accept 0
Decline 1
Challenge 2
ChallengeSMS 3
ChallengeDevice2FA 5
ChallengeEmail 8
ChallengeCronto 11
ChallengeNoPIN 21
ChallengePIN 22
ChallengeFingerprint 23
ChallengeFace 24

The “sessionStatus" field in the JSON response represents the current status of the session after the request has been sent, the table below list the possible status values.

Session Status Status Description
unknown The status unknow and the response is being handled externally
pending Awaiting an action from the end-user
accepted Successfully completed
refused Refused by the end-user
timeout Timed out after no response was received within the time frame
failed The OTP validation fail

The "requestMessage" field is of type String. It is used to transmit an orchestration command to the end user trusted device.

In this blog, we covered how to make a monetary transaction through the OneSpan Interactive API. In the upcoming weeks, we will see other blogs that relate to the Transaction/Validate endpoint. Meanwhile, if you have any questions, feel free to reach us on the OneSpan Community Portal Forums.

OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Assignment Endpoint

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today