Transaction Settings for Digital Lending

Updated on 10 Oct 2024
6 Minutes to read

Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

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.

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 for Digital Lending Transactions

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. orgName — Organization 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. loanId, loanAmount, and lender are only sent to eOriginal for the first item in the array. For subsequent items these values are not sent to eOriginal.
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"
        },
        {
            "documentId":"DocumentName02",
            "loanId":"N/A",
            "loanAmount":"0",
            "lender":"N/A",
            "type":"Ancillary"
        }
]
}

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>support@onespan.com</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 support@onespan.com
<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 article helpful?

What's Next

Configuring eOriginal

Table of contents

Using an eOriginal Vault for Digital Lending Transactions
Email Template for a Vaulting Failure