Embedded Mode User Interface

Embedded mode uses iframes so that that the payment and identity process can be embedded in your website and maintain the customer user experience.


The embedded mode iframe and supports fixed and variable heights with width always 100% of the container you provided for it and provides a fast, rich and responsive user experience.

Embedding mobile pages is also supported and  is loaded when the container width is less than 650px.

Front end instructions

Create a div where the ISX verify embedded web application will be contained. (Do not use modals)

Include the ISX embed javascript source.

Setup and publish the ISX embedded content. Note that the publish javascript call must be after the ISX container div.

Integration with our UI needs has properties and functions that need to be set:


Properties:

transaction_id: (required) Set from the earlier server side response 

container_id: (required) The div id where the verify web application will be embedded

minimum_height: (optional) Set the minimum height in pixels the frame can be (default is “600”)

maximum_height(optional) Set the maximum height in pixels the frame can be (default is null) Setting this value limits the frame’s ability to expand in size – overflow will be accessible through scrolling

language (string): (optional) Set the language of the web application (default is english). See Supported languages



Functions:

After the iSignthis UI has completed or been closed by the user, it securely notifies the outer frame that the embedded content may be closed via callbacks that you may override to provide a responsive experience to the end user.


fail: Called when there is a general failure to initialise our UI


continueLater: Called when an end user selects “Continue Later” – this is an optional feature that can allow a user to complete a transaction at a later date.


resized: Notifies that the iframe has been resized based on the internal content size – it will resize to the best size within the limits you set via properties.  


completed: Notifies that the process the user is undertaking is complete and you may close the frame and progress the user.  We do notify whether the transaction is successful or not, though you should cross check this with the server to server notification we send before funding a users account.

<html>
<head>
  <link type="text/css" rel="stylesheet" charset="UTF-8" href="index.css">
    <script src="https://verify.flykk.it/js/isx-embed.js?profiles=embedded"></script>
</head>
<body>
<div class=content>
    <div class="isignthis-wrapper">
        <div id="isignthis-container" class="isignthis-container">
        </div>
    </div>
</div>
</body>
<script>
    var options = {
        transaction_id: "<uid-goes-here>",
        container_id: "isignthis-container",
        minimum_height: "700",
        maximum_height: "700",
        language: 'en'
    };
    isignthis.setup(options).done(function (e) {
        console.log("completed. e=", JSON.stringify(e));
        alert("Finished iSignthis process...");
    })
        .fail(function (e) {
            console.log("error. e=" + JSON.stringify(e));
        })
        .continueLater(function (e) {
            console.log("continueLater. e=" + JSON.stringify(e));
        })
        .route(function (e) {
            console.log("route. e=" + JSON.stringify(e));
        })
        .resized(function (e) {
            console.log("resized. e=" + JSON.stringify(e));
        })
        .completed(function (e) {
            console.log("completed. e=" + JSON.stringify(e));
        })
        .publish();
</script>
</html>
 

Payload Example 

 

route. e={ 
   "event":"route",
   "route":"/result/aab3380c-82df-4a55-9b73-ecd5b9b4ca6b",
   "state":"SUCCESS",
   "compound_state":"SUCCESS.COMPLETE",
   "workflow_state":{ 
      "CAPTURE":"ACCEPTED",
      "PAYMENT":"ACCEPTED",
      "PIV":"ACCEPTED",
      "SCA":"ACCEPTED",
      "KYC":"PENDING"
   },
   "created":1582206801735,
   "msg_id":"3e7fe987-7486-4952-a388-021b69a39947"
}

 

Post Request

URL for the POST 

https://gateway.isignthis.com/v1/authorization/

 

Fill in the appropriate header information. The API Header information is provided by the iSignthis Merchant Support team.


In the API body request you need to add the  “workflow name” provided and replace “id” in the “merchant” object with the ones provided by merchant support.

Test_Workflow” text should be replaced with the “workflow name” provided by iSignthis Merchant support team.

 

“workflow”:“Test_Workflow”

Test_Merchant” text should be replaced with the “merchant_id” provided by iSignthis Merchant support team.

“id”:“Test_Merchant”

The API call consists of required fields to proceed with the payment:

– first_name

– last_name

– dob

– gender

– email

– mobile

– billing_address_street

– billing_address_street_number (optional)

– billing_address_city

– billing_address_postal_code

– billing_address_country

 

 Sample JSON body for Paydentity:

{
    
"workflow": "Test_Workflow",
    
    "merchant":  { 
           "id": "Test_Merchant"
        },
    "transaction": {
        "id": "Test_ID",
        "amount": "100",
        "currency": "EUR",
        "reference": "Test_Ref"
    },
    "client": {
        "first_name": "Shana",
        "last_name": "Barrows",
        "email":"shana.barrows@isignthis.com",
        "mobile": "+61434444444",
        "billing_address_street": "Arthur Street",
        "billing_address_secondary": "PO Box 24",
        "billing_address_street_number": "42",
        "billing_address_city": "Ashfield",
        "billing_address_postal_code": "2131"

    },
    "account": {
        "identifier": "Test_ID"
    }
}

Server Side insructions

Create an  iSignthis  transaction using the API according to any of the Flykk, Acquiring or Paydentity API requests were a response similar to the following will be given.

The server response will include redirect_url for use in Redirect mode which is a full page redirect.  If you are using embedded mode then you may ignore this URL.

The uid from the server side response will be needed to passed through to the embedded javascript function on the front end.

{
  "id": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
  "uid": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
  "secret": "159173ee-6309-4806-b499-d2598a2ed21e",
  "context_uid": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
  "mode": "registration",
  "original_message": {
    "merchant_id": "Test_Merchant",
    "transaction_id": "Test_ID",
    "reference": "Test_Ref"
  },
  "transactions": "[]",
  "state": "PENDING",
  "compound_state": "PENDING.VALIDATED_TRANSACTION",
  "redirect_url": "https://verify.isignthis.com/vanilla/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756"
}
 

iSignthis Transaction page

The iSignthis transaction page is opened , the customer will be  prompted to insert additional information, if any is required (depending on the settings that you requested) to proceed with the transaction.

For each unsuccessful try the customer makes, an appropriate event notification will be provided to your web hook.

Please check Notifications and Transaction events section for more information.

Once the user has entered the UI the flow will vary based upon the settings  configured for the merchant. Once the user has completed their flows, a server side notification will be sent to notify you of the completed state of the transaction.

Additionally when using Embedded User Interface – a secure notification will be sent from our iframe to the callback methods shown in the above example that you may optionally define, which will allow you to quickly move the user on to the next stage of your overall process.

Returning to a Transaction

Returning to a transaction is an important factor when conducting a Paydentity workflow. A customer might not have on hand the documents which are required to complete a KYC process and therefore return later to the transaction when all documents have been gathered.

For a customer to be able to return to a transaction and complete the KYC process, the redirect URL from the API Request Response must be stored by the merchant and be accessible by the customer later on.

 

The customer should be able to return to their transaction as long as none of the final events has been send to your webhook.

To implement a cancel transaction button please follow the example in the Actions section