flykk

1 1. Introduction
2 2. Embedded Mode User Interface
3 3. Front End Instructions
4 4. Post Request
5 5. API Request Body
6 6. Server Side Instructions
7 7. ISX Transaction Page
8 8. flykk Notifications

1. Introduction

flykk has 2 integration methods:

Embedded.
Redirect.

The Embedded method is a software integration of our flykk payment system, which is embedded in a merchant’s checkout or payment page on their website. This method is to be used for such cases as pop-ups within the same page. Basically, this option is best suited for a merchant that doesn't want an end user to leave the same page and open a new tab or window.

The Redirect method is to be used for such cases as new web tabs or windows.

This can be directly integrated with a merchant or via a 3^rd party provider. Whichever solution is chosen, this will provide a smooth payment experience for merchant and customer alike.

2. Embedded Mode User Interface

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

The embedded mode uses iframes.

This provides a fast, rich, and responsive user experience.

3. Front End Instructions

Change the script source with the appropriate address

Production: https://verify.flykk.it/js/isx-embed.js?profiles=embedded
Stage / Sandbox: https://stage-verify.isignth.is/js/isx-embed.js?profiles=embedded

Create a <div> where the ISX verify embedded web application will be contained (refer to example).

Do not use modals

Include the ISX embed JavaScript source.

Setup and publish the ISX embedded content.

The publish JavaScript call must be after the ISX container div.

Integration with our UI 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.
language (string): (optional) Set the language of the web application (default is english). Refer to Supported Languages for more information.

Functions

After the ISX 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.

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

4. Post Request

URLs for the POST:

Production API URL: https://gateway.isignthis.com/v1/authorization
Stage API URL: https://stage-gateway.isignth.is/v1/authorization

5. API Request Body

In the API body request, replace the “Workflow” name provided and replace “id” in the “merchant” object with the ones provided by the ISX relationship management team.

“Test_Workflow” text (below) should be replaced with the “workflow” name provided by the ISX relationship management team.

"workflow":"Test_Workflow"

“Test_Merchant” text (below) should be replaced with the “merchant_id” provided by the ISX relationship management team.

The API call consists of the following 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:

6. Server Side Instructions

Create an ISX 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.

(Refer to the example)

The server response will include an 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.

7. ISX Transaction Page

Once the ISX transaction page has opened, the customer maybe prompted to insert additional information (depending on the settings requested), once completed, proceed with the transaction.

For each unsuccessful transaction that a customer makes, an appropriate event notification will be provided to your webhook.

Refer to Notifications and Transaction Events & States 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 the 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, this will allow you to quickly move the user on to the next stage of your overall process.

8. flykk Notifications

8.1. Where to find the notifications

All the required information in the transaction, is sent to the notification URL provided.

A sample of the objects is given below.

To receive notifications on the configured URL, your URL must end with /v1/notification.

8.2. Receive Notification Request

The code provided (below right) is a sample flykk notification (after a transaction).

In the response, you will be able to find all the required information regarding the transaction.

The notification will be attempted in the following intervals, until a response is received: 5 seconds, 1 minute, 1 hour, 6 hours, 12 hours, 1 day, and finally one more day.

Data Types

Field	Type	Description

Field	Type	Description
id	String	Unique response identification code.
secret	String	The transaction secret code.
mode	String	The transaction mode detected by ISX.
recurring_transaction	Boolean	Whether the transaction was a recurring operation or not.
original_message	Object	Information about your transaction request.
workflow_state	Object	State information about the workflow.
event	String	Event name of the notification. Refer to Transaction Events & States for full list.
state	String	State of the transaction. Refer to Transaction Events & States.
compound_state	String	Compound State of the transaction. Refer to Transaction Events & States.
payment_provider_responses	Array	Information about payments or credits made.
payment_amount	Object	Original requested payment amount.
identity	Object	Information about the identity.
response_code	String	Response code of the transaction. Refer to Transaction Events & States.
response_code_description	String	Response code description.

Sample flykk Notification

8.3. Additional notification fields for flykk

Events

Pending Transaction (with JSON Extract)

Common notification which all transactions have (refer to the sample flykk notification above).

Payment Success (with JSON Extract)

Flykk user has proceeded with the PaidBy Bank product top up and we are waiting for the funds to arrive.
Usually, merchants credit the user here but liability and option to do is totally up to the merchant.

Payment Accepted (with JSON Extract)

Funds have been settled and the merchant can credit the flykk user.

Transaction Declined (with JSON Extract)

If the PaidBy Bank top up transaction was declined:

Transaction Cancelled (with JSON Extract)

If the PaidBy Bank top up transaction was canceled:
use case: flykk user changed their mind while going through the PaidBy Bank flow and cancelled the top up.