Embedded Mode

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>
    <title> iSignthis Vanilla Widget </title>
    <style>
        /* 
            Proportionally resizing (aka. responsive iframes)
        */
        .isignthis-container {
            overflow: hidden;
            padding-top: 56.25%;
            position: relative;
        }
        .isignthis-container iframe {
            border: 0;
            height: 100%;
            left: 0;
            position: absolute;
            top: 0;
            width: 100%;
        }
        /* 
            Don’t forget to apply an aspect ratio class to your iframe. 
            If you don’t, it could cause the iframe to disappear. 
            Intrinsic ratios for responsive iframes.
            4x3 Aspect Ratio 
        */
        .isignthis-container-4x3 {
            padding-top: 75%;
        }
        /* 
            Here you can configure the width, height etc 
        */
        .isignthis-wrapper {
            margin: 0 auto;
            max-width: 1020px;
            width: 50%;
        }
    </style>
</head>
<body>
    <div class="isignthis-wrapper">
        <div class="isignthis-container">
            <!-- 
                Do not add the width and height attributes. 
                Keeping those attributes forces the content to stay at that size regardless of the screen size.
                This causes problems in responsive layouts when the screen size is smaller than the width of the iframe. 
   
            <iframe src="REDIRECT_URL_FROM_GATEWAY_RESPONSE" allowfullscreen></iframe>
        </div>
    </div>
</body>
</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.