To send documents for signing, please use the following steps:
emSigner uses TLS and Data encryption in transit to protect your documents. To achieve this, the signer gateway uses a combination of a random session key and public key to encrypt both the request and session key
Encrypt unique session key for each request
Every session key needs to be encrypted with Public Key of emSigner which will be shared as a .CER file. Please contact us if you already did not receive this file
Create JSON Payload
For PDF Files
Parameter | Data Type | Description |
---|---|---|
Please use the parameters below to construct the JSON payload for PDF file signing | ||
Filetype* | String | Filetype=PDF, If file is PDF format. |
File* | String | Compress the file using 7zip (Optional) and pass compressed base 64 string of file that needs to be signed. If you are compressing the document make sure you send additional parameter i.e. IsCompressed as TRUE, otherwise FALSE. Compression ratio is high for XML and DATA, whereas for PDF it is only 10% (Varies with size of the document). To know how to compress file, refer the section at the bottom of this page |
IsCompressed | Boolean | Set to "True" if compressed data is sent. Otherwise "False" |
ReferenceNumber * | String | Pass unique random number as reference number for each transaction request. Maximum of 20 characters. Example: 1213 Note: You can pass timestamp as a reference number to create uniqueness. You are not allowed to pass reference number which has been used for any of the previous transactions. |
Name* | String | Pass the name of the signatory which will be displayed along with the signature. |
Authtoken * | String | Pass valid unique Authtoken generated for your account. |
SignatureType* | Integer | This parameter describes the signature mode to be enabled for completing the request. Currently, we support the following signature options i.e. dSign, eSign, eSignature, Digital Signatures (tokens), eSign 2.1 and eSign 3.2 and other signing types from third party trust service providers from time to time Digital Signature: Requires Crypto Token and valid digital signature issued by licensed Certifying Authorities to digitally sign the request. eSignature: eSignature is not valid in India, but it is widely accepted in other countries. eSign : eSign (Aadhar based signing) is valid ONLY in India. Specify below signature type values (comma separated) if you need specific signature options to be enabled in our gateway page. SignatureType=2, if you need digital signature as a signature option. SignatureType=3, if you need eSign as a signature option. SignatureType=4, if you need eSignature as signature option. |
SignerID | String | This is an optional parameter. Value for this parameter can be passed if “eSign” Signature type is selected as one of the signature type values e.g xyz.123 |
IsCosign | Boolean | By default, this parameter would contain a FALSE value. Set this to TRUE, if you want to sign the document multiple times with different signatories. For security reasons, if you have only one signatory signing the document pass as false and also for the last signatory of your workflow/business flow you need to pass false so that document will not be allowed for further signing. |
SelectPage* | String | Signature placeholder specification on which page the signature has to be added. Specify SelectPage=ALL, if you need a signature on all the pages of the document. SelectPage=FIRST, if you need a signature on the only first page of the document. SelectPage=LAST, if you need a signature on only last page of the document. SelectPage=EVEN, if you need a signature on all even pages of the document. For example: If the document consists of 10 pages then second, fourth, sixth, eighth and tenth pages contain a signature. SelectPage=ODD, if you need a signature on all odd pages of the document. For example: If the document consists of 10 pages then first, third, fifth, seventh and ninth pages contain a signature. SelectPage=SPECIFY, if you want to specify page numbers. For specifying page level coordinates, you need to pass additional parameter i.e. PageNumber which is explained below. SelectPage=PAGE LEVEL, if you want to specify page coordinates. For specifying page level coordinates, you need to pass additional parameter i.e. PagelevelCoordinates which is explained below. |
PageNumber | Integer | Pass page numbers separated with a comma, where you wanted to see the signature in the document. For example: 1,2 Note: This is mandatory if SelectPage is SPECIFY. |
PagelevelCoordinates | String | Specify coordinates of page level as
PagelevelCoordinates= Pagenumber1,left,top,width,height;Pagenumber2,left,top,width,height For example: In 10 pages document you wanted the document to be signed on 1st and 6th page with some co-ordinates then specify PagelevelCoordinates = 1,7,10,60,120;6,45,20,60,120 Note: This is mandatory if SelectPage is PagelevelCoordinates. |
SignaturePosition* | String | Signature placeholder specification where the signature has to be placed on a page. Specify SignaturePosition =Top-Left, if you need a signature on a top left position of the document. SignaturePosition =Top-Center, if you need a signature on a top center position of the document. SignaturePosition =Top-Right, if you need a signature on a top right position of the document. SignaturePosition =Middle-Left, if you need a signature on a middle left position of the document. SignaturePosition =Middle-Right, if you need a signature on a middle right position of the document. SignaturePosition =Middle-Center, if you need a signature on a middle center position of the document. SignaturePosition =Bottom-Left, if you need a signature on a bottom left position of the document. SignaturePosition =Bottom-Right, if you need a signature on a bottom right position of the document. SignaturePosition =Bottom-Center, if you need a signature on a bottom center position of the document. SignaturePosition =Customize, if you want to specify page coordinates. For specifying customize coordinates, you need to pass additional parameter i.e. CustomizeCoordinates which is explained below. |
CustomizeCoordinates | String | CustomizeCoordinates=left,top,width,height For example: In 10 pages document you wanted the document to be signed on particular positions then specify CustomizeCoordinates=7,10,60,120 Note: This is mandatory if SignaturePosition is Customize. |
PreviewRequired | Boolean | By default, this will be FALSE. If you want to show preview to the user when redirected to emSigner signer gateway page. Pass TRUE if the preview is required before signing the document. |
Enableuploadsignature | Boolean | By default this will be FALSE, if enabled then the user will have the option to upload handwritten signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document And using this option will invalidate any signed document sent for signing again by another signatory. Pass TRUE if you want to enable upload signature option in the gateway. Note: If the user selects signature type as eSignature or combination of that, then at that time any of the parameter i.e. enable eSignature pad/enable draw signature/enable font signature/enable upload signature is mandatory. For digital signature, it is not mandatory. |
Enablefontsignature | Boolean | By default this will be FALSE, if enabled then the user will have the option to choose or generate some font based signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document And using this option will invalidate any signed document sent for signing again by another signatory. Pass TRUE if you want to enable font based signatures to be visible in the gateway. Note: If the user selects signature type as eSignature or combination of that, then at that time any of the parameter i.e. enable eSignature pad/enable draw signature/enable font signature/enable upload signature is mandatory. For dSign, it is not mandatory. |
EnableDrawSignature | Boolean | By default this will be FALSE, if enabled then the user will have the option to draw signature in emSigner Signer Gateway page and the same will be affixed on the signed PDF document And using this option will invalidate any signed document sent for signing again by another signatory. Pass TRUE if you want to enable draw signature option in the gateway. Note: If the user selects signature type as eSignature or combination of that, then at that time any of the parameter i.e. enable eSignature pad/enable draw signature/enable font signature/enable upload signature is mandatory. For dSign, it is not mandatory. |
EnableeSignaturePad | Boolean | By default this will be FALSE, if enabled then the user will have the option to connect to third-party signature pads. Currently, we support Topaz signature pad in emSigner Signer Gateway page and the same will be affixed on the signed PDF document and using this option will invalidate any signed document sent for signing again by another signatory. Pass TRUE if you want to enable eSignature pad option in the gateway. |
Storetodb | Boolean | By default this value would be FALSE. Pass it as TRUE if you want to save the response data with us. In case of failure you can request us by calling our API's before 48 hours (If Storetodb=TRUE). |
EnableViewDocumentLink | Boolean | By default thisvalue willbe TRUE. Pass FALSE if document view link is not required. Note: Document link will be displayed only when preview is not enabled. If Preview required is TRUE then set "EnableViewDocumentLink" as FALSE. |
SUrl* | String | Pass success URL, so that after successful signing signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Furl* | String | Pass failure URL, so that when there is a failure, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Curl* | String | Pass cancel URL, so that when customer cancels the signer gateway process in the middle, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Parameter | Data Type | Description |
---|---|---|
Please use the parameters below to construct the JSON payload for PDF file signing | ||
Filetype* | String | Filetype=XML, if file is XML format. Filetype=DATA, if file is Text format. |
File* | String | Compress the file using 7zip (Optional) and pass compressed base 64 string of file that needs to be signed. If you are compressing the document make sure you send additional parameter i.e. IsCompressed as TRUE, otherwise FALSE. Compression ratio is high for XML and DATA, whereas for PDF it is only 10% (Varies with size of the document). To know how to compress file, refer to this section. |
IsCompressed | Boolean | Set to "True" if compressed data is sent. Otherwise "False" |
ReferenceNumber * | String | Pass unique random number as reference number for each transaction request. Maximum of 20 characters. Example: 1213 Note: You can pass timestamp as a reference number to create uniqueness. You are not allowed to pass reference number which has been used for any of the previous transactions. |
Authtoken * | String | Pass valid unique Authtoken generated for your account. |
SignatureType* | Integer | This parameter describes the signature mode to be enabled for completing the request. Currently, we support the following signature options i.e. digital Signature, eSign, eSignature and other signature types from trust service providers Digital Signature: Requires Crypto Token and valid digital signature issued by licensed Certifying Authorities to digitally sign the request. eSignature: eSignature is not valid in India, but it is widely accepted in other countries. eSign : eSign (Aadhar based signing) is valid ONLY in India. Specify below signature type values (comma separated) if you need specific signature option to be enabled in our gateway page. SignatureType=2, if you need digital signature as a signature option. SignatureType=3, if you need eSign as a signature option. SignatureType=4, if you need eSignature as signature option. |
SignerID | String | This is an optional parameter. Value for this parameter can be passed if “eSign” Signature type is selected as one of the signature type values e.g xyz.123 |
Storetodb | Boolean | By default this value would be FALSE. Pass it as TRUE if you want to save the response data with us. In case of failure you can request us by calling our API's before 48 hours (If Storetodb=TRUE). |
EnableViewDocumentLink | Boolean | By default thisvalue willbe TRUE. Pass FALSE if document view link is not required. Note: Document link will be displayed only when preview is not enabled. If Preview required is TRUE then set "EnableViewDocumentLink" as FALSE. |
SUrl* | String | Pass success URL, so that after successful signing signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Furl* | String | Pass failure URL, so that when there is a failure, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Curl* | String | Pass cancel URL, so that when customer cancels the signer gateway process in the middle, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Parameter | Data Type | Description |
---|---|---|
Please use the parameters below to construct the JSON payload for PDF file signing | ||
Filetype* | String | Filetype=Hash, if file is an array of hashes. |
Documentdetails | JSON Array | Pass Documentdetails in JSON array format with below details DocumentName: Name of document that needs to be signed. DocumentURL: URL of the document. Should be a HTTP / HTTPS URL for the document, accessible by the signer during the transaction permitted duration (maxUserWait Time). DocumentHash: Sha256 Hash of the document to be signed. Sample Documentdetails Json: [ { "DocumentName": "Document1", "DocumentURL": "https://www.xyz.com/document1", "DocumentHash": "96cac442e493b6e8dd97e2a28dc60d43ed6ff7c6e6d3a0e0490cfcb700046a4b" }, { "DocumentName": "Document2", "DocumentURL": "https://www.xyz.com/document2", "DocumentHash": "96cac442e493b6e8dd97e2a28dc60d43ed6ff7c6e6d3a0e0490cfcb700046a4a" }] Note: This array should contain max 5 document. |
IsCompressed | Boolean | Set to "True" if compressed data is sent. Otherwise "False" |
ReferenceNumber * | String | Pass unique random number as reference number for each transaction request. Maximum of 20 characters. Example: 1213 Note: You can pass timestamp as a reference number to create uniqueness. You are not allowed to pass reference number which has been used for any of the previous transactions. |
Authtoken * | String | Pass valid unique Authtoken generated for your account. |
SignatureType* | Integer | This parameter describes the signature mode to be enabled for completing the request. Currently, we support the following signature options i.e. digital Signature, eSign, eSignature and other signature types from trust service providers Digital Signature: Requires Crypto Token and valid digital signature issued by licensed Certifying Authorities to digitally sign the request. eSignature: eSignature is not valid in India, but it is widely accepted in other countries. eSign : eSign (Aadhar based signing) is valid ONLY in India. Specify below signature type values (comma separated) if you need specific signature option to be enabled in our gateway page. SignatureType=2, if you need digital signature as a signature option. SignatureType=3, if you need eSign as a signature option. SignatureType=4, if you need eSignature as signature option. |
SignerID | String | This is an optional parameter. Value for this parameter can be passed if “eSign” Signature type is selected as one of the signature type values e.g xyz.123 |
Storetodb | Boolean | By default this value would be FALSE. Pass it as TRUE if you want to save the response data with us. In case of failure you can request us by calling our API's before 48 hours (If Storetodb=TRUE). |
EnableViewDocumentLink | Boolean | By default thisvalue willbe TRUE. Pass FALSE if document view link is not required. Note: Document link will be displayed only when preview is not enabled. If Preview required is TRUE then set "EnableViewDocumentLink" as FALSE. |
SUrl* | String | Pass success URL, so that after successful signing signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Furl* | String | Pass failure URL, so that when there is a failure, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
Curl* | String | Pass cancel URL, so that when customer cancels the signer gateway process in the middle, signer gateway will send a response to that particular URL. The response handling can then be done by you after redirection to this URL. |
The JSON Payload needs to be encrypted with the Session Key that was generated as part of the first step
Follow the steps used to Encrypt JSON payload to encrypt Hash of Document using the Session Key
This is used as an added security measure to ensure document has not been tampered in transit
Once you have completed Step 1, please send the payload to the URL using the format below
TEST URL – “https://testgateway.emsigner.com/eMsecure/V3_0/Index”
Type – HTTPS POST
Request Parameters
Parameter | Data Type | Description |
---|---|---|
Parameter 1 * | String | Encrypted Session Key |
Parameter 2 * | String | Encrypted JSON Data |
Parameter 3 | String | Encrypted Hash |
Below is a list of response parameters
Parameter | Data Type | Description |
---|---|---|
ReturnStatus | String | Returns Success if request is done successfully otherwise Failure |
ErrorMessage | String | If ReturnStatus is "Failure" it will return an error message. If this is empty then request is a success. Check below error messages. |
Returnvalue | String | Returns Encrypted Signed data, if signing is done successfully otherwise Failure |
Transactionnumber | String | Returns unique transaction number for each request. To identify each new transaction in the ESGS Database, a unique identifier is created every time. This identifier is known as the Transaction number. |
Referencenumber | String | Returns same reference number which has raised the request. |
Error Code | Error Message | Description |
---|---|---|
104 | Invalid Authtoken | When invalid Authtoken is entered |
105 | You are not subscribed to this VAS item. | When No VAS feature is subscribed. |
106 | Cancelled by user | When client cancels the request |
107 | Invalid parameters | When any parameter is empty |
108 | You cannot use reference number which is already used in previous transactions. | When reference number is already used in previous transactions. |
109 | Invalid Request | When decryption of data failed |
110 | emSigner application is required to digitally sign the documents using token based signature. | When emSigner utility is not installed |
111 | emSigner application is required to digitally sign the documents using token based signature. | When utility not running in the system |
112 | emSigner application is required to digitally sign the documents using token based signature. | When port number is mismatch |
113 | Please update the emSigner utility for new updates | If Utility used is not the latest version. |
114 | eSignature is not applicable for XML and Data signing. | When trying to do eSignature for XML and Data files. |
115 | Only .jpg, .jpeg and .png files can be set as Signature Image. | While uploading signature image other than jpg, jpeg and png files Allowed file types are .jpg, .jpeg and .png |
116 | You can upload maximum of 200KB and minimum of 100KB file size. | While uploading big size file Ensure that the size of file should be between (100KB - 200KB) |
117 | Please connect the eSignature pad to sign and capture the signature image | When eSignature Pad is not connected |