Last modified: 2024-03-26

REST API

OneSpan Sign has created a Digital Lending Solution that can store a loan or other related document (e.g., contract, chattel paper) in a digital vault.

Certain REST API settings associated with a OneSpan Sign transaction can specify which document should be vaulted, and in which organization and vault it should be stored. After a document's authoritative copy is vaulted, it is replaced in OneSpan Sign's database by either a watermarked non-authoritative copy (default) or a blank document.

eOriginal and OneSpan both provide vaults for documents. The following sections describe how to use their vaults:

Creating a transaction or template with the REST API always involves certain standard settings — see Java SDK.

If you want to view all existing calls, see our interactive Open API Specification. From there you can download the YAML file for our REST API, search for specific endpoints in that API, and even try a few calls yourself.

Whenever an attempt to eDeposit documents in an eOriginal vault fails, OneSpan Sign sends a notification to the Sender of the associated transaction via a Callback Event. Once the effort to vault a document suffers a non-recoverable error, OneSpan Sign sends the Sender an email about the failure. That email’s template cannot be customized.

Using an eOriginal Vault

Currently, the use of Optional Signatures with eOriginal is not supported. By default, when using eOriginal, documents are vaulted as soon as the last signature has been signed by the last signer. However, when using optional signatures it is possible to complete a transaction without completing all signature fields. In this case, the document would not be vaulted.

If you want to store a document in an eOriginal vault, the first thing you need to do is to ask our Support Team to enable this functionality for your account.

To instruct OneSpan Sign to store a document in an eOriginal vault, integrators must add to the transaction's data field the vaulting_data JSON field described below.

eOriginal vaults a lending document from a OneSpan Sign transaction together with the transaction's Audit Log.

As of the 11.37 release of OneSpan Sign, if a transaction has multiple loan documents: (1) an eOriginal vault can store all those documents for the transaction; (2) eOriginal's Audit Trail lists all events related to the transaction and its multiple documents.

vaulting_data

This field should be a Base-64-encoded JSON string. When the field is decoded, the parameters in the following table can be viewed.

Parameter Required? Description
vaultTransactionTypeName No This allows vaulting customers to pass their desired transaction type name to the system using the transactiontypename parameter. This allows users to distinguish the source of certain transactions when vaulting from multiple sources they want to track.
vaultCredentials Yes

This JSON object contains the authentication credentials for accessing eOriginal's eCore service API.

This object must contain the following required fields:

  • username — API Login ID of the API user who will perform the vault-deposit operation.

  • orgNameOrganization Short Name for the Organization within eOriginal's eCore service, where the document will be stored.

  • apiKey — API User's 32-character API Key.

This JSON object also contains the following optional field (a default value will be used if the endpoint field is not specified):

  • endpoint — The eOriginal environment in which documents will be deposited. The possible values are:

    • testondemand — This is: (i) one of two values supported for Sandbox accounts; (ii) the default value for Sandbox accounts.

    • previewondemand — This is the other value supported for Sandbox accounts.

    • ondemand — This is: (i) the only value supported for Production accounts; (ii) the default value for Production accounts

documentsToVault Yes

This is a JSON array that must contain the following required fields. Each entry of the array contains vaulting information for a specific document.

  • documentId — ID of the OneSpan Sign document that will be vaulted with eOriginal's eCore service. This document is typically a loan. The value of this parameter should match the document ID of a document in the transaction.

  • loanId — Unique ID of the loan, according to the customer's system
  • loanAmount — Original amount of the loan in US cents
  • lender — Name of the lender for this loan
  • type — This field is used in eOriginal's eCore service to classify documents according to their associated process within your business. It must match a Document Type that has been configured for your eOriginal eCore service Customer Org.
version No

Version of the protocol to be used. Currently the only supported value is Lending-2.0.

postRegisterOption No

After the authoritative copy of a document is vaulted in an eOriginal vault, it is removed from OneSpan Sign. This parameter specifies how this authoritative copy will be replaced in OneSpan Sign. The supported values are:

  • watermark_doc (default) — After a document is vaulted, the signed PDF content is watermarked, flattened, and saved in OneSpan Sign.

  • blank_doc — After a document is vaulted, the signed PDF content is replaced in OneSpan Sign with a blank document.

Note: Clients cannot download the authoritative copy of a document that will be deposited in an eOriginal vault. If they try to do so, they will end up downloading a flattened non-authoritative copy whose every page will bear the watermark Non-Authoritative Copy.

customFields No

This JSON object contains data that will be added to the eOriginal transaction as Custom Fields.

This object can contain any field as long as its name matches that of a Custom Field configured for your eOriginal eCore service Customer Org.

Example

Here is an example of a Base64-decoded "vaulting_data" value:

{
    "postRegisterOption":"watermark_doc",
    "vaultTransactionTypeName":"OneSpan Sign eTest",
    "vaultCredentials":{
        "username":"SampleUsername",
        "orgName":"SampleOrganization",
        "apiKey":"ok0Sample0ApiKey0Just0An0Example",
        "endpoint":"previewondemand"
    },
    "documentsToVault":[
        {
            "documentId":"DocumentName01",
            "loanId":"loanId_001",
            "loanAmount":"99999",
            "lender":"ABC Corporation",
            "type":"Loan Contract"
        }
    ]
}

Using a OneSpan Vault

To instruct OneSpan Sign to store a document in a OneSpan vault, integrators must add to the transaction's data field the registry_data JSON field described below.

OneSpan vaults are administered by the company's e-Vault Manager product.

registry_data

This field should be a Base-64-encoded JSON string. When the field is decoded, the parameters in the following table can be viewed.

Parameter Required? Description
vaults Yes

This is a JSON array that identifies a vault where the document will be stored.

Each entry in the JSON array must contain the following required fields:

  • orgId — Unique ID of the Organization that owns the vault where the document will be stored. This is the same Organization ID employed by users when they log into the e-Vault Manager console.

  • vaultId — The numerical ID of the vault where the document will be stored. An Organization Administrator can see this ID by viewing the vault's details in the Organization identified by the orgId.

Each entry in the JSON array may contain the following optional field:

  • transaction — Name to be given to the e-Vault Manager transaction that will be used to register the document with the e-Vault Manager. The transaction may contain multiple documents.

registryRecords Yes

This is a JSON array that must contain the following required fields. Each entry of the array contains vaulting information for a specific document.

  • documentId — Name of the OneSpan Sign document that will be registered with the e-Vault Manager. This document is typically a loan. The value of this parameter should match the document ID of a document in the transaction.

  • registryId — Name that will be given to the document within the e-Vault Manager. This name must be unique within the given instance of the e-Vault Manager.
  • borrowers — A JSON array that contains one or more OneSpan Sign Role IDs. Before the transaction can be distributed for signing, each Role ID in this array must match the Role ID of a role in the transaction.
  • loanId — Unique ID of the loan, according to the customer's system
  • loanAmount — Original amount of the loan in US cents
  • lender — Name of the lender for this loan

The JSON array may also contain the following optional field:

  • vaultId — This is the vaultId of the entry in the vaults array. If this parameter is not specified, the system will use the vaultId of the vaults parameter. If this parameter is specified, it must match the vaultId of the vaults parameter.
version No

Version of the protocol to be used. Currently the only supported value is Lending-1.0.

postRegisterOption No

After the authoritative copy of a document is registered with the e-Vault Manager, it is removed from OneSpan Sign. This parameter specifies how this authoritative copy will be replaced. The supported values are:

  • watermark_doc (default) — After a document is registered with the e-Vault Manager, the signed PDF content is watermarked, flattened, and saved in OneSpan Sign.

  • blank_doc — After a document is registered with the e-Vault Manager, the signed PDF content is replaced in OneSpan Sign with a blank document.

Example

Here is an example of a Base64-decoded "registry_data" value:

{
    "version": "Lending-1.0",
    "postRegisterOption": "watermark_doc",
    "vaults": [{
            "transaction": "sample-transaction1",
            "orgId": "org1",
            "vaultId": "1"
        }
    ],
    "registryRecords":[{
            "documentId":"UnsignedDocument01",
            "registryId": "loan123-Id01",
            "borrowers": ["Borrower2"],
            "loanId": "loan123",
            "loanAmount": "999999",
            "lender": "ABC Corporation",
            "vaultId": "1"
        },{
            "documentId":"UnsignedDocument02",
            "registryId": "loan123-Id02",
            "borrowers": ["Borrower3"],
            "loanId": "loan234",
            "loanAmount": "999",
            "lender": "Ajax Corporation",
            "vaultId": "1"
        }
    ]
}

Email Template for a Vaulting Failure

If an attempt to vault a document fails, OneSpan Sign uses the following template to send the associated transaction's Sender an email about the failure.

This template cannot be customized.

<?xml version="1.0" encoding="UTF-8"?>
<email-template xmlns="urn:schema.awsng.silanis.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<from>
<email>[email protected]</email>
<display_name>OSS Support</display_name>
</from>
<to>
<address>
<email>%USER_EMAIL;</email>
<display_name>%USER_FIRST_NAME; %USER_LAST_NAME;</display_name>
</address>
</to>
                
<subject>e-Sign Ceremony Failure Notification</subject>
<body>
<content-type>text/html; charset="UTF-8"</content-type>
<content>
                
Dear %USER_FIRST_NAME; %USER_LAST_NAME;,<br/>
<br/>
An error has occurred for your package: <br/>
<br/>
%NOTIFICATION_MESSAGE;<br/>
<br/>
Should you have any problem, please contact OSS Support at [email protected]
<br/>
<br/>
                
Thank you for e-signing.<br/>
<br/>
                
OSS Support
</content>
</body>
<priority>1</priority>
                
</email-template>
					

The above failure notification will not be sent if any of the following errors occurs within the vaulting_data JSON field:

Error What the POST request /api/packages returns
The documentId field for the parameter documentsToVault is incorrect (i.e., it is not a documentID in the transaction). 200
The username field for the parameter vaultCredentials is incorrect. 200
The apiKey field for the parameter vaultCredentials is incorrect.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

The orgName field for the parameter vaultCredentials is incorrect, but the apiKey field is correct.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

Incorrect JSON – e.g., referencing vaultCredentials as valutCredentials. 200
Was this information helpful?
X