Full-Page Redirect vs Iframe-Based Integration

There are two methods to use the Hyp CreditGuard payment page:

1. Full-page redirect. This involves redirecting to the payment page hosted on the Hyp domain. This scenario is demonstrated in the article about the basic integration flow.

2. Iframe-based integration. This involves embedding the payment page inside your merchant website's page as an iframe.

As a merchant, you're free to choose between these methods based on the following factors:

• User experience. Full-page redirects take customers away from your merchant website's experience, while the iframe-based integration feels more native to the customer.

• Complexity and security. Full-page redirects are easier to implement. Iframe-based integration requires setting a content security policy to avoid security vulnerabilities, as well as keeping an eye on links from success and error pages to avoid an iframe loop.

• PCI-DSS compliance. With a full-page redirect, card details are handled 100% on the Hyp CreditGuard domain, ensuring the minimal PCI-DSS compliance scope (SAQ-A) with no additional effort. Iframe-based integration can also fall in the SAQ-A scope, but this requires you to make sure that any scripts that are loaded on your payment page that originate anywhere except from Hyp CreditGuard do not interact with the payment page iframe in any way.

If you decide in favor of iframe-based integration, below is what you need to do. Note that the instructions assume that you have read either Basic Integration Flow: Hello World With a Full Working Charge or Integrating Hyp’s Payment Page and Accepting Payment. Code samples illustrate what you need to modify compared to the sample Express.js application used in the basic integration flow tutorial.

Set a content security policy

First of all, set the content security policy with frame-src, connect-src, script-src, and img-src directives to only allow embedding iframes originating from Hyp CreditGuard's domains: https://*.creditguard.co.il.

For example, in the sample Express application, you can add middleware to server.js that sets the Content-Security-Policy header on all requests:

app.use((req, res, next) => {
  res.setHeader("Content-Security-Policy", [
    `frame-src 'self' https://*.creditguard.co.il`,
    `connect-src 'self' https://*.creditguard.co.il`,
    `script-src 'self' https://*.creditguard.co.il`,
    `img-src 'self' https://*.creditguard.co.il`
  ].join("; "));
  next();
});

Add paymentPageData to your payment page request

To open the payment page in an iframe, you make a POST request similar to how you do it to redirect to a Hyp-hosted payment page. However, in the XML payload inside the int_in parameter, you insert an additional element called paymentPageData into the doDeal element:

<ashrait>
  <request>
      <version>2000</version>
      ...
      <doDeal>
          <terminalNumber>{terminalNumber}</terminalNumber>
          ...
          <paymentPageData>
            <ppsJSONConfig>
            {"frameAncestorURLs": "https://your-merchant-website.com"}
            </ppsJSONConfig>
          </paymentPageData>
      </doDeal>
  </request>
</ashrait>

The value of the frameAncestorURLs property inside ppsJSONConfig should be one or more of your merchant website domains or pages, such as:

<paymentPageData>
  <ppsJSONConfig>
  {"frameAncestorURLs": "https://your-merchant-website.com https://pay.your-merchant-website.com https://your-other-merchant-website.com/checkout.html"}
  </ppsJSONConfig>
</paymentPageData>

Here's the full set of rules regarding the values of frameAncestorURLs:

1. The value or values should include the schema. This is normally https:// but can be http:// in the test environment.

2. The value or values can be the merchant website domain (e.g. https://your-merchant-website.com) or a specific page without query parameters (e.g. https://your-merchant-website.com/payments/checkout.html).

3. You cannot use wildcards in URLs: for example, https://*.your-merchant-website.com is not a valid value.

4. If the value contains multiple URLs, use spaces as separators.

Update your frontend to handle the payment page in an iframe

In your checkout page HTML, create an iframe element to host the payment page:

<iframe id="payment-iframe" allow="payment"></iframe>

In your CSS file, provide a basic set of styles for the iframe element, such as:

#payment-iframe {
    width: 100%;
    height: 600px;
    border: none;
    margin-top: 20px;
    overflow: auto;
}

In your checkout button event listener, when you receive the payment page URL from the backend, load it as the source of the payment-iframe element:

const response = await fetch("/checkout", {
    method: "POST",
    headers: { "Content-Type": "application/json" }
});
const data = await response.json();
if (data.paymentUrl) {
    const paymentIframe = document.getElementById("payment-iframe");
    paymentIframe.src = data.paymentUrl;
} else {
    alert("Error processing payment");
}

As a result, when the user clicks the Checkout button, the payment page will load inline and appear similar to the following:

A payment page in an iframe

Break out of the iframe

When the user completes entering payment card details and clicks Pay, Hyp CreditGuard will process the payment request and redirect the user to either a success or an error page that you specified in your initial payment page request.

By default, either of these pages opens in the same iframe as the payment page. If your success or error pages contain links, following them may result in an iframe loop. To avoid the iframe loop, you can use either of the following two methods:

1. Add the target="_top" attribute to all links in your success and error pages so that if the user clicks any of them, they open as a full page:

   <a href="/" target="_top">Return to Store</a>

2. Add a redirectTargetParent parameter to the ppsJSONConfig object in your initial payment page request. This will cause Hyp CreditGuard to redirect the user to the success or error page in the parent window instead of within the iframe:

   <paymentPageData>
     <ppsJSONConfig>
       {
         "uiCustomData": {
           "redirectTargetParent": true
         }
       }
     </ppsJSONConfig>
   </paymentPageData>