Redirect settings and webmessages

Last updated 4 months ago

It's up to you how you want to use our application. On each signer you need to specify how you want him or her to be redirected.

Request example

{
...
"signers": [{
...
"redirectSettings": {
"redirectMode": "donot_redirect"
}
...
]
...
},

A simple explanation of the different redirect modes

Value

Explained

Depends on

donot_redirect

The user will not leave our page during the signature process.

Nothing

redirect

The user will be redirected to the specified urls on error/abort/success.

error, cancel, success

iframe_with_webmessaging

You iframe our application and can use webmessaging to do what you want on success/error/abort. No redirect is executed.

domain

iframe_with_redirect

You iframe the application, with no use of webmessaging. The signer will be redirected to the specified urls

error, cancel, success

iframe_with_redirect_and_webmessaging

You get both redirect and webmessaging

error, cancel, success, domain

Redirect guide

Step 1 - Create request

Be sure to include error, cancel and success urls in the redirectSettings object. The format should be a valid url with no special characters. If you have special characters be sure to url encode them.

{
...
"signers": [{
...
"redirectSettings": {
"redirectMode": "redirect",
"success": "https://example.com/sign/success",
"cancel": "https://example.com/sign/cancel",
"error": "https://example.com/sign/error"
}
...
]
...
},

Step 2 - Sign or cancel (hopefully no error)

Let the signer do what they want to do

Step 3 - Retrieve the redirect response

To make it easy for you the read some core data about the signature status we append a jwt token to the urls you defined. It will look like this:

https://example.com/sign/success?idfy-jwt=<jwt is inserted as a query parameter called idfy-jwt>

If you use this token you should parse and validate it as described in step 5.

Step 5 - Parse and validate the jwt (optional)

You can parse and validate the jwt here: https://developer.idfy.io/api#tag/Jwt

The response will look something like this, check the JwtValid and Expired properties to make sure the jwt is generated by us.

{
"JwtValid": true,
"Expired": false,
"JwtPayload": {
"AccountId": "efed4e57-cfb2-460b-bb8d-a6e200ac3688",
"DocumentId": "3cd7efd1-32ab-4b63-a097-a88600aac288",
"ExternalId": "768bbab7-c422-46d9-9714-af58e0519dc8",
"SignerId": "bfd58193-2924-401c-a795-a88600aac2a4",
"ExternalSignerId": "759eabea-adc9-48d4-a4cb-1b5b92d823a0",
"SignSuccess": {
"SignatureMethodUniqueId": "9578-6000-4-198651",
"FullName": "Gates, Bill",
"DateOfBirth": "1913-03-31",
"SignatureMethod": "no_bankid",
"SignedTime": "2018-02-13T10:25:08Z"
},
"Expires": "2018-02-13T10:34:48.1859661Z"
}
}

Iframe guide

Step 1 - Create request

Include the domain of the site that is hosting the signature app in an iframe. The domain is needed for our csp policy and for webmessaging.

{
...
"signers": [{
...
"redirectSettings": {
"redirectMode": "redirect",
"domain": "example.com",
}
...
]
...
},

Hint: If you are using nested iframes you have to include all domains, separate them with space. The receiver of webmessages has to be the last domain in your list.

Step 2 - Sign or cancel (hopefully no error)

Let the signer do what they want to do

Step 3 - Read the webmessages if you want to

The webmessage object we send have this structure. Some of the messages includes a payload.

{
"type": "spinner_on",
"payload" : undefined
}

A very simple approach to read them:

<script>
window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
if (event.origin === 'https://sign.idfy.io' || event.origin === 'https://sign-test.idfy.io') {
var data = JSON.parse(event.data);
var type = data.type;
var payload = data.payload;
// Type and payload is now available
}
}
</script>

Webmessage-types

type

Payload included

outdated_browser*

app_started**

{ "documentId": "The doc id" }

document_expired

{ "documentId": "The doc id" }

eid_selected

Selected eid (signature method)

document_read

{ "documentId": "The doc id" } //Only when using internal doc viewer in app

language_changed

Selected language

spinner_on

none

spinner_off

none

user_canceled

{ "documentId": "The doc id" }

sign_success

{ "documentId": "The doc id" }

sign_error

{"errorCode": "Error code if it exists", "errorMessage": "Error message if it exists", "eidErrorCode": "Selected signature method native error code if exists", "eidErrorMessage": "Selected signature method native error code if exists", "documentId": "The doc id" }

*outdated_browser webmessage means that the user is using an old browser that may not work with the signature application. The browser needs to support postMessage to be able to send this webmessage.

** The app may not start if the browser is to old, you can check for the outdated_browser event to catch this error