Transaction details and mobile SDK push messages

Use this page when you need to attach transaction data to an Authentication API request or customize Soft Token SDK push notifications.

Transaction Details

A transaction detail consists of a detail name, a value, and a list of supported usages. Valid usage values are RBA and TVS. When not defined, the transaction detail is used both for RBA (risk-based authentication) and TVS (transaction verification/signing).

When using a push authenticator, such as Entrust Soft Token Push authentication or Mobile Smart Credential Push authentication, transaction details may be included in the challenge request. Transaction details are passed to the mobile device and displayed to the user when confirming authentication.

When using an OTP authenticator with Authentication API or OIDC applications for PSD2, the OTP is dynamically linked with transaction details. The transaction details are included in the challenge request. Identity as a Service generates a new, specific OTP tied directly to the request and transaction details. The OTP is then sent to the user using Email or SMS messaging. The user reviews the transaction details and uses the associated OTP to complete the authentication challenge.

When using a TOKEN authenticator with Authentication API or OIDC applications for PSD2, the token response is dynamically linked with transaction detail values. The transaction details are included in the challenge request. The user reviews the transaction details and enters the transaction values (consecutively) into the token and obtains the signature. The signature is then used to complete the authentication challenge.

When using a TOKEN authenticator with Authentication API or OIDC applications, the token response can be processed offline. The challenge requests include the transactions details. The transaction details consist of a detail name and a value. The challenge response contains a list of QR codes based on the active tokens and the transaction details. The user scans a QR code in the Entrust Identity application, reviews the transaction details, confirms the transaction, and obtains an OTP. The OTP is then used to complete the authentication challenge.

To use the offline QR code transaction with TOKEN authenticator, the request user challenge body and user authentication body need to have the flag offlineTVS set to be true:

"offlineTVS": true

Transaction detail limits

The following restrictions apply to transaction details:

• The detail name cannot be duplicated.
• The length of the detail name and value cannot exceed 255 characters.
• The number of transaction details cannot exceed 25.

PSD2 and request matching

When dynamically linking transaction details with Authentication API or OIDC applications that use an OTP authenticator or TOKEN authenticator for PSD2, the same transaction details must be specified in both the user challenge (Select authenticator) request and the user authenticate (Complete authentication challenge) request. They must match.

When using transaction details with push authentication as part of the user challenge (Select authenticator) request, the use of the same transaction details can be optionally specified in the user authenticate (Complete authentication challenge) request. If specified, they must match.

When using the transaction details, it is recommended that the transaction details are always supplied in both the user challenge (Select authenticator) request and the user authenticate (Complete authentication challenge) request. This is mandatory for PSD2 authentications.

Transaction details can be used with OIDC applications only in the JWT IDaaS workflow. The risk-based authentication (RBA) transaction details passed in the user authenticate challenge and authenticate complete requests can be included in the OAuth2 JWT access token using the transaction_details claim. For details, see OIDC/OAuth JWT IDaaS workflow.

To use transaction details with a push authenticator or an OTP authenticator API or OIDC applications for PSD2, the request user challenge body should contain a JSON object with an array of these details. For example:

{
  "transactionDetails": [
    {
      "detail": "Account",
      "value": "67432",
      "usage": ["TVS"]
    },
    {
      "detail": "Amount",
      "value": "$10,001",
      "usage": ["TVS"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["TVS"]
    }
  ]
}

To use transaction details with a TOKEN authenticator API or OIDC applications for PSD2, the request user challenge body should contain a JSON object with an array of these details. Some tokens may only support numeric transaction values. For example:

{
  "transactionDetails": [
    {
      "detail": "Account",
      "value": "67432",
      "usage": ["TVS"]
    },
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["TVS"]
    }
  ]
}

Mobile SDK Push Messages

When using a customized push message for TOKENPUSH notification, you need to configure a Soft Token SDK.

When a Soft Token SDK is created, a Push Message is generated with a default flag set to true. Users can add, modify, and delete push message configurations. To delete a row with a default flag set to true, users must first add a new push message and set it as the default message before deleting the default message.

Customized push message selection

If you want to send customized messages to the device, you need to set the pushMessageIdentifier parameter in the request to match the identifier column of the customized push message. For example, if you create a customized push message with the Identifier column in the push message table in the SDK settings set to Hello, you must set pushMessageIdentifier to Hello.

If a match is not found, it throws an error. If you have a Soft Token SDK, and you do not set pushMessageIdentifier, the default push message will be used.

The pushMessageIdentifier parameter is case-insensitive, and it is optional.