Recurly.js v4 replaces legacy approaches with Elements, a flexible, iframe-based system that improves security, styling control, and future-proof access to features such as 3-D Secure, Apple Pay, and risk tools. This upgrade guide shows:

1. How to convert Hosted Fields configs to Elements.
2. What changes are required when moving from v3.
3. Why versions prior to v3 require a full re-implementation.

Prerequisites and limitations

• Site must already be on Recurly.js v4+ (Elements are not back-ported).
• Token format unchanged – existing server-side API calls continue to work once you pass the new token.
• Upgrading from v2 or earlier necessitates a complete rewrite; there is no drop-in shim.

Key details

Upgrading from previous versions and deprecated features of Recurly.js

Upgrading from Hosted Fields to Elements

Recurly.js v4.11.0 introduced Elements, a new API for displaying and controlling UI components of Recurly.js. They fulfill all of the roles that Hosted Fields had -- to display credit card inputs on your payment pages. Elements bring a more flexible API for interacting with objects that render to your page. So while their main use-case will be to render card inputs, in the future they will also be used to interact with other UI components, like 3-D Secure challenges, Apple Pay, PayPal flows, price information, and risk/fraud detection.

Hosted Fields had exposed their interface through recurly.configure. In migrating to Elements, you will move this configuration to Element constructors:

Setup changes

Old Hosted Field Setup

<div data-recurly="card"></div>

recurly.configure({
  publicKey: 'my-public-key',
  fields: {
    card: {
      inputType: 'mobileSelect',
      style: {
        fontColor: '#010101'
      }
    }
  }
});

New Setup with Elements

<div class="my-card-element"></div>

recurly.configure('my-public-key');

const elements = recurly.Elements();
const card = elements.CardElement({
  style: {
    inputType: 'mobileSelect',
    fontColor: '#010101'
  }
});
card.attach('.my-card-element');

Changes to Event Listeners

If you are listening for changes to Hosted Field using the 'change' event, you will now listen for these changes on an Element instance.

Old Hosted Field change listener

recurly.on('change', (state) => {
  if (state.fields.card.focus) {
    // Listen for focus on my card field
  }
});

recurly.on('field:submit', () => {
  // Listen for use pressing <enter> within a hosted field
});

New Elements event listeners

const elements = recurly.Elements();
const card = elements.CardElement();

card.on('change', (state) => {
  // Listen for any change to my Element
});

card.on('focus', (state) => {
  // Listen for user focus on my Element
});

card.on('blur', (state) => {
  // Listen for user blur on my Element
});

card.on('submit', () => {
  // Listen for use pressing <enter> within an Element
});

See Elements for details on all events emitted by an Element.

Changes to Getting a Token

When creating a token from Elements, it is necessary to pass your Elements instance to recurly.token along with the form containing your user's billing information. This allows for the flexibility of creating many Elements on a single page, and improved specificity.

Old Hosted Field token creation

const form = document.querySelector('#my-form');
recurly.token(form, (err, token) => {
  // handle my new token
});

New token creation with Elements

const elements = recurly.Elements();
const form = document.querySelector('#my-form');

// create and attach my Element instances

recurly.token(elements, form, (err, token) => {
  // handle my new token
});

We are happy to assist further in your upgrade path. Feel free to reach out to us for Support.

Upgrading from v3

Recurly.js v4 introduced the concept of Elements. These are a more secure method of capturing customer card data, ensuring that their payment information is never exposed to your payment form. This is a huge benefit for security and reduced PCI compliance exposure.

First, you will need to update your payment form. The credit card fields number, month, year, and cvv will need to be removed and replaced with a container element in the form <div id="my-recurly-card-element"></div>. The id is entirely optional, and is simply added for ease of reference. We recommend using the card field since it incorporates validation and UX improvements, but it is also possible to use separate fields for the number, month, year, and cvv. This is explained more completely in the Getting Started section.

Your recurly.token call may also need to be updated. It is now necessary to pass a reference to your Elements instance and the checkout <form> that contains your user's billing info. Your callback function requires no modification. More info is available in the Getting a Token section.

You'll notice that the Elements won't look like the rest of your payment form inputs. That is because they are in fact iframes, and will need to be styled in order to get them to look right. We provide a stylesheet that works as a good baseline for styling the Elements to your needs (See the Getting Started section). To tweak styles further, and to cover styles for when the Element is focused, etc, see the Styling Elements section.

We are happy to assist further in your upgrade path. Feel free to reach out to us for Support.

Upgrading from versions prior to v3

Since version 3, Recurly.js shifted to credit card tokenization as its method of billing info capture. Given the significant changes, upgrading from an earlier version of Recurly.js will require a full rewrite of your integration. Please see the Getting Started section to begin.