Signer held EU qualified signature with Docusign API in PHP

Motivation

Docusign is a great method for signing documents remotely but in its most basic implementations the signers can’t use his own signature to digitally sign the document. In order to get higher identity trust standards they provide additional signing methods not included in the basic accounts.

You can explore which are these methods in this blog post and you’ll find a developer-targeted explanation in their developer’s blog too.

Docusign provides API libraries on multiple languages. The nice thing is they provide basic code examples too in the form of what they call Code example launchers. These are complete GitHub projects in different programming languages where developer can test the functionalities and also grab code ideas.

In this post I will show some PHP code examples on how to set the Signer held EU qualified eSignature type to a signer, directly from their PHP code example launcher.

Getting the code

You can easily get their PHP launcher with following command:

git clone https://github.com/docusign/code-examples-php

This is a demo web app that can work on top of your local LAMP stack. Whether it is a virtual host, XAMPP or WAMP is up to you.

For the examples to work, you will need to set some API keys and certificates in your Docusign developer account and configure them in the app’s settings file. This process is thoroughly explained in their docs. Just keep in mind the API we are working on is the eSignature API.

Testing the App

Once you have the app running you should test example 2. Send an envelope with a remote (email) signer and cc recipient.

If your intention is to always send the envelopes from the same account you will probably need to set up the JWT authentication method, so the part of the settings file you have been playing with is probably this one:

ds_config.php:

$JWT_CONFIG = [
    'ds_client_id' => '{INTEGRATION_KEY_JWT}', // The app's DocuSign integration key
    'authorization_server' => 'account-d.docusign.com',
    "ds_impersonated_user_id" => '{IMPERSONATED_USER_ID}',  // the id of the user
    "private_key_file" => "./private.key", // path to private key file
];

Setting signature type

The original code to set the signer is this:

Example\Controllers\Examples\eSignatureEG002SigningViaEmail::make_envelope():

# Create the signer recipient model
$signer1 = new Signer([
    'email' => $args['signer_email'],
    'name' => $args['signer_name'],
    'recipient_id' => "1",
    'routing_order' => "1",
]);

You can keep this code unmodified but some extra configuration needs to be addes to the signer instance. We want to add a new signature provider and this can be done with following code:

$signature_provider = new \DocuSign\eSign\Model\RecipientSignatureProvider(
    ['signature_provider_name' => 'universalsignaturepen_signer_held_eu_qualified',]
);
$signer1->setRecipientSignatureProviders([$signature_provider]);

And that’s it !!

After adding this lines of code and executing the example you should go to the DocuSign Developer site and check how your new envelope looks like. The generated signer will have the expected signature type:

The problem in some cases might be that your client needs this recipient to be assigned personally to a specific Docusign user account. Setting the correct email address and name in the signer is not enough.

The only method I have found to discover which is the given user is manually changing the target user via Docusign UI and then inspecting the recipient via example 3. List envelopes whose status has changed and example 5. List an envelope’s recipients and their status. This way we can obtain a user_id which we can add to our sender, making it finally appear like this:

# Create the signer recipient model
$signer1 = new Signer([
    'email' => $args['signer_email'],
    'name' => $args['signer_name'],
    'recipient_id' => "1",
    'routing_order' => "1",
]);

# Add the Signer held EU qualified signature provider
$signer1->setUserId([the user id]);

# Add the Signer held EU qualified signature provider
$signature_provider = new \DocuSign\eSign\Model\RecipientSignatureProvider(
    ['signature_provider_name' => 'universalsignaturepen_signer_held_eu_qualified',]
);
$signer1->setRecipientSignatureProviders([$signature_provider]);

Obviously this will only work when this user is fixed, let’s say The Boss.

Final thoughts

This simple method can be useful if you build your client for the Docusign eSignature API based in their PHP Launcher demo app and their docusign/esign-client library. I really recommend this path when your requirements are quite standard and your process matches any of the examples provided by the Code example launchers.

The other option you have is working directly with the API and not using the helper classes Docusign provides. In this case the recipients providers can be set as explained in their raw API docs, but in general their client code is great to use and much of the API calls are already provided in an OO library.