iFrame Javascript API

These are the API docs for version 1 of the Spreedly iFrame Javascript API.

For customers who are not using iframe-v1, or iframe-stable, Spreedly is implementing 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.

The Spreedly iFrame is available from the following URL:

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

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

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.

Lifecycle

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

init

Spreedly.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {
  "numberEl": "spreedly-number",
  "cvvEl": "spreedly-cvv"
});

Initialize the iFrame library. This must be the first call made to iFrame and will trigger the loading of the iFrame fields.

Signature

init(environmentKey, options)

Arguments

Name	Description
environmentKey	The key of the Spreedly environment where the payment method should be tokenized
options	Map of initialization options. numberEl should be set to the id of the HTML element where the number iFrame field should be rendered. cvvEl should be set to the id of the HTML element where the CVV iFrame field should be rendered.

Events

Name	Triggered
ready	When the iFrame has been initialized, rendered, and is ready for further configuration

reload

Spreedly.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.

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

Signature

reload()

removeHandlers

Spreedly.removeHandlers();

Remove all event handlers currently registered via the on function.

Signature

removeHandlers()

SpreedlyPaymentFrame

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

// Configure as usual
otherIFrame.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {
  "numberEl": "number-parent",
  "cvvEl": "cvv-parent"
});

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

Create a new, independent, instance of the iFrame. It will be created alongside the default instance, already exposed as Spreedly.

Signature

SpreedlyPaymentFrame()

Set Parameters

// 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);

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.

ThreeDS Lifecycle

Spreedly ThreeDS Lifecycle object is used to help simplify your frontend integration with Spreedly 3DS2 Solutions.

The Lifecycle object polls the Spreedly backend and emits events when the transaction changes status or times out. When a 3DS Challenge needs to be displayed to a cardholder, it will create an <iframe> element and inject it with the <form> from the acquiring bank.

new

var lifecycle = new Spreedly.ThreeDS.Lifecycle({
  // The key of the Spreedly environment where the payment method should be tokenized
  environmentKey: '...', // (highly recommended)

  // The DOM node that you'd like to inject hidden iframes
  hiddenIframeLocation: 'device-fingerprint', // (required)

  // The DOM node that you'd like to inject the challenge flow
  challengeIframeLocation: 'challenge', // (required)

  // The token for the transaction - used to poll for state
  transactionToken: '...', // (required)

  // The css classes that you'd like to apply to the challenge iframe.
  // e.g. 'red-border left-positioned custom-styles'
  challengeIframeClasses: '...', // (optional)
})

Arguments

Name	Description	Required/Optional
environmentKey	The key of the Spreedly environment where the payment method should be tokenized	O
hiddenIframeLocation	The DOM node that you’d like to inject hidden iframes.	R
challengeIframeLocation	The DOM node that you’d like to inject the challenge flow	R
transactionToken	The token for the transaction - used to poll for state	R
challengeIframeClasses	The css classes that you’d like to apply to the challenge iframe	O

start

lifecycle.start()

Starts Spreedly’s 3DSecure asynchronous flow once it is completely setup using the new constructor.

Signature

start()

Events

Before start() is invoked, the following events need to be wired with the Spreedly.on listener, see 3ds:status:

Name	Triggered
3ds:status	Setup event handling and kickoff 3DSecure lifecycle

Tokenization

tokenizeCreditCard

Spreedly.tokenizeCreditCard({

  // Required
  "first_name": document.getElementById("first-name").value,
  "last_name": document.getElementById("last-name").value,
  "month": document.getElementById("month").value,
  "year": document.getElementById("year").value,

  // Optional
  "email": document.getElementById("email").value,
  "zip": document.getElementById("zip").value,
  "metadata": {
    "customField1": document.getElementById("customField1").value,
    "customField2": document.getElementById("customField2").value
  }
});

Trigger tokenization of the entered credit card. This will send the data contained within the iFrame fields to the Spreedly environment, along with any additional payment method data specified here.

On successful tokenization, the paymentMethod event will be triggered. On failure, the errors event will be triggered.

Signature

tokenizeCreditCard(additionalFields)

Arguments

Name	Description
additionalFields	Map of additional payment method fields to store alongside tokenized card

The list of additional payment method fields that can be set on tokenization include:

Name
first_name required unless full_name is specified
last_name required unless full_name is specified
full_name required unless both first or last names are specified
month
year
email
address1
address2
city
state
zip
country
phone_number
company
shipping_address1
shipping_address2
shipping_city
shipping_state
shipping_zip
shipping_country
shipping_phone_number
eligible_for_card_updater Defaults to true. Value passed must be a boolean, or the string ‘true’ or 'false’
metadata key-value pairs

Events

Name	Triggered
paymentMethod	When a payment method is successfully tokenized
errors	When a payment method is not successfully tokenized

validate

Spreedly.validate();

Request iFrame fields to report their validation status. Useful for real-time validation functionality.

Signature

validate()

Events

Name	Triggered
validation	When validate is invoked

Recache

Update the CVV on an already tokenized credit card.

Note: A credit card must be retained in your environment in order to re-cache its CVV.

setRecache

Spreedly.on('ready', function(){
 Spreedly.setRecache("56wyNnSmuA6CWYP7w0MiYCVIbW6" , {
   'card_type': 'visa',
   'last_four_digits': '1234'
 });
});

Configure the iFrame to operate in recache mode. When iFrame has received and displayed the existing payment method information, the recacheReady event will be fired.

Signature

setRecache(token, options)

Arguments

Name	Description
token	Token of existing payment method in Spreedly environment
options	Map of display options for existing payment method. Set card_type to support CVV validation, and last_four_digits to show the last four digits in the number field.

Events

Name	Triggered
recacheReady	When the iFrame has been properly configured for recache

recache

Spreedly.recache();

Trigger recache on existing payment method. Requires that setRecache has already been called.

On successful recache, the recache event will be triggered. On failure, the errors event will be triggered.

Signature

recache()

Events

Name	Triggered
recache	When a payment method is successfully recached
errors	When a payment method is not successfully tokenized

UI

setFieldType

Spreedly.on('ready', function() {
  Spreedly.setFieldType("number", "tel");
});

Set the input type of the iFrame fields. This is useful to when you want different keyboards to display on mobile devices.

By default, the iFrame fields are set to type=number, which displays the numerical keyboard in most browsers on most mobile devices. However, behavior does vary by browser. If you’d like to manually control the input field type you can do so with setFieldType.

Signature

setFieldType(field, type)

Arguments

Name	Description
field	The iFrame field to set the type. Can be one of number or cvv.
type	The input field type. Can be one of number, text or tel.

setLabel

Spreedly.on('ready', function() {
  Spreedly.setLabel("number", "Card Number");
  Spreedly.setLabel("cvv", "CVV");
});

Style iFrame fields’ label. Although the label for each iFrame field is not displayed, it is still used by screen readers and other accessibility devices.

Signature

setLabel(field, label)

Arguments

Name	Description
field	The iFrame field to set the label. Can be one of number or cvv.
label	The label text value

setTitle

Spreedly.on('ready', function() {
  Spreedly.setTitle("number", "credit card title");
  Spreedly.setTitle("cvv", "cvv title");
});

Set custom iFrame fields’ title attribute. Although the title for each iFrame field is not displayed, it can still be used by screen readers and other accessibility devices. By default, the title attribute is set to “credit card number” for the number field, and “cvv number” for the cvv field. If you would like to customize these titles you can do so with a call of this function.

Signature

setTitle(field, title)

Arguments

Name	Description
field	The iFrame field to set the title. Can be one of number or cvv.
title	The title text value

setNumberFormat

// Pretty format
Spreedly.on('ready', function() {
  Spreedly.setFieldType("number", "text");
  Spreedly.setNumberFormat("prettyFormat");
});

// Masked format
Spreedly.on('ready', function() {
  Spreedly.setFieldType("cvv", "text");
  Spreedly.setFieldType("number", "text");
  Spreedly.setNumberFormat("maskedFormat");
});

Set the card number format. If set to prettyFormat, the card number value will include spaces in the credit card number as they appear on a physical card. The number field must be set to type text or tel for pretty formatting to take effect.

If set to maskedFormat, the card number and CVV values will be masked with * as the user enters text. Both the CVV and number fields must be set to type text for the masked formatting to take effect. Once maskedFormat has been set, the toggleMask function can be called to show the card number and CVV in plain text if they are masked, or mask them if they are shown.

Signature

setNumberFormat(format)

Arguments

The following is an example of how formatting affects what is displayed in the number field:

Format	User enters	Displayed as
prettyFormat	4111111111111111	4111 1111 1111 1111
plainFormat (default)	4111111111111111	4111111111111111
maskedFormat	4111111111111111	****************

setPlaceholder

Spreedly.on('ready', function() {
  Spreedly.setPlaceholder("number", "Card");
  Spreedly.setPlaceholder("cvv", "CVV");
});

Style iFrame fields’ placeholder text.

Signature

setParameter(field, placeholder)

Arguments

Name	Description
field	The iFrame field to set the placeholder. Can be one of number or cvv.
placeholder	The placeholder text value

setStyle

Spreedly.on("ready", function() {
  Spreedly.setStyle("number", "width:225px;  height:35px;");
  Spreedly.setStyle("number", "font-size: 20px; text-align: center");
  Spreedly.setStyle("cvv", "width:60px;  height:35px;");
  Spreedly.setStyle("placeholder", "font-weight: bold; color: blue;");
});

Style iFrame fields using CSS.

Signature

setStyle(field, css)

Arguments

Name	Description
field	The iFrame field to apply the CSS to. Can be one of number or cvv.
css	The CSS to apply. Should be vanilla CSS, -moz-appearance, or -webkit-appearance. All CSS properties should be constructed as a single string.

More than one invocation of setStyle can be used per field to organize and better structure styling directives. Based on the iFrame CORS settings, we do not currently allow importing any external fonts or images.

setStyle (placeholder stying)

Style iFrame placeholders using CSS.

Signature

setStyle('placeholder', css)

Arguments

Name	Description
'placeholder’	This will apply the CSS to the placeholders in both the number and cvv fields.
css	The CSS to apply. The CSS elements that are allowed are restricted to those that can apply to the pseudo-element. All CSS properties should be constructed as a single string.

transferFocus

Spreedly.transferFocus("number");

Set the cursor focus to one of the iFrame fields. This is useful if you want to load your form with the card number field already in focus, or if you want to auto-focus one of the iFrame fields if they contain an input error.

Signature

transferFocus(field)

Arguments

Name	Description
field	The iFrame field to give focus to. Can be one of number or cvv.

toggleAutoComplete

Spreedly.toggleAutoComplete();

Toggle autocomplete functionality for card number and cvv fields. By default, the autocomplete attribute is enabled, so the first call of this function will disable autocomplete

Signature

toggleAutoComplete()

Click to Pay

Click to Pay provides a multi-factor authenticated online checkout option featuring advanced payment technology and intelligent security based on the EMVCo secure remote commerce integration. Spreedly has partnered with Mastercard to provide a way, utilizing the Spreedly iFrame, to allow merchants to make transactions via the Spreedly API with credit card information obtained via Mastercard Click to Pay. Card brands eligible to be enrolled and retrieved via C2P are Mastercard, Visa, Discover, and American Express.

For additional information go to Click to Pay docs docs.

c2pInit

To set up the C2P flow the merchant needs to initialize the iframe library with an environmentKey and at least the required options described below.

Spreedly.c2pInit("{{environmentKey}}", {
    spreedlyPaymentFormEl: "spreedly-payment-form",
    numberEl: "spreedly-number",
    cvvEl: "spreedly-cvv",
    spreedlyPaymentFormSubmitEl: "guest-checkout-submit",
    spreedlyPaymentFormC2PSubmitEl: "c2p-checkout-submit",
    emailEl: "email",
    countryCodeEl: "country-code",
    phoneEl: "phone",
    c2pFrameEl: "mastercard-ui",
    c2pFrameStyle: "width=600,height=720",
    otpEl: "otp",
    otpChannelSelectionEl: "otp-options",
    cardsEl: "cards",
    cvvContainerEl: "cvv-container",
    c2pConfig: {
        dpaData: {
            "dpaPresentationName": "Moovet Shop",
            "dpaName": "MoovetShop"
        },
        dpaTransactionOptions: {
            "paymentOptions": [{
                "dynamicDataType": "NONE"
            }],
            "transactionAmount": {
                "transactionAmount": 100,
                "transactionCurrencyCode": "USD"
            }
        },
        cardBrands: ["mastercard", "visa", "discover", "amex"]
    },
    displayCards: {
        displaySignOut: true,
        displayPreferredCard: false,
        cardSelectionType: 'radioButton'
    },
    otp: {
        type: 'overlay'
    },
    otpChannels: {
        type: 'overlay'
    }
})

Signature

Spreedly.c2pInit(environmentKey, options)

Arguments

Name	Description
environmentKey	The key of the Spreedly environment where the payment method should be tokenized.
options	Object with initialization options. Containing various fields to initialize the C2P SDK.

Options attributes

Name	Required	Type	Description
❯ spreedlyPaymentFormEl	yes	String	HTML element containing the card input form. It is used to toggle visibility based on user flow.
❯ numberEl	yes	String	HTML Frame element containing the Credit Card number.
❯ cvvEl	yes	String	HTML Frame element containing the CVV/CVC number.
❯ spreedlyPaymentFormSubmitEl	yes	String	HTML element containing the action button to trigger a Regular payment (without Click to Pay).
❯ spreedlyPaymentFormC2PSubmitEl	yes	String	HTML element containing the action button to trigger a Click to Pay payment.
❯ emailEl	no	String	HTML element containing the customer’s email address to be used in the C2P account lookup. Required unless customer.email is provided.
❯ phoneEl	no	String	HTML element containing the customer’s phone number to be used in the C2P account lookup. Required unless customer.phone is provided.
❯ countryCodeEl	no	String	HTML element containing the customer’s phone country code to be used in the C2P account lookup. Must be in international calling code format, default is “1”. Required unless customer.countryCode is provided.
❯ otpEl	yes	String	HTML element containing where the OTP element should be displayed. This should be a MC component from their UI kit and is customizable to the MC docs.
❯ otpChannelSelectionEl	yes	String	HTML element containing how the channel selection should be displayed. This should be a MC component from their UI kit and is customizable to the MC docs.
❯ cardsEl	yes	String	HTML element containing how the cards in a C2P wallet are displayed. This should be a MC component from their UI kit and is customizable to the MC docs.
❯ c2pConfig	yes	Object	Contains information passed to C2P init.
❯ c2pFrameStyle	no	String	CSS styling containing how the C2P iFrame should load. Default value: “width=600,height=720”
❯ cvvContainerEl	no	String	HTML element containing where the CVV element should be displayed/moved. If this element is not specified, then the CVV element will be displayed/moved after cardsEl element.
❯ displayCards	no	Object	Contains display cards details.
❯ ❯ displaySignOut	no	Boolean	Display sign out option with the label 'not your cards’. This option is 'true’ by default.
❯ ❯ displayPreferredCard	no	Boolean	Display the consumer preferred card and add the label 'View all cards’ to collapse the other consumer cards. This option is 'true’ by default.
❯ ❯ cardSelectionType	no	String	Display the consumer cards list as 'radioButton’ or 'gridView’. This option is 'radioButton’ by default.
❯ otp	no	Object	Contains display cards details.
❯ ❯ type	no	String	Display OTP visualization as 'overlay’ or integrated with the page. This option is 'overlay’ by default. Posible options 'overlay’ or 'none’.
❯ otpChannels	no	Object	Contains display cards details.
❯ ❯ type	no	String	Display OTP visualization as 'overlay’ or integrated with the page. This option is 'overlay’ by default. Posible options 'overlay’ or 'none’.
❯ customer	no	Object	Contains email and phone details.
❯ ❯ email	no	String	String containing the customer’s email address to be used in the C2P account lookup. Required unless emailEl is provided.
❯ ❯ phone	no	String	String containing the customer’s phone number to be used in the C2P account lookup. Required unless phoneEl is provided.
❯ ❯ countryCode	no	String	String containing the customer’s international phone country code to be used in the C2P account lookup. Must be in international calling code format, default is “1”. Required unless countryCodeEl is provided.
❯ c2pFrameEl	no	String	HTML element containing where the C2P iFrame should load. If you do not include this element, the checkout will open in an external window.

c2pConfig Note:

The Mastercard C2P implementation has an init function, and it has been integrated in iFrame inside the Spreedly.c2pInit function. Therefore, the parameters that are required to C2P are those defined in iFrame in c2pConfig, the following guide shows what they are and how to use them:

Considerations:

1. The srcDpaId parameter is required but does not need to be specified because internally Spreedly is taking this value from the Mastercard Click to Pay SDK script definition.

2. The same is true for the dpaTransactionOptions.dpaLocale and locale parameters. Each Mastercard UI component (src-otp-input, src-otp-channel-selection, src-card-list, etc) uses the same locale parameter that is specified in the Click to Pay SDK script URL.

3. Locale for users who have a C2P profile, the language in the checkout process will be the language of the user profile, not the one that you have configured on your website or applications.

4. MUST request FPAN from Mastercard C2P API because DPAN is not supported at this time with Spreedly.

5. c2pConfig.cardBrands supports the following brands: mastercard, visa, amex, and discover.

6. When Click to Pay is initialized, Mastercard waits several seconds for each of the requested card brands to load. If any of the card brands exceed the timeout, they will not be included as an available brand and thus will be unavailable for checkout process.

7. For dpaTransactionOptions.dpaBillingPreference attribute the default value is NONE. The other options you can set are FULL (to show a full address) or POSTAL_COUNTRY.

Mastercard Developers - Click to Pay integration

Checkout

Once the user selects a credit card, the merchant should enable or show a next or checkout button that triggers the Spreedly.c2pCheckout function. This function calls Mastercard and Spreedly, and the result is a Spreedly payment method token that the merchant can use in their backend for authorize/purchase transactions as usual.

Signature

Spreedly.c2pCheckout(options)

Options attributes

Name	Description
isCheckoutWithCard	Required, Boolean. Flag to know if it is a checkout with an existing card or a new card.

Events

Spreedly.on("event name", function(args) {
  // Invoke your own functionality, using any
  // args passed in to the listener function
});

iFrame emits a variety of state-change events to the host page, which can register to respond to the event.

To register for an event, use the on registration function. To remove all event handlers, use the removeHandlers function.

3ds:status

Setup event handling after kickoff of Spreedly ThreeDS Lifecycle.

Note: If you plan to run multiple 3DS authentications without a full page reload or redirect, this function should only be set up once. Invoking it multiple times will register the event handlers multiple times leading undefined behavior.

Spreedly.on("3ds:status", function(evt) {
  console.log(`3DS Status Update from Spreedly ThreeDS Lifecycle: ${evt}`);

  switch (evt.action) {
    case "challenge":
      // show the challenge-modal
      break;
    case "succeeded":
      // finish your checkout and redirect to success page
      break;
    case "finalization-timeout":
      // present an error to the user to retry
      break;
    case "error":
      // present an error to the user to retry
      break;
    case "trigger-completion": // only applicable for Spreedly Gateway Specific 3DS integrations
      // "Trigger Completion Event. Manually complete your transaction"
      break;
    default:
      console.log(`Event ${evt.action} not handled`)
  }
});

Event handler

function(evt)

Arguments

Name	Description	Note
evt	contains the context of the 3DS status

In addition, you must handle all possible evt.action values:

Action	Trigger	Note
succeeded	Transaction has finished and it’s time to move your user away from your checkout page.
error	There was an error with the transaction and you should either present an error to the user or cancel the transaction. Transactions that have failed cannot be updated or used to challenge the cardholder again; if you would like to present a cardholder with a new challenge upon failure, a new transaction should be used. The event has a response hash that contains information on the transaction state, message, and error_code if available.
challenge	It’s time to pop open the challenge flow, see our integration guides
finalization-timeout	Customer authentication could not be completed within the expected window. This gets triggered 10-15 minutes after presenting a challenge without the transaction state changing. It is recommended that merchants attempt a manual completion here to attempt to continue or finalize the transaction
trigger-completion	Make the authenticated transaction completion call from your backend to Spreedly and call event.finalize` with the response data in your frontend.	3DS Gateway Specific only

consoleError

Spreedly.on("consoleError", function(error) {
  console.log("Error from Spreedly iFrame: " + error["msg"]);
});

Triggered when a javascript error occurs within the iFrame. This is useful for debugging runtime issues.

Event handler

function(error)

Arguments

Name	Description
error	Map of error properties. Keys inlude msg, url, line, col

errors

Spreedly.on('errors', function(errors) {
  messageEl = document.getElementById("message");
  for(var i = 0; i < errors.length; i++) {
    messageEl.innerHTML =
      "Error saving card " + errors[i]["key"] + ": " + errors[i]["message"]
  }
});

Triggered when a payment method is not successfully tokenized or recached. Requires a call to tokenizeCreditCard or recache.

Event handler

function(errors)

Arguments

[
  {
    "attribute":"first_name",
    "key":"errors.blank",
    "message":"First name can't be blank"
  }, {
    "attribute":"last_name",
    "key":"errors.blank",
    "message":"Last name can't be blank"
  }
]

Name	Description
errors	An array of error objects with attribute, key, and message fields describing the errors on the payment method when submitted to Spreedly

The list of error keys include:

Key	Description
errors.account_inactive	A non-test card number was submitted against a test (unpaid) account. This can also occur when an invalid card number is submitted while testing as Spreedly assumes all unknown card numbers are real.
errors.environment_key_parameter_required	An environment was not specified. Specify one when initializing iFrame: Spreedly.init("your_environment_key");
errors.invalid_environment_key_parameter	The specified environment key is not valid. Check the supplied environment key value and re-submit.
errors.blank	The payment method field specified by the attribute property of this error was submitted without a value, which is required by Spreedly. Display an appropriate error message and prompt the user to fill in the specified fields.
errors.invalid	The payment method field specified by the attribute property of this error was submitted with an invalid value (e.g., a month value of “13”). Display an appropriate error message and prompt the user to correct the specified fields.
errors.blank_card_type	The credit card number was invalid; we were unable to determine the card type.
errors.expired	The payment method month and year indicates that it is expired. Display an appropriate error message and prompt the user to enter a non-expired payment method.
errors.unknown_referrer	Spreedly could not determine the source (referring URL) of the form submission. A referring URL is required to identify MITM attacks.
errors.invalid_referrer	The form submission did not originate from the Spreedly payment frame and has been rejected. This is a protection against MITM attempts.
errors.configuration	If iFrame is configured to recache but tokenizeCreditCard is invoked, or iFrame is configured to tokenize but recache is invoked.

fieldEvent

Spreedly.on('fieldEvent', function(name, type, activeEl, inputProperties) {
  if(name == "number") {
    numberParent = document.getElementById("spreedly-number");

    if(type == "focus") { numberParent.className = "highlighted"; }
    if(type == "input" && !inputProperties["numberValid"]) {
      numberParent.className == "error";
    }
  }
});

Triggered when an input event occurs in either iFrame field. This is useful to provide real-time feedback to the user.

Event handler

function(name, type, activeEl, inputProperties)

Arguments

Name	Description
name	The name of the field triggering the event. One of number or cvv.
type	The event type. One of focus, blur, mouseover, mouseout, input, enter, escape, tab, or shiftTab
activeEl	The name of the field that currently has focus (this can be different from the named field depending on the event). One of number or cvv.
inputProperties	Map of properties indicating the state of the user’s input in the iFrame fields. This map is only populated on the input event type.

The list of event types include:

Type	Fired when
blur	An iFrame field has lost focus. Note that on iOS devices this event does not consistently trigger. As a workaround, we have seen some customers use the mouseout event in place of blur when iFrame is used in Safari or a WKWebview on iOS.
enter	The user has pressed “enter” while in an iFrame field
escape	The user has pressed “escape” while in an iFrame field
focus	An iFrame field has gained focus
input	The user has entered a new input value into an iFrame field
mouseover	The cursor has moved onto an iFrame field
mouseout	The cursor has left an iFrame field
shiftTab	The user has pressed the “shift+tab” key combo while in an iFrame field
tab	The user has pressed “tab” while in an iFrame field

{
  "cardType": "visa",
  "validNumber": true,
  "validCvv": true,
  "numberLength": 16,
  "cvvLength": 3,
  "iin": "41111111"
}

inputProperties includes the following keys on the input event type.

Name	Description
cardType	The type (brand) of the card. One of supported card identifiers.
validNumber	This will check if the supplied card number is a supported brand and expected length. If the brand has an algorithm check, it validates that the algorithm passes. Will return either true or false.
validCvv	This will check if the supplied CVV matches the expected length based on the card type, and is comprised of only numbers. Will return either true or false.
numberLength	The length of the value entered into the number field
cvvLength	The length of the value entered into the CVV field
iin	The issuer identification number (IIN) of the supplied card number. All card types (brands) will return the first 6 digits as the number is entered. Visa and MasterCard brands will also return the first 8 digits.

paymentMethod

Spreedly.on("paymentMethod", function(token, paymentMethod) {

  // Send requisite payment method info to backend
  var tokenField = document.getElementById("payment_method_token");
  var fingerprintField = document.getElementById("payment_method_fingerprint");

  tokenField.setAttribute("value", token);
  fingerprintField.setAttribute("value", paymentMethod["fingerprint"]);

  var masterForm = document.getElementById('payment-form');
  masterForm.submit();
});

Triggered when a payment method is successfully tokenized by Spreedly. The host page must handle this event to take the payment method token and send it to the backend environment for further processing. Requires a call to tokenizeCreditCard.

Supports BIN metadata for Advanced Vault enabled cards. See the BIN Metadata guide for more information.

Event handler

function(token, paymentMethod)

Arguments

Name	Description
token	The token of the newly tokenized payment method. Tokens are alphanumerics in the form M8TBiUmc19cjV16PdMbsj65uViL.
paymentMethod	A map of the full payment method in JSON form

ready

Spreedly.on("ready", function() {
  Spreedly.setStyle("number", "font-family: 'Arial';")
});

Triggered when the iFrame is initialized and ready for configuration. setStyle and other UI function calls should be made within this event listener. This event will only fire after init() has been called.

Event handler

function()

recache

Spreedly.on("recache", function(token, paymentMethod) {

  // Send ping back to server for post-recache transaction processing
  var masterForm = document.getElementById('payment-form');
  masterForm.submit();
});

Triggered when a payment method is successfully recached by Spreedly (and the CVV is now available on the payment method). The host page must handle this event to ping the backend environment that the payment method is ready for further processing. Requires a call to recache.

Event handler

function(token, paymentMethod)

Arguments

Name	Description
token	The token of the recached payment method. Tokens are alphanumerics in the form M8TBiUmc19cjV16PdMbsj65uViL.
paymentMethod	A map of the full payment method in JSON form

recacheReady

Spreedly.on("recacheReady", function() {
  // Enable form submit button or other logic dependent on
  // recache readiness...
  var paymentButton = document.getElementById('payment-form-button');
  paymentButton.disabled = false;
});

Triggered when iFrame is properly configured for recache.

Event handler

function()

validation

Spreedly.on('validation', function(inputProperties) {
  if(!inputProperties["validNumber"]) {
    messageEl = document.getElementById("message");
    messageEl.innerHTML = "Please enter a valid credit card number";
  }
});

Triggered when validation of the iFrame is requested. This event will only fire after validate() has been called.

Event handler

function(inputProperties)

Arguments

Name	Description
inputProperties	Map of properties indicating the state of the user’s input in the iFrame fields

{
  "cardType": "visa",
  "validNumber": true,
  "validCvv": true,
  "numberLength": 16,
  "cvvLength": 3,
  "iin": "41111111"
}

inputProperties includes the following keys:

Name	Description
cardType	The type (brand) of the card. One of supported card identifiers.
validNumber	This will check if the supplied card number is a supported brand and expected length. If the brand has an algorithm check, it validates that the algorithm passes. Will return either true or false.
validCvv	This will check if the supplied CVV matches the expected length based on the card type, and is comprised of only numbers. Will return either true or false.
numberLength	The length of the value entered into the number field
cvvLength	The length of the value entered into the CVV field
iin	The issuer identification number (IIN) of the supplied card number. All card types (brands) will return the first 6 digits as the number is entered. Visa and MasterCard brands will also return the first 8 digits.

NOTE: If validNumber is false, iFrame will prevent a call to tokenizeCreditCard. However, the validCVV property will not prevent a call to tokenizeCreditCard, since not all customers require a valid CVV at time of tokenizing.

Testing

Many development teams utilize automated testing to test their browser-based workflows. The following functions should aid in that endeavor.

setValue

Spreedly.on("ready", function() {
  Spreedly.setValue("number", "4111111111111111");
  Spreedly.setValue("cvv", "123");
});

Set the value the iFrame fields to a known test value. Any values that are not on the allowed list will be silently rejected.

Signature

setValue(field, value)

Arguments

Name	Description
field	The iFrame field to set the value. Can be one of number or cvv.
value	The value to set the field to. The number field will only accept test card numbers. The cvv field will only accept 12, 123, or 1234

Scheduled Releases

Spreedly offers a staggered, scheduled iFrame releases for users that wish to test changes before accepting them.

<head>
    <script> src="https://core.spreedly.com/iframe/iframe-[desired channel].min.js" </script>
</head>

v1 is the most current version and is continuously updated with no set release schedule.

candidate is updated on the 1st Tuesday of every month to match iframe-v1

stable is updated on the 3rd Tuesday of every month to match the latest version of iframe-candidate

iFrame Changelog RSS feed available here: https://core.spreedly.com/iframe/feed.xml.

If you encounter issues while using iframe-candidate.min.js, please contact support for assistance.

Plugins

Spreedly provides helper functions in our iFrame that help our customers get the most out of their integrations.

stripeRadar

function callback(radarSessionId) {
  // pass radar_session_id to your backend to use it
  // as a gateway specific field when making and authorization
  // or purchase request
}

Spreedly.stripeRadar('pk_examplepk', callback);

The Spreedly.stripeRadar function allows Spreedly customers using the Stripe or Stripe Payment Intents gateways to integrate with Stripe’s Radar fraud detection tools. For more information on how to use this, see the Stripe or Stripe Payment Intents gateway guides.

This function is asynchronous in that it requires an API call to Stripe. If any failures occur, the callback will receive a null value for the radarSessionId. The transaction should still be performed in this case, but it will not leverage Stripe’s frontend fraud detection.

NOTE: The stripeRadar function uses Javascript’s console.log to log any problems with the integration. Check your browser’s console during development to ensure that any suggestions that it makes are fixed before going to production.

Signature

stripeRadar(publishableKey, callback, options)

Arguments

Name	Description
publishableKey	The Stripe publishable key for the account that the purchase or authorization will be created on. This can be found in the Stripe developer dashboard.
callback	Upon completion of the Stripe API call, the callback function will be called with one argument: the Stripe Radar Session ID. This ID should be passed into your Stripe or Stripe Payment Intents transaction via the radar_session_id Gateway Specific Field.
options	Accepts stripeAccount which specifies a Stripe connected account ID and allows you to perform actions on behalf of that account. For usage with Stripe Connect only.

createStripePaymentElement

const element = Spreedly.createStripePaymentElement({
  publishableKey: 'pk_...',
  clientSecret: clientSecret,
  paymentElement: '#payment-element',
  transactionToken: spreedlyTransactionToken,
  appearance: stripeAppearanceObject
});

The Spreedly.createStripePaymentElement function allows transactions using Alternative Payment Methods on the Stripe Payment Intents gateway begins the process by injecting the Stripe Payment Element form into the checkout page.

For more information, see the Making a Payment with Stripe APMs guide

Signature

Spreedly.createStripePaymentElement(options)

Arguments

Name	Description
options	An object that contains all other arguments available on Stripe Intents below
❯ publishableKey	The publishable key attached to the Stripe account making this purchase. This value can be found in the Stripe developer dashboard.
❯ clientSecret	The client secret is a field returned in the pending transaction from Step 1 that authorizes the frontend to complete the purchase. This value can be found in the Spreedly transaction response at transaction.gateway_specific_response_fields.stripe_payment_intents.client_secret.
❯ transactionToken	The Spreedly transaction token returned by the pending transaction from Step 1.
❯ paymentElement	An HTML DOM element that the Payment Element will be injected into.
❯ appearance (optional)	See the Stripe Appearance API for more information.

Return Value

if (element.error) { handle(error); }

// This will redirect the customer to complete their order
checkoutButton.onclick = element.confirmPayment;

This function returns an object with the following public fields and methods:

element.error

The error field is a string if something went wrong, such as an invalid publishable key, invalid input fields, or Stripe.js not being on the page. These are mostly used during implementation to ensure that the call is being performed correctly. Any value here mean that the Payment Element has not been displayed. If no errors occur when mounting the Payment Element, this function returns undefined.

element.confirmPayment();

When the customer is ready to checkout, confirmPayment() should be called to begin the redirect. This function has no return value as the customer will be redirected to complete the purchase. This should only be called if error is not present.

createBraintreePaymentElements

const element = Spreedly.createBraintreePaymentElements({
  callbackFunction: callbackFunction,
  transactionToken: transactionToken,
  environmentKey: enviornmentKey,
  paymentElements: {paypal: 'paypal-payment-element'},
  style: {paypal: { color: 'blue', height: 45, shape: 'rect'}}
});

The Spreedly.createBraintreePaymentElements function allows transactions using Alternative Payment Methods on the Braintree Blue gateway. It begins the process by injecting the Braintree Payment Element form into the checkout page.

For more information, see the Alternative Payment Methods section in the Braintree Gateway Guide

Signature

Spreedly.createBraintreePaymentElements(options)

Arguments

Name	Description
options	An object that contains all other arguments available on Braintree below
❯ callbackFunction	This is a callback function provided by the customer. When we receive a successful, cancelled or error response from Braintree we will return a object to that callback function. The response returned here will be used in Step 3.
❯ transactionToken	The Spreedly transaction token returned by the pending transaction from Step 1.
❯ paymentElements	An object with HTML DOM element that the Payment Element will be injected into. Send the payment elements you are trying to render.
❯ environmentKey	The Spreedly environment key.
❯ style	An object that accepts parameters to configured the display of the PayPal button. The accepted parameters are color, height, shape and layout.

• The following are the accepted values for each style parameter
  • layout: vertical or horizontal
  • color: gold, blue, silver, white or black
  • shape: rect or pill
  • height: between 25 to 55

Return Value

if (element.error) { handle(error); }

element.error

The error field is a string if something went wrong, such as missing parameters or the different Braintree scripts not being on the page. These are mostly used during implementation to ensure that the call is being performed correctly. Any value here mean that the Payment Element has not been displayed. If no errors occur when mounting the Payment Element, this function returns undefined.

  {
    "state": "Successful",
    "nonce": "paymentMethodNonce",
    "payment_method": {
      "payment_method_type": "paypal"
    }
  }

If the customer successfully completes their payment after they click the respective button then a object will be returned. This object will contain state, nonce, payment_method and possibly other parameters.

  {
    "state": "Failed",
    "message": "undefined Error: PayPal payment options are invalid. at Tr.error…",
    "payment_method": {
      "payment_method_type": "paypal"
    }
  }

If an unexpected error occurs then a object will be returned to the callbackFunction. This objects will contain state, message and payment_method.

  {
    "state": "Cancelled",
    "message": "PayPal payment cancelled, {\n \"orderID\": \"EC-8XN05533WV243142V\"\n}",
    "payment_method": {
      "payment_method_type": "paypal"
    }
  }

If a customer cancels their payment then a object will be returned to the callbackFunction. This objects will contain state, message and payment_method.

Note this is just an example for PayPal but you can find examples for Venmo in our Alternative Payment Methods section of the Braintree Gateway Guide.