Step 2

Topics found on this page:

• Set up E-Sign​ing client API​

• Create a sign order
• Retrieve sign URL

Set up E-Signing client API​​​

The E-Signing client API communicates with the E-Signing service through XML messages. These are sent using HTTP. All XML messages to E-Signing must be signed with a Nets issued certificate. The E-Signing client API can be used to sign and send all XML messages.

In order to use E-Signing client API, it should first be initialized with required details as listed below:

1. PKCS12 file with Nets issued certificate.
2. JKS truststore with Nets E-Signing server SSL certificate.
3. Communication timeout.
4. Environment to connect to (customer test or production).
5. MerchantID (issued by Nets for each customer).
6. Customer (merchant) name.

Sample code provided below does the initialization (detailed code is available in demo app source files).

MerchantContext merchantcontext = new MerchantContext();

string path = "/path-to-resource-folder/";
string signAuthStore = path + "keystore.p12";
string truststorePath = path + "truststore.p12";

//Keystore stream  
FileStream kfs = File.Open(signAuthStore, FileMode.Open, FileAccess.Read, FileShare.Read);
merchantcontext.setKeystoreStream(kfs);
merchantcontext.setKeystorePwd("keystore password");

//Truststore stream
FileStream tfs = File.Open(truststorePath, FileMode.Open, FileAccess.Read, FileShare.Read);
merchantcontext.setTruststoreStream(tfs);
merchantcontext.setTrustKeystorePwd("truststore password");

merchantcontext.setEnv(ESignEnvironment.PRE_PRODUCTION);
merchantcontext.setMerchantId("012345");
merchantcontext.setMerchantName("Demo App");

ESigningFactory fac = new ESigningFactory();
fac.registerMerchantContext(merchantcontext);

 MerchantContext merchantContext = new MerchantContext();
 merchantContext.setSslKeystorePath("/path_to_file/esigndemoapp.p12");
 merchantContext.setSslKeystorePwd("XXXXXX");
 merchantContext.setSigningKeystorePath("/path_to_file/esigndemoapp.p12");
 merchantContext.setSigningKeystorePwd("XXXXXX");
 merchantContext.setTruststorePath("/path_to_file/esigntruststore.jks");
 merchantContext.setTruststorePwd("YYYYYY");
 merchantContext.setTruststoreType(KeyStoreType.JKS);
 merchantContext.setCommTimeout(10000);
 //Environment.PRE_PRODUCTION is an enum value, includes Nets E-Signing service URL
 merchantContext.setEnv(Environment.PRE_PRODUCTION);
 merchantContext.setMerchantId("1587");
 merchantContext.setMerchantName("Demo Merchant");

 ESigningFactory.INSTANCE.registerMerchantContext(merchantContext);

Create a sign order

A sign order is created when an InsertOrder XML message is sent to Nets E-Signing service. A basic InsertOrder XML message should contain the following (for one document and one signer):

1. MerchantID (issued by Nets).
2. OrderID, a unique ID to identify the sign order. Read more about the OrderID.
3. Document details, such as:
1. Document reference (unique string value to reference the document in the XML message).
2. Type, description and title of the document.
3. Document bytes in base64 format.
4. Signer details, such as:
1. Signer name.
2. Allowed eIDs.
3. Personal ID to identify the signer (for the eID).
4. Signer reference (unique string value to reference signer in the XML message).
5. Web context details (Read more about web context), such as:
1. Exit URL.
2. Abort URL.
3. Error URL.
4. Style URL.
5. Sign URL Base
6. Execution details (signing workflow rules connecting signer and document)

Sample code for sending an InsertOrder XML message through E-Signing client API to E-Signing is included below (detailed code is available in demo app source files).

The InsertOrder method (refer sample code below) from E-Signing client API creates an XML message with the details provided, signs the XML message and sends it to E-Signing.

Create a sign order: 
https://www.nets.eu/developer/E-Signing/getstarted/Pages/Step2.aspx#setupasignorder
---------------------

// Create order message

InsertOrder order = TSMHelper.tsmInsertOrder(orderID);

// Document

byte[] textDocumet = System.Text.Encoding.UTF8.GetBytes("This is a text document");
TSMBuilder.addTextDocument(order, "doc-ref-1", "title1", "descr1", textDocumet, false, null);

// End user signer

InsertOrderSignersSigner signer = TSMBuilder.createEndUserSigner(order, "signer-ref");

// BankID example
acceptedPKIsTypeDefBankID bankIDNO = TSMBuilder.createBankIDNO();
TSMBuilder.setBankIDNOSSN(bankIDNO, "12345678912");
TSMBuilder.addSignerPKI(order, signer, bankIDNO);

// Authentication Based Signing example
List<netsPKITypeDefAuthentication> netsABS = TSMBuilder.createNetsABS();
TSMBuilder.addNetsAuthentication(netsABS, "nets_sms");
TSMBuilder.addNetsAuthentication(netsABS, "se_bankid", netsPKITypeDefAuthenticationSignerIDIDType.PID, "0210589209");
TSMBuilder.addNetsAuthentication(netsABS, "fi_tupas", netsPKITypeDefAuthenticationSignerIDIDType.SSN, "010200A9618");
TSMBuilder.addSignerPKI(order, signer1, netsABS);

TSMBuilder.addSigner(order, signer);

// Web contexts

TSMBuilder.addWebcontext(order, "webcontext-ref", 
	"https://www.sign-preprod1.nets.eu/sign/index.html?ref=", 
	"http://styleurl/is/nice", 
	"http://exiturl/why-does-this-fail", null, 
	"http://error.url.base");

// Execution details

TSMBuilder.createExecutionDetails(order, DateTime.Now.AddDays(1), InsertOrderExecutionDetailsDisplayProcessInfo.NameStatusTime, true);
stepTypeDef step1 = TSMBuilder.createStep(order, null);
signingProcessTypeDef signingprocess1 = TSMBuilder.createSigningProcess("signer-ref", "doc-ref-1", "webcontext-ref", null, false);
TSMBuilder.addSignProcessToStep(step1, signingprocess1);
TSMBuilder.addStepToOrder(order, step1);

 ESigningFacade facade = ESigningFactory.INSTANCE.getESigningFacade("Demo Merchant");

 InsertOrderRequest request = new InsertOrderRequest();
 request.setMerchantID(1587);
 request.setMessageID("esigndemoapp-msgid-1");
 request.setTime(new Date());
 request.setAdditionalInfo("Additional_info");
 request.setOrderID("1587-demo-742819356");

 Doc document = new Doc();
 PDF pdf = new PDF();
 pdf.setB64DocumentBytesAsString("Base64_PDF_Bytes");
 document.setDocType(pdf);
 doc.setDesc("Document description");
 doc.setLocalDocRef("document1");
 doc.setTitle("Document title");
 request.setDocuments(new ArrayList<>(Arrays.asList(document)));

 Signer signer = new Signer();
 signer.setName("Signer");
 //for BankID eID
 BankID bankId = new BankID();
 SignerID signerId = new SignerID();
 signerId.setIdType("SSN");
 signerId.setIdValue("12345678912");
 signer.setLocalSignerRef("signer1");
 signer.setAcceptedPKIs(new ArrayList<>(Arrays.asList(bankId)));
 request.setSigners(new ArrayList<>(Arrays.asList(signer)));

 WebContext webContext = new WebContext();
 webContext.setExitURL("http://localhost:8080/verify?status=completed");
 webContext.setAbortURL("http://localhost:8080/verify?status=canceled");
 webContext.setErrorURLBase("http://localhost:8080/error.html");
 webContext.setStyleURL("http://localhost:8080/esign/style.css");
 webContext.setSignURLBase("https://www.sign-preprod1.nets.eu/sign/index.html?ref=");
 webContext.setLocalWebContextRef("webctx1");
 request.setWebContexts(new ArrayList<>(Arrays.asList(webContext)));

 ExecutionDetails executionDetails = new ExecutionDetails();
 executionDetails.setOrderDeadline(new Date(System.currentTimeMillis() + 86400000));
 executionDetails.setDisplayProcessInfo("NameStatusTime");

 Step step1 = new Step();
 step1.setStepNumber(1);
 SigningProcess signingProcess = new SigningProcess();
 signingProcess.setLocalDocumentReferance("document1");
 signingProcess.setLocalSignerReferance("signer1");
 signingProcess.setLocalWebContextRef("webctx1");
 step1.addSigningProcess(signingProcess);

 executionDetails.addStep(step1);
 request.setExecutionDetails(executionDetails);

 InsertOrderResponse response = facade.insertOrder(request);

​On receiving the signed XML message, E-Signing service validates the signature in the incoming message and authenticates the customer. On successful authentication, the XML message is taken for further processing. Once the processing is completed, the E-Signing service sends an OK response back to the customer (received as InsertOrderResponse object as in the code above).

More detailed information on sign order can be found here.

​Retrieve sign URL​

On successful InsertOrder response, GetSigningProcesses XML message should be sent to E-Signing to retrieve a sign URL. The E-Signing client API can be used to send this message. A basic GetSigningProcesses XML message should contain the following:

1. MerchantID (as provided by Nets)
2. OrderID (the unique ID that was sent in the InsertOrder XML message)
3. Signer reference (that was sent in InsertOrder XML message)

Sample code for retrieving sign URL from E-Signing is provided below (detailed code is available in demo app source files). 

 ESigningFacade facade = ESigningFactory.INSTANCE.getESigningFacade("Demo Merchant");
 
 GetSigningProcessesRequest req = new GetSigningProcessesRequest();
 req.setOrderID("1587-demo-742819356");
 req.setMerchantID(1587);
 req.setMessageID("esigndemoapp-msgid-2");
 req.setTime(new Date());
 req.setLocalSignerReference("signer1");

 GetSigningProcessesResponse response = facade.getSigningProcesses(req);

 ArrayList<SigningProcessResult> signprocesses = response.getSigningProcessResults();
 if (null != signprocesses) {
	for (SigningProcessResult sp : signprocesses) {
		String signUrl = sp.getSignURL();
	}
 }

Read more about the GetSigningProcesses xml message.
 

Continue to Step 3 >