An iFrame, short for inline frame, is an HTML element used to embed another document within the current HTML document. It provides a way to insert content from another source, such as an external webpage or a video, into the current page without redirecting the user to another page. The content within an iframe behaves as though it's on a separate webpage, contained within a box on the current page.
In the context of Ping Payments KYC API for the endpoint Merchant AIS, an iframe can be utilized to embed the user interface of the KYC process directly onto the Tenant platform. This way, the Merchant can interact with the KYC process without leaving the original site. It's particularly useful for triggering BankID on all possible devices. Especially on iOS Safari devices, BankID tends to be blocked when attempted to be opened from within an iframe. Hence, a mechanism to trigger this from the parent window is essential for a seamless user experience.
Advantages and Considerations for Utilizing iFrame
In the context of integrating the Account Information Services (AIS) on your platform, employing an iFrame offers a convenient and streamlined approach. Below are some key benefits alongside considerations that should guide your decision on whether to use an iFrame for this process.
Benefits of Using an iFrame
Seamless Integration
iFrames allow for a straightforward embedding of the AIS user interface within your platform, ensuring a consistent user experience without necessitating redirection to external pages.
Enhanced User Experience
Users can interact with the AIS process within the familiar environment of your platform, which can enhance trust and user satisfaction.
Simplified Development
By encapsulating the AIS UI within an iFrame, the need for extensive front-end development on your side may be significantly reduced.
Isolation of Content
iFrames provide a level of isolation from the rest of your page, which can be beneficial for security and content management.
Considerations
Utilizing and iframe also comes with some considerations for you as a tenant to reason about:
Mobile Responsiveness
Ensure that the iFrame content is mobile-responsive to cater to users across various devices.
Cross-Origin Restrictions
Be mindful of cross-origin restrictions and ensure proper configurations are in place to allow for seamless interactions between the iFrame and your platform.
Your decision to utilize an iFrame for the AIS integration should be influenced by your platform's specific needs, the technical capabilities at your disposal, and the experience you aim to provide to your users.
How to create an AIS session with an iFrame
An AIS session is started through a simple POST-call to the merchant AIS-endpoint of the Ping Payments KYC API.
Link to API reference:
https://docs.pingpayments.com/reference/mimerwebapimerchantaiscontrollermerchant_ais
Example call:
curl --request POST \
--url https://kyc-sandbox.pingpayments.com/api/merchant_ais \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"country": "SE",
"iframed": true
}
'
In this example no distribution is used, and the tenant platform is expected to do the distribution of the link to the user, meaning the merchant.
Expected Response (Happy Case):
In a happy case scenario, the response will contain a URL (ais_url) which directs to the verification page, and a verification_id which is a unique identifier for this particular verification process.
{
"ais_url":"https://kyc-sandbox.pingpayments.com/ais/verification-page",
"verification_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
JavaScript for client management of BankID on your platform
window.addEventListener("message", (e) => {
if (e.data) {
try {
const data = JSON.parse(e.data);
if (data.href && data.action === "location_href") {
location.href = data.href;
}
} catch (err) {
// Handle error
console.error(err);
}
}
}, false);
This JavaScript code should be added to the Tenant platform. It listens for messages from the iframe containing the KYC UI. When a message with a location_href action is received, it updates the location of the parent window to the specified href.
This mechanism is vital to ensure that BankID can be triggered on all devices, bypassing restrictions especially on iOS Safari devices that block BankID from being opened within an iframe. The redirection from the parent window circumvents this restriction, ensuring a smooth user experience during the verification process.
A diagram to clarify the AIS flow
The following sequence diagram tries to explain this flow in an abstract but clear manner.
Clarification of terminology
- BankId - In Sweden used to verify towards the bank
- Merchant - The entity that wishes to go through the AIS session
- Browser - The browser used by the Merchant
- Iframe - The embedded element in the browser that utilizes Ping Payments KYC ais_url
- Tenant's portal - The site where the Merchant is acting upon, your website
- KYC API - Ping Payments API used for creating an AIS session and orchestrates the AIS-communications towards the banks
- BANK (AIS) - The bank choosen by the merchant to log into using BankID
The diagram
Please note that timeout or errors are not part of this diagram, only happy case!
What if the user is not on an mobile phone?
In such instances, a QR code will be displayed to the merchant user via the iframe, a process managed by Ping Payments, thus requiring no action on your part as a tenant. This implies that the JavaScript event is exclusively triggered for mobile devices. For non-mobile devices, a QR code alongside instructions for scanning and signing within the BankID app will be provided.
What if I do not use an iFrame?
In this scenario, the JavaScript isn't required and can be omitted. Simply open the ais_url in a separate window. However, make sure to define the redirect URLs to ensure that upon successful completion or timeout or error, the user is redirected to the appropriate location.
However, it is important that you set iframed: false when creating the AIS session. Otherwise the javascript event will be triggered!