Signing

Full-flow Example

3326 views September 26, 2017 May 2, 2019 13

Scenario: 1 document and 1 signer

Use case:

John is planning to buy a new apartment and is logged in to his bank to apply for a loan. He fills out and submits the loan application.

Jane, an employee at John’s bank, receives John’s loan application and approves the application based on information on John’s financial situation. Jane prepares the loan contract for John, uploads it and sends it to John to sign.

The content of this page:

  1. Prepare signing
  2. Create and send signing request
  3. Notify signer
  4. Redirect signer to Signicat
  5. Signer signs the document
  6. Signing result is created
  7. Sender checks the status of the request
  8. Download signed document from Signicat Archive
  9. Flow diagram

1. Prepare signing

For John to get his loan application approved and signed, some specifications have to be in place. It has to be specified which methods are to be made available for signing, as well as which functionality is available for handling the document. As the loan application only has to be signed, the “Sign” action is the only action needed for this process.

Upload the document to be signed to Session Data Storage (SDS)

Jane uploads the document “Loan contract.pdf” to SDS for temporary storage accessible via a REST interface. Jane also chooses to save the SDS document, as well as the document after it has been signed. For more information about the different document data types and SDS, please see the DocumentService page.

The data-type is set to “sds-document” and is given a unique SDS ID that identifies the document, “ref-sds-id“. These fields will be set in the signing request.

An alternative is to send the document to be signed along with the signing request, but SDS is both more efficient and can handle larger documents.

2. Create and send signing request

Jane creates the signing request with Documentservice and the createRequest.

Jane sets:

  • the task to have document-action of type “Sign” that is set to be saved after signing
  • the method to be used for signing to be Norwegian BankID
  • the type of signing to be authentication-based signing
  • language to “en” for English (optional)
  • subject to “John Doe” with national id “10109001290” and mobile number “11223344” (optional)
  • notification to “Dear John, Please sign this loan contract. Best regards Jane” (optional)
  • send-result-to-archive” is set to true for archiving the signed document to the archive. (optional)
  • on-task-postpone“, “on-task-complete” and “on-task-cancel” values are only set to illustrate their existence (optional)

See the complete signing request here:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <S:Body>
        <create-request-request xmlns="https://id.signicat.com/definitions/wsdl/Document-v3">
            <service>demo</service>
            <password>Bond007</password>
            <request>
                <language>en</language>
                <task bundle="false" id="1">
                    <subject>
                        <national-id>10109001290</national-id>
                        <first-name>John</first-name>
                        <last-name>Doe</last-name>
                        <mobile>11223344</mobile>
                    </subject>
                    <document-action optional="false" send-result-to-archive="true" type="sign">
                        <document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ref-sds-id="021020172365t7y0xwatgum3d7973311le4u44bdo31o1vo9gu3lcmwtcn" send-to-archive="false" xsi:type="sds-document">
                            <sign-text-entry/>
                            <description>Loan contract.pdf</description>
                        </document>
                    </document-action>
                    <notification notification-id="1" type="SMS">
                        <recipient>11223344</recipient>
                        <sender>Jane</sender>
                        <message>Dear John,
                            Please sign this loan contract.

                            Best regards Jane</message>
                    </notification>
                    <on-task-postpone>https://en.wiktionary.org/wiki/postpone</on-task-postpone>
                    <on-task-complete>https://en.wiktionary.org/wiki/complete</on-task-complete>
                    <on-task-cancel>https://en.wiktionary.org/wiki/cancel</on-task-cancel>
                    <configuration>default</configuration>
                    <signature>
                        <method>nbid-sign</method>
                    </signature>
                </task>
            </request>
        </create-request-request>
    </S:Body>
</S:Envelope>

3. Notify signer

John gets notified about the document through an SMS from Jane, specified in the signing request. It says “Dear John, Please sign this loan contract. Best regards Jane”. An URL for signing the document is attached in the SMS.

4. Redirect the signer to Signicat

The URL leading attached to the SMS notifying John about the signing has this format:

https://env.signicat.com/std/docaction/service?request_id=request_id&task_id=task_id&artifact=artifact

For more about the URL and the different parts of the URL, please see here.

5. Signer signs the document

John clicks the URL sent to him and the document presenter opens and he signs the Loan contract with his Norwegian BankID.

The screenshots show the signing process with Norwegian BankID for John. John will not have specify his national identification number; Norwegian BankID only requires one-time-code and personal assword for this scenario, as subject is set with the national identification number (national-id) in the signing request.

6. Signing result is created

The signing results is a LTV-SDO that is packed to a PAdES through createPackage in PackagingService.

SDO

To download the LTV-SDO XML example, please click here.

PAdES

To download the PAdES example, please click here.

7. Sender checks the status of the request

With DocumentService and getStatus, it is possible for Jane to get information about the signing requests, to see if the status still is “Created”, or if John has signed (status set to “Completed”) or if the signing request is cancelled for some reason (status set to “cancelled”). As John has signed the Loan contract document, getStatus will return “completed”.

An alternative is for Jane to be notified when the status is changed.

8. Download signed document from Signicat Archive

Jane defined through “send-result-to-archive” that the signed document should be archived. The signed document can therefor be downloaded from the archive for later use and validation, if desired, through the getDocument in ArchiveService.

9. Flow diagram

Was this helpful?