OneSpan Implementation with PHP

Hi Rosy,

If you are developing with PHP, unfortunately there's no out-of-the-box SDK to integrate with your flow, so you'd use REST API code instead. But no worries, we have a lot of useful example codes in the Code Share guiding you how to build the JSON and invoke these APIs.

If you just get started integration with OneSpan Sign using PHP, go check this Create and Send package code share, it gives you the code base how to send out API.

In your description, you said "upload document without adding custom fields", do you mean that the document is an accept-only document without any particular fields(guide here)?

Once signed, in order to download the signed document, you'd use the API mentioned in this Quick Start Guide.

Duo

Hello Sir,

Thank you so much for the prompt reply. As per my requirement, there will be certain types of users (i.e. companies) who will upload their contract documents (pdf document different format and different text) in our PHP website. This PDF will be a kind of readonly PDF and will be sent to the respective customers. The customer will then sign that PDF document (any where in PDF mostly there will be a blank link in pdf to indicate the customer to sign here) . Once they sign the document, it should save the document on our server. Some of the examples I followed, iFrame was used and I don't know why because I was not able to see the demo in regards to how exactly it works.

It would be a great help to me.

Thank you,

Hi Rosy,

(1) These users can be added as senders under your account, simply add them from the UI portal should be fine. Sender/Signer are uniquely identified by email in OneSpan Sign system, so you'd use an email to represent each of the users.

(2) When sending transactions, you can use the feature "send on behalf of your sender", meaning you are using your account owner's API Key, but the ownership of this package belongs to the sender. One of the pros of doing this is, you can pull packages per sender when you want to manage all the packages.

There's a "sender" node in package JSON, just required "email", as "sender":{"email":"your_sender_email"}

(3) In your specific case, I won't think you need to embed the Signing Ceremony to an iFrame, just using the default delivery way that OneSpan Sign will send an email to your signer and they can click the "Go to Document" link from there and remotely signing should be enough. 

Using iFrame is for the scenario when you want to embed the signing process to your application and (most likely) to deliver the link yourself.

Duo

Hello,

Thanks very much for the help. The link you provided ( Create and Send package code share) to create and send package is returning error "Cannot send package without approvals"

I understand that creating package will upload the pdf document and sending package will send an email to customer to sign the document, correct? Every new or existing user who upload a new contract document will create a new package everytime. Please confirm.

I can set the callback URL in event notification so when customer signs the PDF document, they can return to the PHP website. There may be a case when the new PDF document is sent to the same customer so that should not be a problem.

Also the portal will be only used as mediator to organize the flow and everything should be managed through API. So we would be using only API to do the work. Both types of users will see the signed documents from our website only.

Also can you let me know what should be the package status when we send it to signer?

Would you let me know what REST API to use to send customer an email to sign PDF document? Is it create and send a package?

Again thank you very much for spending sufficient time and providing me solution and having a patience with me.

Thanks

 

"creating package will upload the pdf document and sending package will send an email to customer to sign the document"

"Every new or existing user who upload a new contract document will create a new package everytime"

Both correct.

"when customer signs the PDF document, they can return to the PHP website"

I guess you should use the Handover URL, instead of callback listener. Callback Listener sends notification to your PHP website, but won't give you the capability to redirect sender.

I have a blog talks about Handover URL, here.
 

"what should be the package status when we send it to signer"

should be "SENT", check all the possible package status in this guide.

"what REST API to use to send customer an email to sign PDF document"

You can directly set the "status":"SENT" in package JSON, so OSS will directly sent the email. Or you can create a "DRAFT" status package, then use PUT /api/packages/{packageID} with payload {"status":"SENT"} to send the package in two steps.

Duo

BTW, approval means signatures in OSS terminology.

The reason why you are seeing that error when use the sample code is because in the code, we used a feature called "Document Extraction" that will use the PDF forms existing in the PDF to automatic the signature/field design.

For you, you'd adjust the package JSON code like below: giving an "approvals" node without "fields", just bind to the role ID.

    $json = array(
            'type' => 'PACKAGE',
            'status' => 'SENT',
            'roles' => array(
                array(
                    'id' => 'Signer1',
                    'type' => 'SIGNER',
                    'signers' => array(
                        array(
                            'email' => '[email protected]',
                            'firstName' => 'John',
                            'lastName' => 'Smith',
                            'id' => 'Signer1',
                        )
                    ) ,
                ) ,
                array(
                    'id' => 'Sender1',
                    'type' => 'SIGNER',
                    'signers' => array(
                        array(
                            'email' => '[email protected]',
                            'firstName' => 'Mike',
                            'lastName' => 'Boss',
                            'id' => 'Sender1',
                        )
                    ) ,
                ) ,
            ) ,
            'name' => 'PHP Application Example',
            'documents' => array(
                        array(
                            'name' => 'Sample Contract',
                            'id' => 'contract',
                            'approvals' => array(
                                    array(
                                        'role' => 'Signer1'
                                    )
                            )
                        )
                    )
        );
 

Duo

Hi,

Yeah error disappeared and it returned id which I understood is the package id or is it document id? Although it did not send me an email to sign the document :)

Any idea? Also when I set the handover url, will it send me the document id in URL, so I can identify and proceed further actions?

Thanks for your rime. Much appreciated.

Hi Rosy,

ID returned reference to the package ID. (since there can be multiple documents in a package)

For not receiving email:

(1)make sure you are not checking your sender's email inbox, the email.activate template will only send to signers.

(2)there's a database out of sync issue this morning, and should have been fixed now. Try to send the package once again to see if the signer can receive an invitation email.

    $json = array(
            'type' => 'PACKAGE',
            'status' => 'SENT',
            'roles' => array(
                array(
                    'id' => 'Signer1',
                    'type' => 'SIGNER',
                    'signers' => array(
                        array(
                            'email' => '[email protected]',
                            'firstName' => 'John',
                            'lastName' => 'Smith',
                            'id' => 'Signer1',
                        )
                    ) ,
                ) 
            ) ,
            'name' => 'PHP Application Example',
            'documents' => array(
                        array(
                            'name' => 'Sample Contract',
                            'id' => 'contract',
                            'approvals' => array(
                                    array(
                                        'role' => 'Signer1'
                                    )
                            )
                        )
                    )
        );

"handover url, will it send me the document id in URL"

Yes, there are two three parameters in the URL: package, signer, status. It's explained in another blog, here.

I am glad if these information could be helpful, just feel free to post if you have any further questions towards integration.

Duo

Hi,

Thanks for the update. After logged into my sandbox account, all I have done is using API key only.

"make sure you are not checking your sender's email inbox, the email.activate template will only send to signers."

- Do I need to create template from my sandbox account in order to send email to customers? That would be the dynamic process, So do I need to use any other API? Let me know if I misunderstood anything? I know I am bugging you but thanks for the patience.

In your use case, cuz your users have different documents, I won't think you need to use the templates.

For API Key, there are two options as I mentioned above:
(1) If the users are senders under your account and you are using the feature "send on behalf of", you just need your own API Key for the temporary.

(2) Actually all senders have their own API Key, but this adds difficulty for you to send the package because you'd check the API Key first then build the HTTP connection differently. But retrieving sender's API Key is necessary when you want to pull the package list, but it won't be a concern at this point, I think.

For what I meant, take below code for example:

    $json = array(
            'type' => 'PACKAGE',
            'status' => 'SENT',
            'roles' => array(
                array(
                    'id' => 'Signer1',
                    'type' => 'SIGNER',
                    'signers' => array(
                        array(
                            'email' => '[email protected]',
                            'firstName' => 'John',
                            'lastName' => 'Smith',
                            'id' => 'Signer1',
                        )
                    ) ,
                ) 
            ) ,
            'name' => 'PHP Application Example',
            'documents' => array(
                        array(
                            'name' => 'Sample Contract',
                            'id' => 'contract',
                            'approvals' => array(
                                    array(
                                        'role' => 'Signer1'
                                    )
                            )
                        )
                    )
        );

OSS will only send email to this "[email protected]"

Duo

Hi,

Yes, I used the same json array yet it did returned package id but no email has been received to sign the document. Also one last query is that do I have to use the same id for documents and signers or it needs to be different while creating new package everytime when a new pdf docu is uploaded?

Thanks

"no email has been received to sign the document."

Can you share a package ID so that I can help you check your account settings.

"do I have to use the same id for documents and signers or it needs to be different while creating new package everytime when a new pdf docu is uploaded"

As long as it's a separate package, you can use the same document and role IDs.

Duo

Hi,

Package ID - iCw537cuj2hDaYmHA9SE9Us9icY=

Thanks

Hi Rosy,

I see that you were trying to add yourself as a signer, as I stated above: sender (even if is a signer), won't receive an email notification.

So could you try to use another email as signer?

Duo

Hi,

Yes, I thought the same and then tried with a different email but still did not received it. I changed the mail address and here is another package id - vRw-9ktafBQ3pcQIl8skDECb-U0=

In my sandbox account panel, it shows me that the transactions are in progress.

Thanks

Backoffice shows the email has been sent out, try to check the spam folder or use a more general email domain like gmail please.

Duo

Hi,

Finally I got email but the doc has only "Accept" and "Opt out" button. I was in an assumption that customer will draw the signature (like docusign or something like that)

Is this the complete flow that when customer clicks "accept" button, it determines that the document has been signed by customer?

Thanks for your time.

The handdrawn signature is with subtype of "CAPTURE", check the JSON example in this guide, where used hardcoded x/y coordinates to locate the signature.

Duo

Hi,

Ok, the property is in fields key and it would require to be manually added in json array. Also it has positions specified in it which we can't use because PDF format is not unique and all will have their own contract document in their standard format. so we cannot identify the exact placement in PDF. So I think it will not satisfy the requirement.

Let me know if I misunderstood anything.

Thanks

In which case, after the package has been created and in DRAFT status, you can embed the designer view to your own application and allow them to use the UI, drag and drop to design the package themselves.

You can check this blog series:

https://www.onespan.com/blog/onespan-sign-developer-designer-customization-and-integration-part-1

https://www.onespan.com/blog/onespan-sign-developer-designer-customization-and-integration-part-2

https://www.onespan.com/blog/onespan-sign-developer-designer-customization-and-integration-part-3

https://www.onespan.com/blog/onespan-sign-developer-designer-customization-and-integration-part-4

https://www.onespan.com/blog/onespan-sign-developer-designer-customization-and-integration-part-5

And the sample codes are exactly written in PHP.

Duo

Hi,

Thanks for the links. This solution led to the iFrame embedding in website which we had discussed earlier on the start of this conversation.

Just to confirm here that each individual customer will be able to embed the respective PDF document in website based on package id received. Also please confirm that email will not be sent to signer if the package is created and  in Draft status.

Also just for my knowledge, I understood that different authorization or authentication token for each customer is not required and package id should be enough to proceed with designer flow.

Thanks for your time. I will get back to you if I found any issue.

Thank you.

"email will not be sent to signer if the package is created and  in Draft status"

email won't be sent until the package is in "SENT" status

"each individual customer will be able to embed the respective PDF document in website based on package id received"

"different authorization or authentication token for each customer is not required and package id should be enough to proceed with designer flow."

Only package Id is not enough, you need to create a sender authentication token of the package owner (depending on whom you set in the "sender" field in package JSON, or API Key holder if you didn't set) -- Sender Authentication Token and the link built out of it as documented in this guide. When you built this link, you can send it to anyone to proceed with the designer flow.

Duo

Hi,

Yes understood. I referred  this integration part1

According to above link, we would create the sender authentication token through package id. what I am trying to convey here is that user who will embed the signature placement will be the end user who will sign the document. The user who had created the package will be the one who will upload a PDF document contract and the end user will be the one who will embed the signature by creating a sender authentication token through package id that will be stored in our database. So I assume that there will no authentication related issue.

Thank you.