iFrame

For the Web usage, the use of iFrame is recommended, for the following reasons:

• Greater security;
• Experience integrated into your website;
• Higher conversion rate when using iFrame;
• Easier implementation;

To start using iFrame, we must begin by installing the SDK that IDPay provides:

$ npm install idpay-b2b-sdk

Available methods:

init(options)

This method allows the SDK to be initialized independently of a transaction ID, making the end user experience more fluid. Once the transaction ID and token are available, the application has already been preloaded using this method. If this method is not called directly by the application, the end user will have a long load time when they first open the SDK.

Parameters:

options

Receives an object with configuration properties:

type

The flow that will be initialized. Today, we offer two types of flows (REDIRECT and IFRAME). For new applications, we recommend using the IFRAME type, making the experience for the end user much more fluid and with less friction, since it won't be necessary to leave the checkout screen, and the experience can be loaded beforehand.

import { IDPaySDK } from “idpay-b2b-sdk”;

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // It will only be filled in if it is a test environment.
});

open({ transactionId, token, onFinish? })

This method opens the IDPay experiment according to the flow previously chosen in the initialization function. For the REDIRECT type flow, this function simply redirects to the IDPay capture flow route. For the IFRAME type flow, this function displays the pre-loaded iframe and starts the flow between the customer's page and the IDPay experience.

Parameters:

options

Receives an object with configuration properties:

transactionId

It receives the ID of the transaction created. This ID is important so that we can obtain the details of the transaction and carry out the entire flow correctly (it can be obtained when creating the transaction via the API).

token

Receives the token of the transaction created. This token is important so that we can authenticate the transaction and ensure that only authorized domains use it (it can be obtained when creating the transaction via API).

opcional onFinish(transaction, type)

Receives a callback function that will be executed at the end of the IDPay capture flow, passing two arguments:

• The transaction object with the following data: { captureConcluded, concluded, id }
• The type of response that can be FINISH, for cases where the flow was successfully completed, or ERROR, for cases where the flow was interrupted by an error¹

[1] In cases of error in the flow, the transaction will not have its status changed and a callback via webhook, if configured, will not be performed.

const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

Security

Choice of Iframe Solution with Auth Token Instead of CSP

After a careful analysis of the needs and challenges we face, we decided to adopt a solution based on iframes with authentication tokens rather than implementing a Content Security Policy (CSP). This choice was driven by various security considerations and the flexibility needed to meet our clients' demands.

Context and Challenges with CSP

Content Security Policy (CSP) is a powerful tool for protecting web applications against various types of attacks, such as Cross-Site Scripting (XSS) and code injection. However, when configuring a CSP policy, it is necessary to define a strict list of trusted domains. This approach is effective when the domains are fixed and predictable. However, for our clients, who frequently use dynamic and variable domains, this rigid configuration presents significant challenges.

Vulnerability with Dynamic Domains

Dynamic domains represent a substantial security risk when using CSP. When a client has domains that change frequently or are created dynamically, it would be necessary to constantly update the CSP policy to include these new domains. This not only increases maintenance effort but also exposes the domains to which the CSP policy applies. Each domain added to the CSP policy is potentially a vulnerability point if not properly managed.

Solution with Iframe and Auth Token

To mitigate these risks and meet the flexibility required by our clients, we opted to use iframes combined with authentication tokens. This solution provides an additional layer of security and avoids the need to expose or manage an extensive and dynamic list of domains.

How It Works

• Secure Authentication: Each iframe is loaded with a unique authentication token for each transaction, ensuring that only authorized users can access the content. This token is verified in real-time, providing an additional layer of security and control.
• Content Isolation: Using iframes allows content to be isolated in a separate context, reducing the risk of interference between different origins and mitigating potential attacks.
• Flexibility for Dynamic Domains: By not relying on a static CSP policy, our solution easily adapts to clients' dynamic domains without the need for constant updates to security policies.

Any concerns?

Missing something or still need help? If you are already a customer or partner, you can contact us through the Help Center.