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 Transactions/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, here are step-by-step 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 this detailed user’s registration blog.

Endpoint URL

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

https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users/{userID@domain}/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:  

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 userID@domain. 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.

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

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:

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.

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.

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.

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 Community

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

Join Today