Login
    Contents x
    Transaction Model
    • 07 Oct 2024
    • 5 Minutes to read
    • Dark
      Light
    • PDF
    Contents

    Transaction Model

    • Updated on 07 Oct 2024
    • 5 Minutes to read
    • Dark
      Light
    • PDF
    Article summary

    The OneSpan Identity Verification Transaction model defines data elements that contain all transaction metadata necessary for the execution of an e-agreement workflow. The transaction model facilitates the following actions:

    • Produce signed agreement documents

    • Collect electronic evidence

    • Produce the audit trail and the single evidence pack

    The OneSpan Identity Verification Transaction model is fully defined by JSON schemas that can be used to generate client-side libraries for accessing the OneSpan Identity Verification REST API.

    Transaction properties

    The OneSpan Identity Verification transaction data structure contains metadata necessary for executing an e-agreement workflow and collecting electronic evidence. The evidence is needed for facilitating proof of compliance and legal enforceability.

    The structure combines transaction, users, documents, events, and session (view_state) data. Transaction is a top level resource that is shared across all OneSpan Identity Verification components.

    Transaction properties lists the transaction properties in OneSpan Identity Verification.

    • Path: .../properties/transaction

    • Type: object

    Transaction properties

    Property

    Type

    Description

    brand_id

    String

    The UUID of the brand assigned to the transaction.

    Brands are defined in the tenant configuration. Tenants can define and use multiple brands for their transactions. Once the brand ID is assigned, it cannot be changed after the transaction has been created.

    • Maximum length: 64

    • Minimum length: 36

    • Pattern:

      ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

    completed

    String

    The date and time when a transaction was completed.

    • Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}Z$

    • Default format: 2012-04-23T18:25:43.511Z

    configuration.consent

    Object

    Configuration for implicit or explicit consent. With explicit consent, the user needs to explicitly provide consent by selecting a checkbox on the Welcome page.

    For the list of consent properties, see configuration.consent properties.

    Restrictions for consent:

    • The consent needs to be provided in the same language as defined for IDV transactions.

    • The consent text can have up to 2048 characters.

    • The text can contain URLs in the following format:

      "I agree to the <URL link="URL">Terms and Conditions</URL>."

      The URL is not case sensitive.

    For more information, see Display rules for consent text.

    configuration.redirects

    Array

    The list of URLs which override the corresponding configured Handover URLs during transaction creation, using the values of the user's current transaction. They can be used to pass the following parameters:

    • userRole

    • transactionId

    • opaqueId

    URLs are specified with pairs of ID and URL. For the list of redirects properties, see configuration.redirects properties.

    created

    String

    The date and time the transaction was created in UTC.

    Pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

    disable_notifications

    Boolean

    This property defines whether notifications are disabled for the current transaction.

    Default value: false

    disable_recording

    Boolean

    This property defines whether recording is disabled for the current transaction.

    Default value: false

    documents

    Array containing documents and their attributes defined in the current transaction (see Document model).

    Schema: transaction.schema.3.0.documents.json#/definitions/documents

    erasure_mark

    String

    The day when the transaction should be deleted as per client request. UTC Now only considers the year, the month, and the day.

    • Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}Z$

    • Example: 2012-04-23Z

    erasure_mark_request

    String

    UTC Now timestamp in milliseconds.

    The moment the transaction was marked or unmarked for erasure.

    • Pattern:

      ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]*)?Z$

    • Example: 2012-04-23T18:25:43.511Z

    expiry_period

    Integer

    The number of days before the transaction expires. If not provided, the default value specified in the tenant configuration will be used.

    expiry_timestamp

    String

    The date and time the transaction expires in UTC.

    Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}Z$

    id

    String

    The UUID of the transaction.

    • Maximum length: 64

    • Minimum length: 36

    • Pattern:

      ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

    language

    This property defines the default language for transactions. It can be overwritten at the session level. In the context of the same transaction, multiple interactive sessions can be executed using different languages.

    Schema: ../common/_common.schema.3.0.language.json

    last_api_request

    String

    The date and time of the last transaction with an API request.

    Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}Z$

    last_session_event

    String

    The date and time of the last event from an active workflow session.

    Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}Z$

    opaque_id

    String

    Optional. The opaque ID can be provided by the client application and assigned to a transaction. Once the opaque ID is assigned, it cannot be changed after the transaction has been created. The opaque ID will be included in the event notification data together with the transaction ID. It can be used by the client application as additional context for transaction tracking.

    • Maximum length: 64

    • Minimum length: 0

    • Default length: 1234567890

    request_ids

    Array

    IDs of asynchronous requests.

    Items:

    • Type: string

    session

    Session data (see Session model).

    Schema: transaction.schema.3.0.session.json#/definitions/session

    status

    String

    The current transaction status. The status can be one of the following:

    • new

    • post_processing

    • completed

    • cancelled

    • expired

    • error

    Default value: new

    status_changed

    String

    The date and time when the transaction status has changed.

    • Pattern:

      ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]*)?Z$

    • Example: 2021-01-23T18:25:43.511Z

    tenant_id

    String

    The UUID of the tenant to which this transaction belongs.

    When the transaction is created, the tenant is identified by the JWT provided with the transaction creation request. Once the tenant ID is assigned, it cannot be changed. Thus, transactions cannot be reassigned among tenants.

    Pattern: ^[-w]+$

    tokens

    Array containing the session creation tokens that were issued for this transaction (see Token model).

    Schema: transaction.schema.3.0.tokens.json#/definitions/tokens

    urlSetKey

    String

    The URL set key that is used to retrieve the tenant endpoint.

    users

    Array containing information that specifies the signer's identity data (see User model). This array contains a list of resources where each list entry represents information about a single participant of the e-agreement process. The data contains personal identity information, address information, and other data that can be used for online identity validation.

    Schema: transaction.schema.3.0.users.json#/definitions/users

    version

    Integer

    The version of the transaction record. Read-only property.

    Default value: 0

    workflow_id

    String

    The UUID of the workflow assigned to the transaction.

    Workflows are defined in the tenant configuration. Tenants can define and use multiple workflows for their transactions. Once the workflow ID is assigned, it cannot be changed after the transaction has been created.

    • Maximum length: 64

    • Minimum length: 36

    • Pattern:

      ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

    configuration.consent properties

    Property

    Type

    Description

    explicit

    Boolean

    True: Consent is explicit.

    False: Consent is implicit.

    text

    String

    The message displayed on the Welcome page for implicit/explicit consent.

    configuration.redirects properties

    Property

    Type

    Description

    id

    String

    The ID of the Handover URL to override.

    URL

    String

    The URL that overrides the configured Handover URL.

    Display rules for consent text

    The following display rules apply:

    • Links in the format <URL link="URL">Text</URL> should open in a new browser tab.

    • HTML symbols need to be escaped and will be displayed as is.

    • All lines are preserved.

    Display rules for consent text

    Consent text

    Displayed as

    Please confirm <URL link="link"> a consent </URL>. Thanks

    Please confirm a consent. Thanks

    Please confirm <URL link="link"> a consent </URL>.

    Thanks

    Please confirm a consent.

    Thanks

    Please confirm <URL link="link"> a consent </URL>. </> Thanks

    Please confirm a consent. </> Thanks

    Please confirm <URL link="link"> a consent </URL>. <URL> Thanks

    Please confirm a consent. <URL> Thanks

    Please confirm <URL link="link"> a consent </URL>. </URL> Thanks

    Please confirm a consent. </URL> Thanks

    Please confirm <URL link="link"> a consent </> </URL>. Thanks

    Please confirm a consent </>. Thanks

    Please confirm <URL link="link"> a consent <URL> </URL>. Thanks

    Please confirm a consent <URL>. Thanks

    Please confirm <URL link="link"> a consent </URL>. </URL> <URL link="link"> a consent1 </URL>. Thanks

    Please confirm a consent. </URL> a consent1. Thanks

    Example request

    {
  "workflow_id": "80b601c9-f102-4761-9eaa-90ba8fcb58b6",
  "urlSetKey": "default"
  "language": "english",
  "opaque_id": "WorkflowExternalMitAtPwd=1234",
  "brand_id": "a089f718-f12d-4b13-b82e-e1d8b324337d",
  "disable_recording": "true",
  "disable_notifications": "true",
  "configuration": {
    "redirects": [
      {
        "id": "REDIRECT_DOCID_PASS",
        "url": "https://www.overriddenUrl.com/?user={{userRole}}&transaction={{transactionId}}&opaqueId={{opaqueId}}"
      }
    ]
  "status_changed":"2021-01-23T18:25:43.511Z"
  "erasure_mark":"2012-04-23Z"
  "erasure_mark_request":"2012-04-23T18:25:43.511Z"
  },
  "users":[{"...": "..."}],
  "tokens": [{"...": "..."}],
  "documents": [{"...": "..."}]
  "expiry_period": 10
}

    The content of this API contains data elements provided by our partners and is subject to changes and updates by our partners. Such content may include errors, omission, technical or other mistakes or inaccuracies. We will assist you to the best of our ability, but please note that we do not fully control this content.

    Was this article helpful?
    What's Next
    Change password!
    Changing your password will log you out immediately. Use the new password to log back in.
    Change profile
    Success!
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    Logout
    ESC

    Ozzy, our interactive help assistant