Introduction

Flykk® combines payment, banking and eMoney services, which also leverage our Paydentity™ KYC service.

As such the integration for the Flykk service is very similar to the Paydentity product as we perform the same identity verification and payment instrument validation (PIV) before provisioning the Flykk user with an IBAN based account in which to store their eMoney.

KYC data is collected to instantiate KYC however in the case where insufficient quality or quantity of KYC data is parsed, Paydentity™ will request to collect the KYC data in different methods listed below.

– Card Scheme Address Verification Data (US, UK, CA)

– Electronic Verification Sources (UK, US, Australia, Germany, Canada and others)

– BankID (Nordics)

– Government Document Verification Sources (Australia, China)

– Proof of Address Document upload

– Proof of Living Document upload

– Payment Instrument Verification (PIV)

– Other Electronic Sources

 

 

For a smoother user experience, it is encouraged that KYC data known should be passed into the API body request by the merchant in the initial call which Paydentity™ will conduct its verification process.

Our patented Payment Instrument Verification (PIV) could be required in certain cases where further assurance on identity is needed or if the card is will be used for payouts.

Once the customer’s identity has been verified, iSignthis in accordance with European Union and Australian Anti-money laundering requirements, Paydentity™ will screen for Politically Exposed Person (PEP), Sanctions (UK, US, CA, AU, EU, UN), Law Enforcement, Criminal Court Judgments and Adverse Media.

The steps involved during the process are: 

1. Create API Request

2. Receive API Request Response

3. iSignthis Transaction page

4. Receive notifications

5. Result page

 

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Mandatory Fields

The user experience is significantly streamlined when we are provided with details of the user.
 
If attributes such as name, mobile, address and so forth are not passed to us, then our service will need to collect those from the user directly.
 
At all times, we seek to avoid double handling of the customers, especially if the customer has just entered those details into a registration process with the merchant.
 
 
 
Please make sure to pass the correct data each time.

 

"client" :{
    "first_name": "Shana",
    "last_name": "Barrows",
    "billing_address_street" :"AU",
    "billing_address_street_number" : "42",
    "billing_address_secondary": "PO Box 24",
    "billing_address_city": "Ashfield",
    "billing_address_postal_code": "2131",
    "billing_address_subdivision": "NSW",
    "billing_address_country": "AU",
    "email":"shana.barrows@isignthis.com",
    "mobile": "+61434444444"
}

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

Flykk Embedded


1. Create API Request

The request API consists the below four steps: Method, URL, Header and Body

Request Method: POST.

The API is accessed from the Request URL. This is a combination of our URL and the addition of the following text at the end of the URL: “/v1/authorization/”

URL For Production Environment:

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

 

Required Headers

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

Field Name Field Value
From Api client name
Authorization Bearer API token
Content_type application/json
Example:
Field Name Field Value
From Test_APIClient
Authorization Bearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE
Content_type application/json

In order to generate the “Transaction API call” the following API Objects are required. Each object has a number of specific attributes in order to be successful.

Below you can view each object name, description and whether is required or not. Also, the glossary column has a link that directs you to detailed information about each object, including examples.

Object name Description Required Glossary
merchant Information of the merchant Yes Merchant object
transaction Information of the transaction Yes Transaction object
client Information of the client Yes Client Object
account Information of the account Yes Account object

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

– residential_address_street

– residential_address_street_number 

– residential_address_city

– residential_address_postal_code

– residential_address_subdivision (US,AU,CA)

– residential_address_country

– citizen_country

 

 

 Sample JSON body for Paydentity:

{
    
"workflow": "Test_Workflow",
    
    "merchant":  { 
           "id": "Test_Merchant"
        },
    "transaction": {
        "id": "Test_ID",
        "amount": "100",
        "currency": "AUD",
        "reference": "Test_Ref"
    },
    "client": {
        "first_name": "Shana",
        "last_name": "Barrows",
        "email":"shana.barrows@isignthis.com",
        "mobile": "+61434444444",
        "residential_address_street": "Arthur Street",
        "residential_address_secondary": "PO Box 24",
        "residential_address_street_number": "42",
        "residential_address_city": "Ashfield",
        "residential_address_postal_code": "2131",
        "residential_address_subdivision": "NSW",
        "residential_address_country": "AU",
        "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",
        "billing_address_subdivision": "NSW",
        "billing_address_country": "AU"

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

 

NOTE: In the “account” object –  identifier is the customer ID that you assigned to your customer. Each “identifier” must be unique and paired with the customer for future transactions.

2. 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. Provided  by copying  the code on the right

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

Make sure to replace “<uid-goes-here>”, with the transaction ID you received from the POST response, the UID is the trailing end of the redirect_url

Example : https://verify.isignthis.com/vanilla/landing/e6988b4a-ed1c-4104-9caf-af6bb876976

The UID is  e6988b4a-ed1c-4104-9caf-af6bb876976

 

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

We recommend a minimum height  of at least 600 pixels  to provide a smooth experience across devices and screen sizes. 

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.

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.

<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"
}

 

Changing language in embedded mode

In the case that you wish to change language, you will need to change the code as the one set on the right : 

 

The available languages are :

 

Code Language
en English
fr French
de German
da Danish
jp Japanese
es Spanish
no Norwegian
se Swedish

<!DOCTYPE HTML>
<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 trxnID = '<?php echo $_POST["transactionID"]; ?>'
    
// You will need to change the bellow variable to the language you want to display. Example  var lang = "/ja" to display japanese
    var lang = "/en" 
    var options = {
        transaction_id: trxnID+lang,
        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>
<input type=button onClick="location.href='http://ist-qa01.northeurope.cloudapp.azure.com/Iframe_html/IframeTester-Index.html'" value="RESET" id="reset" name="reset_me">
</html>
 

3. API Request Response

Server Side insructions

Once the POST is sent, a message will be received as a response. 

Field Type Description
id/uid “String” Unique response identification code.  
secret “String” The transaction secret code that can be used to validate ISX notifications.  
mode “String” The transaction mode detected by iSignthis.  
original_message Object Information about your transaction request.  
state “String” Information about the state of the transaction  
compound_state “String” The ISX meaningful state of the transaction  
redirect_url “String” The redirect URL  

 

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.

If successful it will have the following format:

Sample JSON Payment Response:

{
    
"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"

}

Opening the redirect_url will display the transaction page

NOTEIf the API request response is unsuccessful an error will be shown.

4. iSignthis Notifications

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

For each step of the transaction, an appropriate event notification will be provided to your web hook.

Please check Notifications and Transaction events section for more information.

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.

5. Returning to a Transaction

Returning to a transaction is an important factor. 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