iFrame overview

For merchants who are not using iframe-v1, or iframe-stable, Spreedly has implemented a deprecation plan for iFrame where all versions that are more than 3 months out of date will be deprecated and removed from service. This ensures that all customers are on recent versions with the latest security updates. We strongly recommended implementing one of our regularly updated release channels as they will always be up to date.

📘

Please read the iFrame guide for general-purpose iFrame documentation.

The Spreedly iFrame is available from the following URL:

https://core.spreedly.com/iframe/iframe-v1.min.js

By default, an instance of the Spreedly iFrame will be available on the host page as Spreedly. Invoke the functions described in these docs using the Spreedly object.

// Invoke methods on the "Spreedly" global object,
// for instance...
Spreedly.validate();

Lifecycle

Including the iFrame Javascript file on a checkout page does not automatically load the library. The iFrame’s lifecycle must be explicitly managed using the following functions.

init

Initializes the iFrame library with secure tokenization. This must be the first call made and triggers loading of the iFrame fields.

Signature

init(environmentKey, options)

Spreedly.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {  
  "numberEl": "spreedly-number",  
  "cvvEl": "spreedly-cvv",  
  "nonce": "dd6b70a5-e070-4fa2-a3ca-0db0b45f78d0",  // Unique per session (e.g., UUID)  
  "certificateToken": "certificate",
  "timestamp": "1738252535",
  "signature": "SERVER_GENERATED_HMAC" // HMAC-SHA256(nonce + private key, certificate, timestamp)  
});  

ℹ️

The call to init must be made after the DOM elements for numberEl and cvvEl have been created.

Security Requirements

⚠️ These arguments are required to authenticate requests to Spreedly's Core API for new and existing payment methods.

• nonce: A unique, cryptographically random value generated per session to prevent replay attacks.
• timestamp: A timestamp of the request which indicates the window of time a nonce is valid; Epoch time recommended.
• certificateToken: the Spreedly certificate token returned to a merchant when storing the public portion of their asymmetric key pair; used for verification of the digital signature.
• signature: A server-generated hash string created by a merchant using the nonce + timestamp + certificateToken, signed with a merchant-controlled private key.

Arguments

Events

Key Notes

1. Security Compliance:
   • Enabling this functionality allows for further confidence in risk assessments, performance of rate-limiting and other moderation strategies for transaction attempts using iFrame on a payment page.
   • HMAC validation ensures request integrity and authenticity, aligning with PCI-DSS 4.0’s script/data integrity requirements.
   • Never hardcode secrets client-side—generate signature server-side using a securely stored private key.
2. Implementation Steps:
   • Generate a unique nonce (e.g., UUID) for each payment session, and for each instance of iframe.
   • Compute signature server-side via HMAC-SHA256 using the nonce + timestamp + certificateToken and your private key.
   • Send these arguments during the init call to ensure authentication of your session and associated Create payment method call.

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, this authenticate transactions from iFrame in this environment only, using a session nonce + HMAC 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.

reload

Reload the iFrame library. This resets and re-initializes all iFrame elements and state and is a convenient way to quickly reset the form.

Spreedly.reload();

When reload is complete, the ready event will be fired, at which time the iFrame can be customized.

Signature

reload()

removeHandlers

Remove all event handlers currently registered via the on function.

Spreedly.removeHandlers();

Signature

removeHandlers()

SpreedlyPaymentFrame

Create a new, independent, instance of the iFrame. It will be created alongside the default instance, already exposed as Spreedly. Note that unique security parameters must be passed for this other instance.

// Create a new instance  
var otherIFrame = new SpreedlyPaymentFrame();

// Configure as usual  
otherIFrame.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {  
  "numberEl": "spreedly-number",  
  "cvvEl": "spreedly-cvv",  
  "nonce": "dd6b70a5-e070-4fa2-a3ca-0db0b45f78d0",  // Unique per session (e.g., UUID)  
  "certificateToken": "certificate",
  "timestamp": "1738252535",
  "signature": "SERVER_GENERATED_HMAC" // HMAC-SHA256(nonce + private key, certificate, timestamp)  
});  

otherIFrame.on("ready", function() {  
  // Style etc...  
});

ℹ️

Only instantiate a new instance of the iFrame if you want to use multiple payment forms on the same host page. Otherwise, use the default Spreedly instance that is automatically created on the page.

Signature

SpreedlyPaymentFrame()

Set parameters

Sets parameters to bypass some validation features of the iframe. Valid parameters that can be passed are allow_blank_name and allow_expired_date. If set to true, the related steps in validation will be skipped. Defaults to false.

// On an active Spreedly instance
// Validation will not require any of the name fields
Spreedly.setParam('allow_blank_name', true);

// Validation will still require a date, but it can be expired
Spreedly.setParam('allow_expired_date', true);