Integration of adaptive message-based transaction data signing

Adaptive message-based transaction data signing is a type of transaction data signing that supports virtual signatures that are sent via email, SMS, or voice delivery to a mobile device. A virtual signature consists of a one-time password (OTP) and signature data fields that are unique to the pending transaction.

This type of transaction requires a virtual authenticator that supports VDP Sign.

Prerequisites

To ensure successful adaptive message-based transaction data signing, the following prerequisites must be met:

Adaptive message-based transaction data signing secured with virtual signature validation

Adaptive message-based transaction data signing — overview

Sequence of an adaptive message-based transaction data signing operation secured with virtual signature validation

  1. The user starts the transaction data signing operation. The app collects CDDC data and sends the request with the collected data to the web server. The web server forwards the request to the OneSpan Trusted Identity platform API with a call to the POST /transactions endpoint.
  2. The OneSpan Trusted Identity platform API forwards the request to Risk Analytics, which returns either a riskResponseCode of 3 (ChallengeSMS), 8 (ChallengeEmail), or 13 (ChallengeVoice) to the client application.
  3. The user enters their credentials, which triggers the client application to initiate the signature generation request to the OneSpan Trusted Identity platform API with a call to the POST /users/{userID@domain}/generate-virtual-signature endpoint.
  4. The Authentication component verifies the user credentials.
  5. The Authentication component generates the signature and contacts the Message Delivery component.
  6. The Message Delivery component forwards the message via the specified delivery method (SMS/ email/ voice call) to the user's mobile device. The message consists of an OTP and signature data fields.
  7. The user verifies the signature data fields and enters the OTP into their client application.

  8. The client application sends the transaction validation request to the OneSpan Trusted Identity platform API with a call to the POST /users​/{userID@domain}​/transactions​/validate endpoint. The request contains the OTP and the signature data fields.

    When you send the signature for the POST /users​/{userID@domain}​/transactions​/validate endpoint, ensure that you also add the authType field and set it to strong in the payload.

  9. The Authentication component validates the signature.
  10. The Authentication component sends all the gathered data with the result of the transaction validation response to the Risk Management component. This component assesses all factors involved and sends the response back to the client application to confirm the transaction.

To integrate message-based transaction data signing via virtual signature

  1. Issue a transactions request with a call to the POST /transactions endpoint and provide the following information:

    • Payload:

      • accountRef
      • amount
      • currency
      • relationshipRef
      • sessionID
      • transactionType
      • userRef: (Optional) This field can be configured in Risk Management component to query user-specific information.

    • Response body:

      • riskResponseCode: 3 (ChallengeSMS) for SMS delivery, 8 (ChallengeEmail) for email delivery, and 13 (ChallengeVoice) for voice delivery
      • transactionID

  2. Issue a generate virtual signature request with a call to the POST /users/{userID@domain}/generate-virtual-signature endpoint and provide the following information:

    • Payload:

      • dataFields
      • credentials
      • deliveryMethod

  3. Issue a transaction validation request with a call to the POST /users​/{userID@domain}​/transactions​/validate endpoint and provide the following information:

    • Payload:

      • objectType: “AdaptiveTransactionValidationInput”
      • accountRef
      • amount
      • cddc
      • currency

      • authentType: strong

      • data.standard

        • dataFields
        • signature
      • relationshipRef
      • transactionType
      • userRef: (Optional) This field can be configured in Risk Management component to query user-specific information.

    • Response body:

      • riskResponseCode: 0
      • sessionStatus: accepted

Adaptive message-based transaction data signing — low risk validation request

If the transaction signing validation request is regarded as low risk, the Risk Management component will accept the request and return a riskResponseCode of 0 (accepted). In this case, no additional authentication steps are required.

Adaptive message-based transaction data signing — overview

Sequence of an adaptive transaction data signing operation

  1. The user starts the transaction data signing operation. The app collects CDDC data and sends the request with the collected data to the web server. The web server forwards the request to the OneSpan Trusted Identity platform API with a call to the POST /transactions endpoint.
  2. The OneSpan Trusted Identity platform API sends a transaction request to the Risk Management component. This component accepts the transaction request.
  3. The OneSpan Trusted Identity platform API receives the accepted transaction request and sends it to the web server.
  4. The web server forwards the accepted transaction request to the app.

To integrate message-based transaction data signing

  • Issue a transactions request with a call to the POST /transactions endpoint and provide the following information:

    • Payload:

      • accountRef
      • amount
      • currency
      • relationshipRef
      • sessionID
      • transactionType
      • userRef: (Optional) This field can be configured in Risk Management component to query user-specific information.

    • Response body:

      • riskResponseCode: 0 accepted

      • transactionID