https://esp.mangoca.com/v2/request-for-certificate?data= base64Encode(jsonEncode())
| Name | Value | Comment |
|---|---|---|
| ba_return_url | {url that will be hit after eKYC registration} | Build up a public method in your application and give us an URL to access that method |
| signerId | {null} | Send signerId as null as user is registering for eKYC. Then save the response for later use. |
The API will return to given URL after registration. Assuming, you have implemented a method to receive the call from
eKYC API, the method should be able to read data from request.
In your request data you will get a parameter named 'data' that contains returned base64 encoded data from API. You have to base64 decode and
then json decode the data to get raw data.
PHP Code Example for calling API:
PHP Code Example to implement returning method for receiving data from API:
$encoded_data=base64_encode(json_encode([
'ba_return_url' => 'http://localhost/my_app/ekyc_return_page.php',
'signerId' => '', //if calling for Registration
]));
header('location: https://esp.mangoca.com/v2/request-for-certificate?data='.$encoded_data);
if ($_GET['data'] && !empty($_GET['data'])) {
$rawdata = json_decode(base64_decode($_GET['data']), true);
//Received signer ID if called for registration. Save this signer id in your user's data and later on you may call only verification API for this user
$signer_id => $rawdata['signerId'],
}
https://esp.mangoca.com/v2/request-for-certificate?data= base64Encode(jsonEncode())
| Name | Value | Comment |
|---|---|---|
| ba_return_url | {url that will be hit after verification} | Build up a public method in your application and give us an URL to access that method |
| signerId | {saved Signer ID from eKYC registration} or {null} | Send signerId as null if user is registering for eKYC | Send saved signerId if user is being verified |
The API will return to given URL after verification. Assuming, you have implemented a method to receive the call from eKYC verification API, the method should call API 3 automatically.
PHP Code Example for calling API:
PHP Code Example to implement returning method for receiving data from API:
$encoded_data=base64_encode(json_encode([
'ba_return_url' => 'http://localhost/my_app/ekyc_return_page.php',
'signerId' => '{saved SignerID from eKYC Registration API}', //if calling for verification
]));
header('location: https://esp.mangoca.com/v2/request-for-certificate?data='.$encoded_data);
if ($_GET['data'] && !empty($_GET['data'])) {
$rawdata = json_decode(base64_decode($_GET['data']), true);
//Received data if called for verification. With this data, now you can call file hashing and signing apis.
$signer_id => $rawdata['signerId'],
$app_token => $rawdata['app_token'],
//hashing and signing api codes...
}
Before sending the file to E-Sign, the file needs to be hashed. Hence, we offer file hasher in File Hashing E-Signer Utilities.
You can download the File Hashing E-Signer Utility source code from this link and host this source code in your preferred hosting environtment. Or, you can directly call to file hasher
API.
Download File Hashing E-Signer Utility Source Code
Now you can move on to the next steps starting with setting up the file hashing API.
If you have downloaded source code: {url_of_esigner_utility}/sign-embed/upload-doc
or
If you want to call our API: https://doc-mango.e-signer.xyz/sign-embed/upload-doc
| Param | Value | Type | Comment |
|---|---|---|---|
| APIKEY | 997dc568-5d89-4147-a48f-186185b66bc7 | text | Unique key for communication between two distinguished systems, which is constant. |
| pdf_doc | {file_object_as_url} | text | An Object created from file location. |
| APISECKEY | 887dc568-5d89-4147-a48f-186185b66bc7-997dc568-5d89-4147-a48f-186185b66bc9 | text | This key is a secret key for ensuring secure API access which should be changed in a regular interval. |
| doc_name | {file_name} | text | The actual file name which is supposed to be hashed. |
"status": "success",
"data" : {
"name_hash": --random_hashed_string--,
"doc_uuid": --random_universal_unique_identifier_string--,
"uuid_hash": --hash_of_the_uuid--,
"downloadUrl": --url_for_downloading_document--
}
As the document is now hashed it is ready for electronic sign requesting.
To Sign the target document's hash, the hash needs to be ready to make sign on it. Call this GET API to get the file hash ready.
'https://doc-mango.e-signer.xyz/sign-embed/file-hash/{uuid_hash}>/{signer_id};
| Param | Value | Type |
|---|---|---|
| uuid_hash | {uuid_hash from previous response} | text |
| signer_id | {received Signer id after verification} | varchar(14) |
In the response of this API, you will find the file's hash in response body. You will have to json_decode the response and you will get the following data:
$response= json_decode($response, true);
$file_hash= $response['body'];
To Sign the target document, business application have to get ready with some data as parameter. This GET Endpoint of Sign request accepts base64 and json encoded version of the prepared data as query parameter.
https://esp.mangoca.com/v2/request-for-sign?data={json(base64(param_data))}
| Param | Value | Type |
|---|---|---|
| BACallbackURL | {return_url_of_business_application} | text |
| SignerId | {received Signer id after verification} | varchar(14) |
| app_token | {received app_token after verification} | text |
| version | 2 | text |
| AuthMode | 1 | text |
| ekycIdType | 2 | text |
| BA_Id | {given_ba_id} | text |
| sc | true | text |
| TimeStamp | {current_timestamp} | text |
| RequestUniqueId | {$file_hash from previous response} | text |
| SignatureType | {null} | text |
| HashAlgorithm | SHA256 | text |
| HashToSign | {doc_uuid} (From Previous Response) | text |
| Description | {Any Text} (can be null) | text |
| DocumentLink | {available_link} (can be null) | text |
| BAVerificationResponseURL | {null} | text |
| BAeSignResponseURL | {return_url_of_business_app} | text |
| 'Language' | {Any Text} (can be null) | text |
As business application is giving the return_url_of_business_app in the parameter data,
E-Sign Platform will sign the document and it will send the signed file hash data
as parameter with the return_url_of_business_app.
So, a method is essential in business app to response to this call. The return URL calling structure from E-Sign Platform will be:
{return_url_of_business_app}?data={random_encoded_string}
This {random_encoded_string} is actually base64 and json encoded.
So, Business application should have a method to base64 and json decode this
parameter data and achieve the signed hash value of the target document.
Code Example:
Here comes the need of Signed File Hash Embedder which is a part of the E-Signer File Hashing Utilities that is
involved in incorporating the hash value of a document directly into the document itself.
JSON.parse(atob(urlParam.get('data')));
Assuming the API of this tool has been already set up as you have downloaded and hosted the source code of File Hashing E-Signer Utilities. Now the signed file hash needs to return to its original form. To achieve the form-data of Signed File Hash Embedder Utility’s API you need to form a unique data set.
If you have downloaded and hosted File Hash Embedder: {url_of_esigner_utility}/sign-embed/apply-signed-hash
or
If you had not downloaded the source code and you decided to simply call our hash embedder API:
https://doc-mango.e-signer.xyz/sign-embed/apply-signed-hash
| Param | Value | Type | Comment |
|---|---|---|---|
| signerId | {received signer id from verification} | text | User's Mobile Number from eKYC (Mandatory Parameter) |
| docUuid | {doc_uuid_value from response of API 3} | text | The unique universal identifier value of document that was achieved in API 3: File Hasher |
| signedHash | {signed_hash_value} | text | The Signed File hash value that was acheived from the response of calling the e-signer API. |
Calling This API will return a JSON response having only one variable: 'status'. If the status is 'success' then you will find the document as signed document by calling the received download_url from API 3.
