Transaction model

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

  1. {
  2.   "workflow_id": "80b601c9-f102-4761-9eaa-90ba8fcb58b6",
  3.   "urlSetKey": "default"
  4.   "language": "english",
  5.   "opaque_id": "WorkflowExternalMitAtPwd=1234",
  6.   "brand_id": "a089f718-f12d-4b13-b82e-e1d8b324337d",
  7.   "disable_recording": "true",
  8.   "disable_notifications": "true",
  9.   "configuration": {
  10.     "redirects": [
  11.       {
  12.         "id": "REDIRECT_DOCID_PASS",
  13.         "url": "https://www.overriddenUrl.com/?user={{userRole}}&transaction={{transactionId}}&opaqueId={{opaqueId}}"
  14.       }
  15.     ]
  16.   "status_changed":"2021-01-23T18:25:43.511Z"
  17.   "erasure_mark":"2012-04-23Z"
  18.   "erasure_mark_request":"2012-04-23T18:25:43.511Z"
  19.   },
  20.   "users":[{"...": "..."}],
  21.   "tokens": [{"...": "..."}],
  22.   "documents": [{"...": "..."}]
  23.   "expiry_period": 10
  24. }

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.