Create transaction

Transactions are the main resource in OneSpan Identity Verification (see also Transaction model). This API creates and starts the execution of a new transaction:

  • Create transactions with documents, signatures, signers, and an instance of the predefined workflow.
  • Create transactions with predefined document templates.
  • Create transactions by providing additional metadata that will be retained as electronic evidence.
  • Create transactions with an instance of a predefined workflow to request identity validation checks to be executed through OneSpan Identity Verification.
  • Create transactions that require implicit or explicit user consent. For an example request, see Example request with explicit consent. For consent configuration, see Transaction model.

The number of agreements may not exceed a total size of 50 MB, and the size of a single agreement must not exceed 10 MB.

Syntax

PUT /api/transaction/

Examples

Example requests

  1. PUT api/transaction/ HTTP/1.1
  2. Host: onespan.com
  3. Accept: application/json, text/javascript
  4.  
  5. {
  6.   "tenant_id":"5e52d7b8-8b18-41a4-9187-d4ce75af6815",
  7.   "workflow_id":"80b601c9-f102-4761-9eaa-90ba8fcb58b6",
  8.   "urlSetKey":"default",
  9.   "brand_id":"a089f718-f12d-4b13-b82e-e1d8b324337d",
  10.   "language": "english",
  11.   "opaque_id": "WorkflowExternalMitAtPwd=1234",
  12.   "configuration": {
  13.     "redirects": [
  14.       {
  15.         "id": "REDIRECT_DOCID_PASS",
  16.         "url": "https://www.overriddenUrl.com/?user={{userRole}}&transaction={{transactionId}}&opaqueId={{opaqueId}}"
  17.       }
  18.     ]
  19.   },
  20.   "users"[...],
  21.   "documents"[...]
  22. }

Example request with explicit consent

  1. PUT api/transaction/ HTTP/1.1
  2. Host: onespan.com
  3. Accept: application/json, text/javascript
  4.  
  5. {
  6.   "tenant_id":"5e52d7b8-8b18-41a4-9187-d4ce75af6815",
  7.   "workflow_id":"80b601c9-f102-4761-9eaa-90ba8fcb58b6",
  8.   "urlSetKey":"default",
  9.   "brand_id":"a089f718-f12d-4b13-b82e-e1d8b324337d",
  10.   "language": "english",
  11.   "opaque_id": "WorkflowExternalMitAtPwd=1234",
  12.   "configuration": {
  13.     "redirects": [
  14.       {
  15.         "id": "REDIRECT_DOCID_PASS",
  16.         "url": "https://www.overriddenUrl.com/?user={{userRole}}&transaction={{transactionId}}&opaqueId={{opaqueId}}"
  17.       },
  18.       "consent": {
  19.         "explicit": true,
  20.         "text": "I agree to the <URL link=\"myTermsURL"\> Terms and Conditions</URL> consent."
  21.       }
  22.     ]
  23.   },
  24.   "users"[...],
  25.   "documents"[...]
  26. }

Example response

  1. HTTP/1.1 200 OK

  2. Vary: Accept
  3. Content-Type: application/json
  4. {

  5.   "id":"dcaad720-d1e9-47ba-a76b-a6370ef0373b",

  6.   "status":"new",
  7.   "created":"2017-04-23T18:25:43.511Z",
  8.   "tokens": [...],

  9.   ...

  10. }

Headers

The following headers are included in the request and the response:

Request headers

  • Accept: The response content type depends on the Accept header.
  • Authorization: The OAuth/JWT token to authenticate.

Response headers

Status codes

Status codes
Status code Name Description
200 OK

No error.
400 Bad Request The transaction data is invalid.
401 Unauthorized Invalid token.
403 Forbidden The token does not grant transaction creation rights.
500 Internal Server Error Server or application error.