Opening Payment Page in an iframe element of an HTML page

Overview

When opened in an iframe element, the Payment Page payment form is embedded in the merchant's web service HTML page. This option may not necessarily focus the customer's attention on the purchase but keeps the customer in the context of the web service, without interrupting their interaction with it and redirecting them to a different page.

Notice: For the payment form to be displayed correctly, the minimum dimensions of the iframe element should be 320 and 600 pixels in width and height accordingly—if smaller dimensions are specified, the form does not fit into the element. For responsive display on desktop computers, the minimum width of the element should be 480 pixels. The restrictions on the maximum size are not imposed.

For opening the payment form in an iframe element, the following should be performed on the web service side:

  1. Link the CSS library from ecommpay on the client side of the web service. The library is available at https://paymentpage.ecommpay.com/shared/merchant.css.

    Link the CSS library from ecommpay on the client side of the web service for the payment form to be displayed correctly. The library is available at https://paymentpage.ecommpay.com/shared/merchant.css.

  2. Define the events that will trigger the opening of the payment form (for example, the purchase button click).
  3. Set up the payment form to open upon the required events by using your in house-solutions or the JavaScript library from ecommpay available at https://paymentpage.ecommpay.com/shared/merchant.js.

Opening Payment Page via in-house solutions

To open Payment Page in an iframe element with the help of the merchant's in-house solutions, prepare the corresponding script that will ensure the payment form opening with the required parameters specified and signed. The information about the parameters that can be used to open Payment Page and about the signature generation is provided in the following articles: Parameters for opening payment form and Signature generation and verification.

To open Payment Page in an iframe element with the help of the merchant's in-house solutions, prepare the corresponding script that will ensure the payment form opening with the required parameters specified and signed.

Opening Payment Page via the ecommpay JavaScript library

To open Payment Page in an iframe element with the help of the JavaScript library merchant.js from ecommpay, link this library on the client side of the web service and use the corresponding calls to the EPayWidget object.

In these calls, the identifier of the iframe element must be specified in the target_element parameter of the configObj object. Without this parameter, the payment form opens either in a modal window or as a separate HTML page (if this has been set up via the redirect or redirect_on_mobile parameters).

Note: If the request for opening the payment form contains the parameters to open Payment Page in a separate tab and in an iframe element, opening the form in a separate tab is given the priority.

Apart from these aspects, in case of opening the form in an iframe element via the EPayWidget object, the work with this object is carried out according to the following general conditions that are also relevant for other options to open the payment form:

To open Payment Page in an iframe element with the help of the JavaScript library merchant.js from ecommpay, link this library and use the corresponding calls to the EPayWidget object. These calls, among other parameters in the configObj object, must contain the target_element parameter with the iframe element identifier. Apart from this, the following general conditions should be met:

  1. Each call can be made via one of the two methods:
    • bind (EPayWidget.bind)—if the payment form should be opened with a button click (with the button identifier <pay_button_id> specified).
    • run (EPayWidget.run)—if the payment form should be opened upon any other event in the user interface.
  2. Each call must contain the JavaScript object configObj with the parameters of the payment form opening and the signature for these parameters. with the parameters of the payment form opening and the signature for these parameters.

    The information about the parameters used and signature generation is provided in the following articles: Parameters for opening payment form and Signature generation and verification.

  3. If necessary, any call can also contain an HTTP request method (method)—POST or GET. If nothing is specified, the GET method is used by default.
  4. Additionally, any call can contain functions to handle the information about customer's actions (details).

    The information about such handler functions is provided in the article Handling customer behaviour events on Payment Page.

Figure 1. Signature of the methods bind and run
EPayWidget.bind('<pay_button_id>', configObj, method);

EPayWidget.run(configObj, method);
Figure 2. Example of calling the object via the bind method
EPayWidget.bind('pay_button_id', // Button identifier
    { target_element: 'widget-container', // Element identifier
      project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')
Figure 3. Example of calling the object via the run method
EPayWidget.run(    
    { target_element: 'widget-container', // Element identifier
      project_id: 42, // Project identifier
      customer_id: '17008', // Customer identifier
      payment_id: '18641868', // Payment identifier
      payment_amount: 8855, // Payment amount
      payment_currency: 'USD', // Payment currency code
      signature: 'YWb6Z20ByxpQ30hfTI' }, // Signature
    'post')

When either of the methods (bind and run) is used, the HTML code of the web service page looks as follows.

<html>
<head>
<!-- Adding ecommpay libraries -->
  <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css">
  <script src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
  <script type="text/javascript">var EP_HOST = 'https://paymentpage.ecommpay.com';</script>
<!-- Other parts -->
</head>
<body>
  <!-- HTML Web page code to add the Payment Page widget -->
  <div class="container">
      <div class="cart-info">...</div><div id="widget-container"></div>
  </div>
  <!-- JS command to open Payment Page -->
  <script type="text/javascript">
      EPayWidget.run({ target_element: 'widget-container',
                       project_id: 42,
                       customer_id: '17008',
                       payment_id: '18641868',
                       payment_amount: 8855,
                       payment_currency: 'USD',
                       signature: 'YWb6Z20ByxpQ30hfTI' });
 <!-- Other parts -->
 </script>
</body>
</html>

Customising the size of third-party services' pages

To set up the dimensions of the pages used for customer redirection to third-party services, the request for opening the payment form should contain the payment_methods_options parameter with the required values of height and width of such pages. These values are defined as redirect_window_height and redirect_window_width. These parameters can be specified as follows:

To set up the dimensions of the pages used for customer redirection to third-party services, the request for opening the payment form should contain the payment_methods_options parameter with the required values of the height (redirect_window_height) and width (redirect_window_width). These parameters can be specified as follows:

  • Directly in the payment_methods_options parameter, for all third-party services unless specified otherwise.
  • As the parameters for separate payment methods, which are specified via the codes (from the reference), according to the structure in the example below.

Note that the specified parameters are not applied when the pages of third-party services are opened in separate tabs.

Figure 4. Example of a parameter set for customising the size of third-party services pages
payment_methods_options:"{
    "redirect_window_height":1200,
    "redirect_window_width":1200,
    "card":{"redirect_window_height":600, "redirect_window_width":900},
    "neteller-wallet":{"redirect_window_height":900, "redirect_window_width":1200}
}"

In the provided example, you can see the dimensions that should be used for all third-party services by default and the dimensions for separate payment methods. These dimensions are applied as follows:

  • For all methods except card and neteller-wallet, the height and width are 1200 pixels each.
  • For the card method, the height and width are 600 and 900 pixels accordingly.
  • For the neteller-wallet method, the height and width are 900 and 1200 accordingly.