Transaction model

The OneSpan Identity Verification Transaction model defines data elements that contain all transaction metadata necessary for the execution of the e-agreement workflow, producing signed agreement documents, collecting electronic evidence, producing the audit-trail and Single Evidence Pack.

The OneSpan Identity Verification Transaction model is fully defined by JSON schemata 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 necessary 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 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
id String

UUID identifying 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}$

status String

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

  • new
  • post_processing
  • completed
  • cancelled
  • expired
  • error

Default value: new

request_ids Array

IDs of asynchronous requests.

Items:

  • type: string
tenant_id String

UUID of the tenant to which this transaction belongs. At the moment of transaction creation, the tenant is identified by the JWT provided with the transaction creation request. Once assigned, the tenant ID cannot be changed; thus, transactions cannot be reassigned among tenants.

Pattern: ^[-w]+$

brand_id String

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 assigned, the brand ID 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}$

workflow_id String

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 assigned, the workflow ID can not 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}$

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 could be executed using different languages.

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

opaque_id String

Opaque ID that can be optionally provided by the client application and assigned to a transaction. Once assigned, the opaque ID 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, and can be used by the client application as additional context for transaction tracking.

Maximum length: 64

Minimum length: 0

Default length: 1234567890

created String

Date and time of the transaction creation 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}$

last_session_event String

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$

completed String

Date and time when a transaction is 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

last_api_request String

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$

users  

Array containing information that specifies the signer's identity data (see User model). This array contains a list of resource 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

tokens  

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

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

documents  

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

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

session  

Session data (see Document model).

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

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$

disable_notifications Boolean

Notifications are disabled for the current transaction.

Default value: false

disable_recording Boolean

Recording is disabled for the current transaction.

Default value: false

version Integer

Read-only property; version of the transaction record.

Default value: 0

urlSetKey String The URL set key that is used to retrieve the tenant endpoint.
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.

Property Type Description
id String

The ID of the Handover URL to override.

URL String

The URL that overrides the configured Handover URL.

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

erasure_mark String

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

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.

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.

Property Type Description
explicit Boolean

True: Consent is explicit.

False: Consent is implicit.

text String

Message displayed on Welcome page for implicit/explicit consent.

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.

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": "otp_twilio_sms_tc1Pwd=9421",
  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.