iFrame security

Payment processing using Spreedly for tokenization requires the secure handling of sensitive customer data. Spreedly's iFrame payment form provides a secure, PCI-compliant method for collecting payment information directly from your customers' browsers, minimizing compliance burden.

However, the security of this integration relies on properly securing the communication channel between your application and the iframe. This document outlines the essential security measures for your payment pages, including robust measures such as session authentication, which is critical for preventing unauthorized use and protecting against common web vulnerabilities. Detailed information on the lifecycle and implementation of session authentication, including parameters like nonces and signatures, is available in the iFrame Lifecycle guide, and mentioned here to provide a comprehensive understanding of payment page security.

Payment Page Considerations

Including the iFrame Javascript file on a checkout page does not automatically load the library. The iFrame’s lifecycle must be explicitly managed for successful payment processing.

Providing all required parameters in every function call is crucial for successful payments and helps to fortify payment pages from bot attacks that test stolen credit card numbers. These steps establish a properly-configured iFrame integration for PCI-compliant card tokenization.

Security Requirements

Securing the iFrame is critical to minimizing card testing and other automated fraud attempts via botnets. An unsecured iFrame can be exploited as an entry point for malicious scripts that test stolen card details at scale, bypassing frontend protections. Merchants can significantly reduce exposure to this abuse by implementing robust security measures. This includes authenticating all iFrame requests using secure tokenization described here, and by following our Step-by-Step guide.

With a secure iFrame as a strong foundation, businesses can further improve protections by configuring proper security headers and applying bot-mitigation techniques such as rate limiting and token validation, among other strategies. These steps can help businesses protect both their customers and their payment pages, with iFrame as a secure component of the overall payment flow.

Enabling authentication

To enable authentication of your Create payment method API calls via iFrame, visit the environment settings page in app.spreedly.com.

We recommend selecting iFrame or Express only, and ensuring iFrame is properly configured with the arguments for secure tokenization prior to enabling its setting under "Enhanced Security". Once saved, transactions are authenticated from iFrame in this environment only, using a session nonce + signature and timestamp.

Note: When enabled, all Create payment method calls will be impacted and require authentication. This includes iFrame using the described session nonce authentication mechanism, or basic HTTP authorization for payment methods tokenized via API.

Payment Card Industry (PCI) Compliance

To achieve the highest level of PCI-DSS 4.0 compliance using iFrame, disable the creation of payment methods via direct API. After confirming any alternative methods of adding a payment method are not in use, enable the "iFrame or Spreedly Express only" option from the Environment settings page in the Spreedly application.

This prevents direct API submission of payment methods which is required to detect malicious attacks and, in general, enforce adherence to the PCI standard. The only way payment methods can be added to this environment is via the iFrame (or Express) payment forms.

PCI-DSS 4.0

Starting March 31, 2025, all merchants will be subject to new payment page requirements under the updated PCI standards. One key aspect of these new requirements is the emphasis on script security for protecting sensitive cardholder data and PII on client-side environments, particularly as applied to any third-party script merchants use on their payment pages.

Under PCI-DSS 4.0, script integrity on payment pages must be explicitly verified and managed. Scripts must be sourced from trusted providers like Spreedly, securely implemented, and must be necessary for functionality on the payment page. The standard introduces requirements such as script monitoring, the need for a Content Security Policy, or sub-resource integrity to certify that scripts loaded on the page are not tampered with. Merchants must also include written justification as to why each script is necessary as part of their payment page script inventory.

Content Security Policy

Content Security Policy (CSP) adds a layer of security to your payment page, aimed at mitigating attacks like Cross-Site Scripting (XSS). By specifying trusted domains for the browser, CSP restricts the executable script sources and reduces vectors where XSS can occur. A well-configured CSP may help assist with restrictions on unauthorized or malicious scripts from being loaded and executed. For iFrame, include the following directives to ensure proper loading of iFrame assets.

script-src https://*.spreedly.com https://www.datadoghq-browser-agent.com

child-src https://*.spreedly.com data:

iframe-src https://*.spreedly.com data:

connect-src https://*.spreedly.com https://datadoghq-browser-agent.com https://cdn-b.checkouttools.com

Script integrity

Merchants must verify and maintain script integrity for any third-party asset running on their payment page. This can be done using a combination of techniques and includes a number of varying mechanisms. Key examples are sub-resource integrity (SRI), file-integrity monitoring (FIM), manual review and whitelisting, or leveraging of other third-party providers to inspect their inventory, notifying and potentially blocking requests to any unauthorized or altered scripts running on the page.

This requirement applies to all third-party scripts on a payment page, including Spreedly's iFrame. To that end, Spreedly supports these integrity mechanisms, enabling merchants to comply with this requirement. For ease of accessibility, Spreedly publishes the version number and integrity hash for the most recent version of iFrame here.

A straightforward implementation of SRI, for example, would involve updating your iframe implementation to pin to a specific version of the script and providing the corresponding SRI hash value in the script tag. This could look like:

<head>
  <script src="https://core.spreedly.com/iframe/iframe-1.158.min.js" integrity="sha384-D8OIQOcHJl+1ANw5fBEV1ZqcGn3t3etLFeuDnmg6jfQpv/W8XhEhUhTYM4BnOCH/" 
crossorigin="anonymous"></script>
</head>

Replace sha384-D8OIQOcHJl+1ANw5fBEV1ZqcGn3t3etLFeuDnmg6jfQpv/W8XhEhUhTYM4BnOCH/ with the SRI hash for that specific version in the script tag. The crossorigin="anonymous" attribute is used to ensure that the integrity check is performed correctly.

Each time the script tag is updated to a different version, there is also a different corresponding SRI hash. To find this for your desired version of iframe, use a command-line tool like openssl or an online SRI hash generator for the correct base64-encoded hash.

A strict implementation of SRI using iframe's v1, stable or candidate release channels can be challenging due to the frequent update cadence for those versions. Therefore, if your solution to the script integrity requirements for PCI 4.0 hinges on SRI hash validation, we recommend pinning to a specific version of the script instead. The release channels can be more compatible with other solutions to this requirement, if you would like to continue using them.

Note: This solution is impacted by recent changes to our iframe deprecation policy, which ensure merchants are able to leverage a script integrity mechanism on recent, supported versions of the script.

Those pinning to a version of the script will need to update to a newer version at an annual cadence according to the iframe deprecation cycle for each version, or where required for security updates. Pinning to recent versions of the script may also be desired to take advantage of the latest feature enhancements, bug fixes and other updates.

We recommend discussing the best approach for your payment page scripts with a Qualified Security Assessor (QSA) before implementing any solution to this requirement.

Script inventory

Another aspect of PCI-DSS 4.0 is the requirement for merchants to keep an inventory of all third-party scripts on their payment page, along with the justification for usage as part of the page's functionality.

For the Spreedly iFrame, an example justification could relate to the need for secure tokenization of cardholder data, including PAN and CVV, as part of the overall payment flow.