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
  • cancelled
  • expired
  • workflow_in_progress
  • workflow_completed
  • error
  • autosigned
  • vaulted
  • completed
  • post_processing

Default value: new

request_ids Array

IDS of an asynchronous request.

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

Example request create transaction content

  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. }