Insert sign order

To initiate a signing through E-Signing, a sign order must be inserted into E-Signing. The sign order defines the document(s) to be signed, the signer(s), the web context to sign the document(s) in, any connection to an organisation, all actions to be performed and post-processing details like archival and checking signature rights. ​

The InsertOrder message has these main elements:

InsertOrder

The InsertOrder message is the message used place sign orders to E-Signing. This message must be used to initiate a signing. The first part of this page gives an overview of the main components of the structure in this message.

​Name​Description​Constraints
OrderID​

​The OrderID is the ID of the sign order which is set by the customer when inserting the sign order. The OrderID must be unique among all sign orders inserted by this customer identified with a MerchantID.

​MinLength = 1

MaxLength = 80

Special characters not accepted: [æ ø å ä ö < &  > \ / ' " % # ? = + *]

​OrderDescription

​A textual description of the sign order defined when inserting the sign order.

​MaxLength = 400

​Documents​All documents to be signed in this sign order must be defined in the Documents structure. ​NA
​Attachments​All attachments to be displayed to users in this sign order must be defined in the Attachments structure. ​Optional.
​MerchantThis element defines the notifications to the E-Signing customer. ​Read more about the structure. ​NA
​Signers​All signers of the documents in this sign order must be defined in the Signers structure. ​NA
​Organizations​This element defines the organisations involved in business to business post processing of the sign order. Read more about the structure. ​NA
​WebContexts​This elements defines the different web contexts the signer of a document can have. Read more about the structure. ​NA
​ExecutionDetails​This element defines the actions to be performed in the sign order like which signer shall sign document, the order of signing, what type of web context and so on. Read more about the structure.​NA
​MetaDataThis element defines meta data freely defined by the customer. Read more about the structure. NA​
​B2BPostProcessing​This element defines post processing of the sign order related to business to business information. Read more about the structure. ​NA
​PostProcessing​This element defines post processesing actions like archival of the signed documents. Read more about the structure.​NA

Back to top

​​​Doc​​uments​​

All documents to be signed are defined in this part of the sign order. The sign order must consist of at least one document in either TEXT, PDF or XML format. Each document can be up to 10 MB (10 million bytes) Base64 encoded while the sign order can be up to 30 MB Base64 encoded. Encoded documents add approximately 30 % extra to a non-encoded document. As an example, a PDF document of size 7 500 000 bytes (7.5 MB) will result in an encoded document of size 10 000 000 bytes (10 MB). Any restrictions on the docum​ent sizes related to the specific eID are specified in the eID section.

Note: It is always adviced to try testing the different documents used in the customer test environment. Larger documents may degrade the user experience. If possible, try avoiding a large amount of graphics in the document.

Documents2.png

Name​​Description​Constraints
​LocalDocumentReference A reference to label the document. This label must be unique inside this sign order and it is used later in the ExecutionDetails element to connect a signer to a document.

​MinLength = 1

MaxLength = 100

​Presentation / Title​The document title. The title is exposed to the signers in the web interface.

MinLength = 4

MaxLength = 100

There is an input validation on this element rejecting sign orders with the characters “<” and “>” in this element. 

The MaxBytes is 110.

​Presentation / DescriptionT​he document description. The description is exposed to the signers in the web interface.

​MinLength = 4

MaxLength = 240

There is an input validation on this element rejecting sign orders with the characters “<” and “>” in this element.

​Presentation / SignTextPrefix​The SignTextPrefix element is used in combination with BankID on mobile phones PDF signing. The SignTextPrefix will together with the hash of the PDF document be the signing text shown to the signer and be the actual text the signer signs.​MaxLength = 50
​DocType / PDF / Form

​This field indicates if the PDF shall be handled as a PDF form or not.

Read more about PDF Forms.

Optional

[true | false]

​DocType / PDF / FormInstructions​This is form instructions that will be displayed above the PDF form, and it can be used to inform the signer about what to do.

String

​MinLength = 4

MaxLength = 2000

​DocType / PDF / B64DocumentBytes

The PDF document is placed here.  ​

​Base64 encoded.
​DocType / TEXT / B64DocumentBytes​The TEXT document is placed here.  If the document is a TEXT, provide the document UTF-8 bytes. ​Base64 encoded.
​DocType / XML / B64XMLBytes​The XML document is placed here. 

​Base64 encoded.

Only BankID (NO) supports this document format.

​DocType / XML / B64XSLBytes​The XSL document format is placed here. The XSL used to transform the input xml into HTML. 

​​Base64 encoded.

Only BankID (NO) supports this document format.

​RequiresAuthentication ​If a document has this element set to true then all signers in sign processes that references this document are forced to identify themselves before signing the document. All signers in these sign processes MUST have SignerID’s to validate against. The SignerID is defined for each eID in the AcceptedPKIs element. [​true | false]
​NumberOfNeededSigners​This number specifies the number of end user signers required to sign the document. When this number is reached the document status is set to complete. ​NA

PDF Forms

The PDF sent to E-Signing can either be a regular PDF or a PDF form, but shouldn't be a secured PDF. The PDF form must be filled out by the first signer of the document. Other signers will sign the fulfilled document. Note: The first signer of a PDF form can't be a MerchantSigner, but must be a real person.

The PDF form in E-Signing support these form elements: 

  • Single-line text
  • Multi-line text
  • Dropdown
  • Radio button
  • Check box

Selected text elements and dropdowns will be shown as an overlay. This increases the readability and usage on smaller devices. Here is an example of how the overlay look:

Edit pdf form.PNG

The user may use keyboard navigation to navigate in the document:

  • Tab - can be used to move from element to element
  • Space - can be used to change values for radio buttons and check boxes
  • ESC - closing overlays
  • Enter - apply values to single-line text

The service is currently only validating required fields. User will not be able to proceed without filling these. Other validation is currently not supported.

The form data inserted by the first signer can be retrieve using the GetFormData request. The data will be returned as name/value pairs, and the name will be retrieved from the input form field name. The different form fields should be named uniquely.

We recommend that all PDF form document templates is tested in Nets customer test environment prior to use in production to make sure they can be filled out and signed correctly.

Note: The use of this function may have an extra cost. If it is not already priced in your agreement, please contact sales.esecurity@nets.eu to retrieve the price list and an offer. 

Back to top

Attachments

One or more attachments can be added to a sign order and displayed to a specified signer during the signing flow. The attachments must be PDF documents. The attachments are displayed as links above the sign client, and the links will open in a PDF reader or another browser window. The attachments are not signed and will not be a part of the SDO or PAdES document. Below is an example on how it will look like. Note: You might need to increase the height of the iframe used:

PDF Attachment.jpg

 

InsertOrder-attachments.png

​Name​Description​Constraints
​LocalAttachmentReference​A reference to label the attachment. This label must be unique inside this sign order and it is used later in the ExecutionDetails element to connect a signer to an attachment.

​MinLength = 1

MaxLength = 100

​Presentation / Title​The title of the attached document. The title is shown in the UI as the link to the attached document.

MinLength = 4

MaxLength = 60

​DocType / PDF / B64DocumentBytes​The PDF attachment that shall be shown to the user. ​Base64 encoded.

​Merchant

An E-Signing customer may request to get notifications on events related to a sign order. The Merchant structure defines the notification channels and triggers for the customer.

Merchant.png 

​Name​Description​Constraints
​Notification / NotificationChannels ​Several customer notifications channels can be defined in a sign order. ​NA
​Notification / NotificationChannels / NotificationChannel​See the next table for details. ​NA

NotificationChannel

NotificationChannel.png 

​Name​Description​Constraints
​Channel

​The notification channel.

​​[Email | SMS | XMLService]


​Channel / Email / EmailAddress

​This is the receipient e-mail address.

​​Pattern = [a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}

​Channel / SMS / PhoneNumber

​This is the receipient phone number.

​Pattern = \+?[0-9]{4,12}

Note: For SMS notifications, the phone/mobile number must include the international country code before the subscriber number. The international dialing prefix (+) is optional.

​Channel / XMLService / URL

​XMLService notification channel. Must have a valid URL as value.

​NA
​Channel / Fax / PhoneNumber​NA​No longer supported.
​Triggers / Trigger​Each notification channel must have 1..N Trigger elements. This tells E-Signing when to trigger a notification to this channel. Read more about the triggers.[​OnOrderCancellation | OnOrderCompletion | OnOrderRejection | OnOrderExpiration | OnOrderFailed | OnStepReady
OnStepExpiration | OnStepCompletion |
 OnSignProcessRejection |
 OnSignProcessExpiration |
 OnSignProcessCompletion]

​Back to top

​Signers​

There are two types of signers in E-Signing: either a physical person (an end user) or an organisation (the E-Signing customer). The organisation signature is done automatically in E-Signing using the customer's organisational certificate of choice. The end user signer can be presented with either a specific eID or a list of all available eIDs.

Signers.png 

​Name​DescriptionConstraints
​Signer / EndUserSigner

​This element includes information about an end user that should sign one or several documents in the sign order. The EndUserSigner is a “real” person. 

Read more about the EndUserSigner.

​NA
​Signer / MerchantSigner

​The MerchantSigner uses the eID certificate hosted by E-Signing to sign one or several documents in the sign order.

Read more about the MerchantSigner.

​NA

​​​​EndUserSigner​

This element defines the physical signer of a document - the end user. The end user is primarily referred to as the signer.

EndUserSigner.png 

​Name​Description​Constraints
​LocalSignerReference The LocalSignerReference is a reference that defines one specific signer in the InsertOrder message. The reference must be unique inside this message. Several of the other E-Signing messages uses this reference.

​MinLength=1

MaxLength=100

​Name​The name of the signer.

​MinLength=1

MaxLength=100

There is an input validation on this field rejecting names with the “<” and “>” characters.

​​AcceptedPKIs​This element is used to  specify which eID(s) the signer may use to sign documents. If absent, the signer may choose between all eIDs configured for this customer. Read more in the AcceptedPKIs section.

Note: As an option to this element, the forcepkivendor parameter on the sign URL can be used.

​NA
​Notification / NotificationChannels​Several notifications channels for the end user signer can be defined in a sign order. ​NA
​Notification / NotificationChannels / NotificationChannel

A specified notification channel. ​Read more about NotificationChannel.

​NA

​​AcceptedPKIs​

This element defines the different eID(s) the signer can use when signing a document.

AcceptedPKIs2.PNG

​Name​Description​Constraints
​BankID​This element must be added if BankID (NO) is one of the eIDs the signer can use. Read more about BankID.​NA
​BankIDNOMobile​This element must be added if BankID on mobile (NO) is one of the eIDs the signer can use. Read more about BankIDNOMobile.​NA
​NemID​This element must be added if NemID POCES or MOCES with NemID JS (DK) client is one of the eIDs the signer can use. Read more about NemID.​NA
​BankIDSE​This element must be added if BankID (SE) is one of the eIDs the signer can use. Read more about BankIDSE.​NA
​NemID-OpenSign​This element must be added if NemID MOCES with the NemID code file (DK) client is one of the eIDs the signer can use. Read more about NemID-OpenSign.​NA
​PKI-OTP​This element must be added if an OTP eID is one of the eIDs the signer can use. Read more about PKI-OTP.​NA
​Tupas

​This element was previously used when defining a signer with Finnish Bank ID (earlier known as Tupas). It is recommended to use the Nets element for this purpose.

The element is still supported due to backward compatibility. 

​NA
​Nets​This element must be added if an authentication-based signing shall be performed. Read more about Nets. ​NA
​MitID​This element should be added if MitID (DK) is one of the eIDs the signer can use. Read more about MitID. ​NA

BankID

This element is used to defined that the signer can sign with BankID (NO).

   BankIDNO1.PNG 

​Name​Description​Constraints
​IncludeSSN

​The IncludeSSN element should be set if the signer's SSN shall be added to the SDO. The service will request the SSN from BankID and it will be a part of the OCSP response. The OCSP response is added to the SDO. 

Note: The SSN will also be added if the SignerID element has been set to the user's SSN.

​Value: [true]
​CertificatePolicy​This specifies the type of BankID (NO) certificate to accept. If used it is only certificates with this certificate policy that is allowed.​[Personal | PersonalQualified | Employee | EmployeeQualified]
​SignerID / IDType​The identifier type of the signer.

​[SSN | PID]

SSN: Social security number
PID: BankID PID, personal ID present in all BankID end user certificates.

​SignerID / IDValueThe identifier value.​​NA

BankIDNOMobile

This element is used to defined that the signer can sign with BankID on mobile (NO).

BankIDonmobileNO1.PNG 

​Name​Description​Constraints
​IncludeSSN

​The IncludeSSN element should be set if the signer's SSN shall be added to the SDO. The service will request the SSN from BankID and it will be a part of the OCSP response. The OCSP response is added to the SDO. 

Note: The SSN will also be added if the SignerID element has been set to the user's SSN.

​Value: [true]
​​CertificatePolicy​This specifies the type of BankID on mobile (NO) certificate to accept. If used it is only certificates with this certificate policy that is allowed.[​Personal]
​SignerID / IDType​The identifier type of the signer.

​[SSN | PID]

SSN: Social security number
PID: BankID PID, personal ID present in all BankID end user certificates.

​SignerID / IDValue​The identifier value.​​NA

NemID

This element is used to defined that the signer can sign with NemID JS (DK).

NemID1.png

​Name​Description​Constraints
​CertificatePolicy​​This specifies the type of NemID JS (DK) certificate to accept. If used it is only certificates with this certificate policy that is allowed.​[​Personal | Employee]
This element should not be used if the SignerID/CertificatePolicy element is used. 
​SignerID​The SignerID element defines ID of this specific signer. ​​There can be from 0 to 2 SignerID elements. If two elements are used, they must have different SignerID / CertificatePolicy. Two SignerID elements can be used with the NemID Private - on behalf of company ​functionality.
​SignerID / CertificatePolicy​This specifies the type of NemID certificate that can be used. ​​[​Personal | Employee]​
​SignerID / IDType

​The identifier type of the signer.

Note: The IDType value set to SSN and CertificatePolicy set to Employee is not supported.

[​SSN | PID | RID]

SSN: Social security number/national identify number

PID: Personal ID from certificate

RID: Role ID.  

​SignerID / IDValue​The identifier value.​

RID format: “CVR:<CVR number>-RID:<RID number>”
Note: The RID-part is not mandatory.
Ex. “CVR:12345678” or
“CVR:12345678-RID:1234”

BankIDSE

This element is used to defined that the signer can sign with BankID (SE).

BankIDSE.png 

​Name​Description​Constraints
​CertificatePolicy​​This specifies the type of BankID (SE) certificate to accept. If used it is only certificates with this certificate policy that is allowed.​[PersonalSoft |
PersonalSmartcard | PersonalMobile]
​SignerID / IDType​The identifier type of the signer.​[SSN]

SSN: Social security number

​SignerID / IDValue​The identifier value.​​NA

NemID-OpenSign

This element is used to defined that the signer can sign with the NemID CodeFile client (DK). The NemID CodeFile client has replaced the OpenSign applet.

NemID-OpenSign.png 

​Name​Description​Constraints
​CertificatePolicy​​This specifies the type of NemID Code File (DK) certificate to accept. If used it is only certificates with this certificate policy that is allowed.​[​Employ​​​​​​​​​ee]
​SignerID / IDType

​The identifier type of the signer.

Note: SSN was previously supported as IDType. But due to low number of NemID employee certificates with a CPR (SSN) connected to their certificate, this functionality has been removed.

​[​RID]
RID: Role ID.
​SignerID / IDValue​The identifier value.​RID format: “CVR:<CVR number>-RID:<RID number>”
Note: The RID-part is not mandatory.
Ex. “CVR:12345678” or
“CVR:12345678-RID:1234”

PKI-OTP

This element is used to defined that the signer can sign with an OTP eID. This element currently only support customer specific eIDs.

PKI-OTP.png 

​Name​Description​Constraints
​CertificatePolicy​​This specifies the type of eID OTP certificate to accept. If used it is only certificates with this certificate policy that is allowed.​See customer specific documentation.
​SignerID / IDType​The identifier type of the signer.​​See customer specific documentation.
​SignerID / IDValue​The identifier value.​​​See customer specific documentation.
​OTP-Provider​The OTP provider. ​​See customer specific documentation.
​CertCN​This value will be added as the Common Name (CN) to the short term certificate used when signing with an eID OTP.​NA
​CertSN​This value will be added as the Serial Number (SN) to the short term certificate used when signing with an eID OTP.​NA

Nets

This element is used to define that the signer can sign based on an authentication. The AuthenticationID is used to specify the authentication method that the end user can authenticate with.

Read for more information about authentication-based signing.

AcceptedPKIs - Nets.PNG

​Name​Description​Constraints
​Authentication / AuthenticationID​This element indicates the eID that shall be used as the authentication method.  

​Required.

[no_bankid | no_bidmob | no_buypass | dk_nemid_js | dk_nemid-opensign | se_bankid | fi_tupas | fi_mobiilivarmenne | nets_sms | passport_reader | verimi | mitid  | smart_id | mobile_id]

​IncludeSSN
​The IncludeSSN element can be used to decide if the user's SSN shall be included in the SDO or not. If true, the SSN will be added as a part of the attached ID Token in the SDO. This feature is currently supported for AuthenticationID:
    • smart_id (Smart-ID)
    • mobile_id (Mobile-ID)
    • mitid (MitID)
[true]
​SignerID / IDType

​This element can be used to specify the specific signer of the document.

SSN - social security number/ national identifier

PID - an identifer from the authentication.

​Required if SignerID is used.

[SSN | PID]

For Passport Reader: SSN is not supported. PID is supported with value  ID document number.

​SignerID / IDValue​The value of the SignerID.

MitID

This element is used to defined that the signer can sign with MitID through the NemLog-in broker. 

MitID.PNG    

​Name​Description​Constraints
​CertificatePolicyThis element specifies the identity type accepted for this signing.

Optional.

[PersonalQualified]

​SignerID / IDType

​This element can be used to specify the specific signer of the document.

​[​CPR-UUID] (SSN is not yet available in DK)
​SignerID / IDValue​The value of the SignerID.

CPR-UUID: The user's CPR UUID.
SSN: The user's CPR number.

NotificationChannel

This element is used to define a specific notification channel related to a signer.

EUNotificationChannel.png

​Name​Description​Constraints
​Channel

​The notification channel.


​​[Email | SMS | XMLService]

​​Channel / Email / EmailAddress

​This is the receipient e-mail address.

​​Pattern = [a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}

​Channel / Email / EmailText /BodyFragment​NA​Not supported.
​Channel / SMS / PhoneNumber

​This is the receipient phone number.

​Pattern = \+?[0-9]{4,12}

Note: For SMS notifications, the phone/mobile number must include the international country code before the subscriber number. The international dialing prefix (+) is optional.

​Channel / SMS / SMSText / BodyFragment​NA​Not supported.
​Channel / XMLService / URL

​XMLService notification channel. Must have a valid URL as value.

​NA
​Triggers / Trigger​Each notification channel must have 1..N Trigger elements. This tells E-Signing when to distribute a notification to this channel.

​[ OnOrderCancellation | OnOrderCompletion |  OnOrderExpiration | OnOrderRejection |
OnOrderFailed | OnStepReady | OnSignProcessReady |
OnSignProcessExpiration | OnReminderEvent]

​​MerchantSigner​

The MerchantSigner element specifies if the customer's organisation signature shall be applied. The signing is performed with one of the customer's eIDs hosted by E-Signing.

MerchantSigner.png 

​Name​Description​Constraints
​LocalSignerReference​The LocalSignerReference is a reference that defines one specific signer in the sign order. The reference must be unique inside this message. Several of the other E-Signing messages uses this reference.

​MinLength=1

MaxLength=100

​SigningPKIType

​This defines which of the customer's eID to use when signing.

Note: When the Nets value is selected, you will use a Nets ID certificate issued to you by Nets AS Intermediate CA.  Download CA certificates.

For older versions of the schema, EuridaConnect is used instead of Nets.

​[BankID (for Norwegian BankID) | NemID (for Danish NemID) | Nets (for Nets ID and other eIDs ]

Back to top

Organizations​​

A set of organisations can be defined in this element. These will be a part of the sign and procura validation in the B2BPostProcessing element or it can be used with the Private NemID - on behalf of a company​ function​.

Organizations.png

​Name​Description​Constraints
Organization /​LocalOrganizationRef

The LocalOrganizationRef is a reference that defines a specific organisation in the sign order. The reference must be a unique value inside this sign order.

​MinLength = 1

MaxLength=20

Organization /​​OrganizationNumber​The organisation number for a company.

MinLength = 1

MaxLength=20​

​Organization /​AttachBusinessCertificateToSDO​This element indicates whether or not a business certificate shall be downloaded and added to the signed document object (SDO). ​[true | false]
​Organization /​ Country​Country code for this organization.​[NO | SE | FI]

Back to top

​WebContexts

The WebContexts element defines a set of URLs that tells E-Signing where a signer is supposed to perform the sign process and where a signer shall be routed when he/she has signed, if an error occur or if he/she cancels the signing. After inserting the sign order, the E-Signing customer may retrieve a sign URL using the GetSigningProcesses message. This URL is a pointer to a sign process involving a signer and a document. The customer chooses how the sign experience shall be by either presenting the sign proccess embedded on its own sign page or redirects the signer to a standalone Nets page. The sign URL can also be distributed to signers via notification channels. If a signer is registered with the e-mail channel and the trigger OnSignProcessReady  set, the signer will receive an e-mail holding the sign URL when it is his/hers turn to sign.

The SignURLBase is the sign URL prefix. When a sign order is inserted into E-Signing the WebContext is registered for later use. When a customer asks for the sign URL, E-Signing generates a unique reference and appends it to the end of the SignURLBase. Sign URL = SignURLBase + <generated reference>.

Note: All of the below URLs can be overridden by parameters added to the sign URL when presenting the URL for the signer. 

WebContexts.png

​Name​Description ​Constraints
WebContext /​LocalWebContextRefThis element gives a reference to a web context used locally in the sign order. The value must be unique inside the same sign order and several  web context items can be used.

MinLength  = 1

MaxLength = 100

WebContext /​ ​SignURLBase

The SignURLBase is the sign URL prefix that is used to style the link to a specific sign process. When a customer asks for the sign URL,  a unique reference is generated and appended to the end of the SignURLBase. Sign URL = SignURLBase + <generated reference>.  The SignURLBase value might be a URL (https://www.example.com/Sign?sref=), a relative path (/Sign?sref=) or empty.

When the signer accesses the sign URL,  the customer site forwards the signer to E-Signing with the corresponding generated reference.

If this value is an empty string, the reference alone is returned.

Native SignURLBase:

Customer test: https://www.sign-preprod1.nets.eu/sign/index.html?sref=

Production: https://www.sign.nets.eu/sign/index.html?sref=

​NA
​WebContext /​ ErrorURLBase

This element defines the location the signer is sent to if an error occurs. The sign process is performed inside an iframe. If an error occurs, the client in the sign page must break out of the iframe and redirect the user to this URL. An error code is appended to the ErrorURLBase. In addition, the sref parameter can be appended to the URL. This is a configurable feature, please contact support to update your configuration settings.

Example:

http://www.example.com/Sign/Error?err=<value>&sref=<value>

Native ErrorURLBase:

Customer test: https://www.sign-preprod1.nets.eu/sign/status.html?status=

Production: https://www.sign.nets.eu/sign/status.html?status=

​MinLength  = 15

Qualified and well-formed URL.

Parameter that overrides this URL: status=

​WebContext /​ StyleURL

​This URL points to a customer specific css-file used to tailor the user interface.

Example:

http://www.example.com/style.css

Native StyleURL:

Customer test: https://www.sign-preprod1.nets.eu/sign/signng.css

Production: https://www.sign.nets.eu/sign/signng.css​

​MinLength  = 15​

Qualified and well-formed URL.

Parameter that overrides this URL:

style=

​WebContext / ExitURL

​This is the URL where the signer is redirected upon sign completion. The sign process is performed inside an iframe. Upon sign completion, the client in the sign page must break out of the iframe and redirect the user to this URL. The sref parameter can be appended to the URL. This is a configurable feature, please contact support to update your configuration settings.

Example URL:

http://www.example.com/SignComplete?sref=<value>

Native ExitURL:

Customer test: https://www.sign-preprod1.nets.eu/sign/receipt.html?status=

Production: https://www.sign.nets.eu/sign/receipt.html?status=

​MinLength  = 15

Qualified and well-formed URL.

Parameter that overrides this URL: exit=

​WebContext / AbortURL

This element defines the URL where the signer is directed if he/she chooses to terminate or cancel the signing. The sref parameter can be appended to the URL. This is a configurable feature, please contact support to update your configuration settings.

Example URL:

http://www.example.com/Abort?sref=<value>

Note: The abort page in E-Signing gives the end user an opportunity to reject the sign process. If the user rejects, the status on the sign process will be updated to RejectedBySigner. If the customer implements its own abort page they need to perform the ModifySigningProcess message to update the sign process status. If the AbortURL is not present, a default E-Signing AbortURL is used: https://www.sign-preprod1.nets.eu/sign/status.html?statuscode=cancel&sref=<value>

If you want to use E-Signing default AbortURL, leave this element empty.

​MinLength  = 15

​Qualified and well-formed URL.

Parameter that overrides this URL: cancel=

Back to top

ExecutionDetails​

Execution details are a set of rules that the E-Signing customer wishes to impose on the sign order. These can be used to specify the following aspects of signing:

  • Outline which documents are assigned to the different signers.
  • The order in which documents are signed. E-Signing allows for parallel, sequencial or a combination of both. Read more about the sign workflow.
  • A deadline before which documents must be signed. Each document and signer can be specified with a deadline.
  • Validity period of a sign URL (whether they are for multiple or single use)

   ExecutionDetails_1.PNG 

​Name​Description​Constraints
​OrderDeadlineThe order deadline. Must be a date and time after the current time (when the order is placed) ​Must be after now and max 90 days in the future.
​DisplayProcessInfo​Information displayed in the web interface below the signing applet, and it is visible to all signers of a document. The information is presented per document

Name: Displays the name of the signers that have signed or are supposed to sign a document.

NameStatus: Displays the name and status of the signers that have signed or are supposed to sign the document.

NameStatusTime: Displays the name, status and sign time of the Signers that have signed a document.

​[Name | NameStatus | NameStatusTime]
​GenerateOneTimeURLs​If true, E-Signing will generate new URLs (references) each time a URL is requested. A URL (ref) can ONLY be used once. After the URL is requested it is valid for 10 min. The customer may at any time request E-Signing to generate a new URL for a signer.​[true | false]
​Steps​Must contain 1 to 15 number of Step elements. The Step element is described further down.

​Min= 1 element

Max = 15 elements

​OutputFormat

​E-Signing offers two output formats; SDO and PAdES. 

If nothing is set, the output format will be SDO.

Note: The PAdES  output format is currently only supported by BankID NO and MitID through the NemLog-in broker. When PAdES is set, it will not be possible to get a SDO returned for this order. If SDO is set, a PAdES generated from the SDO may be returned if requested.

​Optional

[PAdES | SDO]

SDO is default.

Steps

The Steps element contains one or more Step element that again can hold a set of SigningProcess elements. See the definitions of steps and sign processes here.

InsertOrder-executiondetails.png 

​Name​Description​Constraints
​Step / StepNumber​Must in ascending order starting from 1 and to the number of steps in the sign order. ​Non negative integer
{1, 2, ... 15}
​Step / StepDeadline

​Step deadline.

If the StepDeadline is not present in the InsertOrder request, the system sets the StepDeadline value to the OrderDeadline value.

​The StepDeadline value must be before the OrderDeadline value. If the StepNumber is greater than 1 then the StepDeadline value must always be after the StepDeadline of the preceding step and before the next step’s deadline.
​Step / SigningProcess

A step must contain one to an infinite number of SigningProcess elements.

A SigningProcess element is where it all gets tailored into a process. In the sign process the customer has to combine a document, a signer and optionally a web context. Combined, this information reveals who is signing what document and at which location it all is going to be processed.

​NA
​Step / SigningProcess / LocalWebContextRef​This must be a LocalWebContextRef predefined in a WebContext element.

​MinLength  = 1

MaxLength = 100

​Step / SigningProcess / LocalDocumentReferenceThis must be a LocalDocumentReference predefined in a  Document element.

​MinLength = 1

MaxLength = 100


​Step / SigningProcess / LocalSignerReference​This must be a LocalSignerReference predefined in a Signer element.

​MinLength=1

MaxLength=100

​​Step / SigningProcess / LocalOrganizationRef​This points to a LocalOrganizationRef defined in an Organization element. If this is set, a verification towards ID-Rights will be performed to check that the signer can act on behalf of this organisation.
​​​​​​

​MinLength = 1

MaxLength=20

This element can only  be used with the Private NemID - on behalf of a company​.
​Step / SigningProcess / LocalAttachmentReferences / LocalAttachmentReference​The LocalAttachmentReference points to an attachment defined in the Attachments element and connects the attachment to a specific signer and document.

​MinLength = 1

MaxLength = 100

 

​Optional.

 

​Step / SigningProcess / SigningProcessDeadline

​The sign process deadline. Must be after now and before the step deadline. If the StepDeadline value is absent then the value must be before the mandatory OrderDeadline value.

If the SigningProcessDeadline is absent, the system sets the value to the StepDeadline.

Must be before the StepDeadline​
​Step / SigningProcess / ReminderSettings​A signer will be reminded, if he has a Trigger called OnReminderEvent set, at this Interval from the StartTime to the SigningProcessDeadline.​NA
​​Step / SigningProcess / ReminderSettings / StartTimeThis must be after now and before the sign process deadline​Must be before the SigningProcessDeadline.
​​Step / SigningProcess / ReminderSettings / Interval​A reminder notification is sent to a signer from StartTime and every Interval​Integer representing hours.
​Step / SigningProcess / TerminateOrderOnSignerRejection ​If true, the sign order state is set to Rejected if a signer rejects this sign process. If false, the signer may reject this sign process without “terminating” the sign order. The sign process is considered Complete even if the signer rejected to sign the document.​[true | false]

Back to top

MetaData​

The MetaData structure enables the customer to set its own “labels” on this sign order.

MetaData.png 

​Name​Description​Constraints
​NameValuePair ​A name and value pair. A MetaData element may include from 1 to 10 NameValuePair elements.​NA
​NameValuePair / Name

​Name of meta data.

Some meta data names are reserved. See the Reserved metadata table below. 

​MinLength =  1

MaxLength =  50

​NameValuePair / ValueThe value of this meta data.​

MinLength =  1

MaxLength =  50​

Reserved metadat​a​​

​Name​Description
​Notification_CustomerName​By using this Name in a sign order, any e-mail notifications sent from Nets to the customer will replace the customer name from Nets database with the value given in the Value element in the e-mail notification.

<Name>Notification_CustomerName</Name>
<Value>INSERT THE NEW CUSTOMER NAME</Value>

Back to top

B2BPostProcessing​

The B2BPostProcessing structure are used to define the mapping between organizations, documents and the signers that will be included in a sign and procura verification. The sign and procura verification are using the Nets ID-Rights service.

B2BPostprocessing.png

​Name​Description​Constraints
SignAndProcuraVerifications / SignAndProcuraVerification / LocalOrganizationRefThis must be a LocalOrganizationRef predefined in an Organizations element.

​MinLength = 1

MaxLength=20

SignAndProcuraVerifications / SignAndProcuraVerification / LocalDocumentReference​This must be a LocalDocumentReference predefined in a Documents element.

​MinLength = 1

MaxLength = 100

SignAndProcuraVerifications / SignAndProcuraVerification / Signers / LocalSignerReferenceThis must be a LocalSignerReference predefined in a Signers element. Several signers can be defined.

​MinLength=1

MaxLength=100

SignAndProcuraVerifications / SignAndProcuraVerification / TerminateOnSPCheckFails​Determines if the sign order should be set to failed-status in case of a negative answer to the signature and procura check query.​[true | false]
SignAndProcuraVerifications / SignAndProcuraVerification / SignOrProcuraSet to sign if it is a signature check and to procura if it is the procura that shall be checked. [sign | procura]​

Back to top

PostProcessing​​

The PostProcessing element includes functions that are processed after all signatures in a sign order have been performed. This includes archival to the Nets E-Archive and other customer specific archives.

Postprocessing.png 

​Name​Description​Constraints
​ArchiveDefinitions / Archive​This structure holds the archive information. There may be several Archive elements, for example one for each document in the sign order. ​NA

Archive

​If the Archive element is present, E-Signing will archive the signed document (in SEID SDO format) to the selected archive with the given indexes and values. The structure gives the possibility to set archival indexes on each separate document in a sign order. It also gives the possibility to archive to a customers sub archive or to another organisations logical archive. An example of this usage is if the customer is available in different countries and would like to separate the signed documents dependent of the originated country.

Archive.png

​​Name​Description​Constraints
​ArchiveName​Name of the archive the document shall be archived in.​[eArchive]
​ObjectRef / LocalDocumentReference​A reference to the signed document that shall be archived. This is a reference to an earlier defined document.

​MinLength = 1

MaxLength = 100

​ObjectRef / LocalOrganizationRef​A reference to an organisations company certificate. This may only be used if the customer is using ID-Rights together with E-Signing.

​MinLength = 1

MaxLength=20

​ArchiveData / Index / Key​An Index key. Each archive type (ArchiveName) has optional and mandatory Index keys. The name of the index is set in this element. See the table below and archive documentation for possible indexes.​NA
​ArchiveData / Index / Value

​The value of an index is set in this element.  See the table below and archive documentation for possible index values.

 

The index values must be in the ISO 8859-1 range as Nets archives only support indexes with the character set.

​MetaDataList / MetaData / Key​The MetaData key is a predefined key.

The orgNumber tells which organisation’s archive to use and gives the possibility to archive to another organisation’s archive.  Only whitelisted organisation numbers can be used for the orgNumber key.
The subArchiveName is a possible sub archive of your E-Archive setup. Your subArchiveName is found in the E-Archive portal under “eArchive admin”.

​[orgNumber | subArchiveName]

When eArchive is used as the value in the ArchiveName element, it is mandatory to specify the subArchiveName and the orgNumber.

MetaDataList / MetaData / Index​​The value of the MetaData is set in this element.​NA

When archiving to the Nets E-Archive through E-Signing, there are some general indexes that must be set by the customers and some indexes that are set by the E-Signing service. In addition, the customer may set their own indexes. The indexes that are required set by the customer and the ones set by E-Signing are listed in the table below. Other customer specific indexes are not added here, and the customer should check their E-Archive settings to find information about those.

​Index key​Constraints
​documentID​This index is set by E-Signing, and the customer shall not use this.
​mimeType​This index is set by E-Signing, and the customer shall not use this.
​documentDate​This index is set by E-Signing, and the customer shall not use this. The index value will be set to the seal time of the SDO from E-Signing.
​externalRef​This value should not be used by customers. This index will be mapped to the OrderID in E-Signing in E-Archive.
​documentGroup​This value should not be used by customers. Automatically set by E-Archive.
​documentType​This value must be set by customers, and each customer has predefined set of values for this index. Please check your archive settings for correct values. If wrong values are used, the document may be seen as a rejected document in the E-Archive portal.
<PostProcessing>
  <ArchiveDefinitions>
    <Archive>
      <ArchiveName>eArchive</ArchiveName>
      <ObjectRef>
        <LocalDocumentReference>text1</LocalDocumentReference>
      </ObjectRef>
      <ArchiveData>
        <Index>
          <Key>indexname1</Key>
          <Value>indexvalue1</Value>
        </Index>
        <Index>
          <Key>indexname2</Key>
          <Value>indexvalue2</Value>
        </Index>
        <Index>
          <Key>indexname3</Key>
          <Value>indexvalue3</Value>
        </Index>    
     </ArchiveData>
      <MetaDataList>
        <MetaData>
          <Key>orgNumber</Key>
          <Value>999888777</Value>
        </MetaData>
        <MetaData>
          <Key>subArchiveName</Key>
          <Value>documents</Value>
        </MetaData>
      </MetaDataList>
    </Archive>
  </ArchiveDefinitions>
</PostProcessing>

 

Back to top

CustomProperties

A set of additional data related to one or all signers can be defined in this element. The properties will be add to the SDO as an extra signature on the document. There is no validation of the data in the CustomProperties, and these are returned in the SDO as they were specified in the sign order. 

Note: CustomProperties can't be used if the OutputFormat is set to PAdES. 

CustomProperties.PNG

​Name​Description​Constraints
​Property / LocalSignerReference​Optional reference to one of the signers in the sign order. If this element is not present, it means that the property is for all signers in the sign order.

​MinLength=1

MaxLength=100

​Property / Name​Custom name of the property.  Reserved property names are listed below.

​MinLength = 1

MaxLength = 80

​Property / Value​Custom value of the property

​MinLength = 1

MaxLength = 200

Reserved property name

There are some Name values that are reserved.

​Name​Intended use
​OrganisationNumber

​This name is reserved for organisation numbers. The organisation number will be displayed in the Organisation field in a PAdES document.

​document-open-time​The time when the signer opened the document. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​authentication-completed-time​The time when the authentication used in authentication-based signing was completed. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​signer-ip-address​The IP address of the signer. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​user-agent​The user agent of the signer. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​signing-time​The time when the document was signed. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​id-token​The ID Token from the authentication taken place as part of authentication-based signing. This custom property value is reserved when using authentication-based signing. The value will be returned in the signed document (SDO).
​national-identifier
​The national identifier (SSN) may for some eIDs be returned as a custom property. 

How will this look like in the SDO?:

Note: If the SignatureRef value is set this refers to a specific signer. This will be the case if the LocalSignerReference is used. If the SignatureRef is set to [1] this refers to the first signature in the SDO, if set to [2] it refers to the second signature and so on.

<AdditionalSignatureProperties xmlns="http://www.nets.eu/e-signing/additional-signature-properties" CreateTime="2019-05-23T16:40:32.956+00:00" Version="1.0">
	<CustomProperties DocumentDigest="2.16.840.1.101.3.4.2.1:j/9pWQJlux2wUDW1+cNvDV3xX2g7GnSdbrGH+Ycjr3E=">
		<Properties SignatureDigest="2.16.840.1.101.3.4.2.1:HHTvf/+w4LK2f/cZ06gIqTDD8dfBncn3DtJmJC9xPG8=" SignatureRef="(//sdo:SignatureElement)[1]">
			<Property name="OrganisationNumber">123456789</Property> 
			<Property name="casenumber">123456789</Property> 
		</Properties>
	</CustomProperties>
</AdditionalSignatureProperties>

 

Back to top 

InsertOrder response

InsertOrderResponse-(002).png 

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.

​MinLength = 1

MaxLength = 80

​Transref

​String uniquely identifying the transaction in E-Signing.

​NA