Customize Your Checkout Process and Accept Payments Securely

Securely accept sensitive payment details within your checkout process with a fully customizable user experience. The Recurly.js JavaScript library secures your checkout forms. Create subscriptions, process one-time transactions, and update customer billing information worry-free.

PCI Compliance with Recurly.js Elements

Recurly.js provides Elements, which inject transparent iframes that allow you to deliver a customized customer checkout experience, while ensuring you meet the latest PCI DSS SAQ A compliance requirements.

Open Source

Recurly.js is open source, and we welcome all to view the code and work with us on GitHub. We’re here to make Recurly.js the best possible tool for your needs.

 View code on GitHub

How It Works

When a customer submits your payment form, Recurly.js sends customer payment information to be encrypted and stored at Recurly and gives you an authorization key to complete the subscription process using our API.

With this authorization key (or token), you can do anything with our API that requires payment information. Because you never handle any sensitive payment information, your PCI scope is drastically reduced.

Getting Started

To begin, you’ll include the Recurly.js script on your page.

<script src="https://js.recurly.com/v4/recurly.js"></script>
<link href="https://js.recurly.com/v4/recurly.css" rel="stylesheet" type="text/css">

This exposes a single global object, recurly.

It is not necessary to include recurly.css, but we highly recommend it while you’re getting set up. It provides some helpful default styles to Recurly Elements.

Configure

Simply call recurly.configure anywhere on your page, passing your public key. This identifies your site to Recurly servers. You can find your public key in the API Access section of your admin app.

recurly.configure('sc-ABCDEFGHI123456789');

recurly.configure accepts other options not detailed here. You may refer to the source for more detail.

Build a Payment Form With Elements

To collect card payment information from your customers, you may build an HTML form however you wish, collecting all user data that you require. Use the data-recurly attribute to identify any non-card billing fields to Recurly.js. Card fields are built using Elements

<form id="my-form">
  <input type="text" data-recurly="first_name">
  <input type="text" data-recurly="last_name">

  <div id="recurly-elements">
    <!-- Recurly Elements will be attached here -->
  </div>

  <!-- Recurly.js will update this field automatically -->
  <input type="hidden" name="recurly-token" data-recurly="token">

  <button>submit</button>
</form>

The Card Element

This is the simplest and most streamlined way to accept customer card data. Recurly will inject a single field that will accept the card number, expiry, and cvv. This field is responsive and includes helpful UX enhancements to make card entry as smooth as possible on a multitude of devices.

const elements = recurly.Elements();
const cardElement = elements.CardElement();
cardElement.attach('#recurly-elements');

Other Elements

Recurly.js has Elements for individual card fields as well. Use these fields when you would like to display card fields separately from each other. This is helpful when the combined field does not fit your design needs.

The example forms above contain the minimum required input fields, and the tables below document all possible input fields.

Billing fields

Depending on how you’ve configured your billing address requirements, some of the fields in the table above may be required.

Styling Elements

Since elements are within iframes, any style properties within those iframes must be configured on your Element. See the code example and table below.

const cardElement = elements.CardElement({
  inputType: 'mobileSelect',
  style: {
    fontSize: '1em',
    placeholder: {
      color: 'gray !important',
      fontWeight: 'bold',
      content: {
        number: 'Card number',
        cvv: 'CVC'
      }
    },
    invalid: {
      fontColor: 'red'
    }
  }
});

Styling the card element

Options available to the card element are detailed in the following table.

Styling the individual card elements

Options unique to the individual card elements are detailed in the following table.

Common field style properties

CSS Classes

Since Recurly.js Elements are contained within iframes, the default browser appearance for those fields will likely not match the appearance of the other inputs in your billing form. We provide the following CSS classes to achieve a look and feel similar to your form. Using these classes, you may specify Element size, colors, and a full range of appearance customization to make the injected Elements blend into your payment form.

Custom Fonts

Custom fonts are sourced from Google Web Fonts. Simply use the name of the font as it appears on the Google Web Fonts site.

Responsive Styles

All of the built in element CSS classes will support and respond to media queries. You may call Element.configure to change style properties for an individual Element – thus you may change any property according to your responsive needs.

Getting a Token

Interrupt your form submit to send billing info to Recurly and get a secure token in exchange. Once you have the token, send the token to your server.

const elements = recurly.Elements();

// construct and attach your Elements...

document.querySelector('#my-form').addEventListener('submit', function (event) {
  const form = this;
  event.preventDefault();
  recurly.token(elements, form, function (err, token) {
    if (err) {
      // handle error using err.code and err.fields
    } else {
      // recurly.js has filled in the 'token' field, so now we can submit the
      // form to your server
      form.submit();
    }
  });
});

Recurly.js works with tokens, which represent secure and temporary storage for your customer’s sensitive billing information. They are stored directly on Recurly servers to reduce your PCI exposure.

When your customers submit your billing form, you’ll need to interrupt the submit and ask Recurly.js to create a token from the form. You may have noticed an additional hidden field in the form above, token. When you ask Recurly.js for a token during submit, it will automatically populate this field for you. After you get the token, you will submit it to your servers and use it there to talk to any endpoint in our API that accepts a billing_info.

Reference

fn recurly.token

You must call recurly.token with your Elements instance, and your <form> reference.

recurly.token(elements, document.querySelector('form'), tokenHandler);

Using a handler function like this one:

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

Sends billing information to Recurly to store as a token, sending that token id back to you.

Arguments

A callback is always required

Callback Arguments

Returns

Nothing.

Using a Token

Create a new purchase with a token using one of our client libraries or API v3

  purchase = {
    currency: "USD",
    account: {
      code: account_code,
      billing_info: {
        token_id: rjs_token_id
      },
    },
    subscriptions: [
      { plan_code: plan_code }
    ]
  }

  invoice_collection = @client.create_purchase(body: purchase)

  let purchaseReq = {
    currency: 'USD',
    account: {
      code: accountCode,
      billingInfo: {
        tokenId: rjsTokenId
      }
    },
    subscriptions: [
      { planCode: planCode },
    ]
  }

  let invoiceCollection = await client.createPurchase(purchaseReq)

  purchase = {
      "currency": "USD",
      "account": {
          "code": account_code,
          "billing_info": {"token_id": rjs_token_id},
      },
      "subscriptions": [{"plan_code": plan_code}],
  }
  invoice_collection = client.create_purchase(purchase)

  PurchaseCreate purchase = new PurchaseCreate();
  purchase.setCurrency("USD");

  AccountPurchase account = new AccountPurchase();
  account.setCode(accountCode);
  purchase.setAccount(account);

  BillingInfoCreate billing = new BillingInfoCreate();
  billing.setTokenId(rjsTokenId);
  account.setBillingInfo(billing);

  List<SubscriptionPurchase> subscriptions = new ArrayList<SubscriptionPurchase>();
  SubscriptionPurchase sub = new SubscriptionPurchase();
  sub.setPlanCode(planCode);
  subscriptions.add(sub);
  purchase.setSubscriptions(subscriptions);

  InvoiceCollection collection = client.createPurchase(purchase);

  const purchaseReq = new PurchaseCreate()
  {
      Currency = "USD",
      Account = new AccountPurchase()
      {
          Code = accountCode,
          BillingInfo = new BillingInfoCreate()
          {
              TokenId = rjsTokenId
          }
      },
      Subscriptions = new List<SubscriptionPurchase>()
      {
          new SubscriptionPurchase() { PlanCode = planCode }
      }
  };

  InvoiceCollection collection = client.CreatePurchase(purchaseReq);

Once Recurly.js has stored your customer’s sensitive data and given you a token reference, you will have 20 minutes to use it in our API. Expired tokens are permanently removed from the Recurly servers. Since tokens may be used to create charges in Recurly, be sure to keep them safe and only transmit them over a secure connection. Note that tokens do not expire after their first use. They can be reused as many times as you need during that 20 minute period.

Tokens can be used to populate any account Billing Info data through our API. Simply assign it to the Billing Info’s token_id property and we’ll do the rest.

These endpoints accept tokens within Billing Info.

• Purchase create
• Subscription create
• Account create, update
• Billing Info update
• Transaction create

Events

Listen to events using the Emitter methods. Any object in this document that emits events may be listened to as follows.

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

// Listen to the 'change' event
card.on('change', changeHandler);

// But we're feeling indecisive today. Let's detach this event
card.off('change', changeHandler);

function changeHandler (state) {
  // perform an action
}

Elements

Elements allow sensitive customer payment information to be securely accepted via iframes. They are controlled in groups by an Elements instance.

To use Elements, you will first create an Elements instance.

const elements = recurly.Elements();

There are several types of Elements which you may wish to use. The most common is the CardElement.

const cardElement = elements.CardElement();

Recurly.js also provides individual card Elements.

const cardNumberElement = elements.CardNumberElement();
const cardMonthElement = elements.CardMonthElement();
const cardYearElement = elements.CardYearElement();
const cardCvvElement = elements.CardCvvElement();

The reference below details the common API for interacting with Elements and Element instances. While you may be working with different Element types, their API is the same.

Reference

fn recurly.Elements

Creates an Elements instance, which associates a group of Element instances for tokenization and control. You will use this to create individual Element instances.

const elements = recurly.Elements();

Returns

A new Elements instance

events Emits

See Events for usage.

fn elements.CardElement

fn elements.CardNumberElement

fn elements.CardMonthElement

fn elements.CardYearElement

fn elements.CardCvvElement

Create an Element instance of the type respective of its name.

const cardElement = elements.CardElement({
  style: {
    fontSize: '2em'
  }
});

Arguments

Returns

A new Element instance.

events Emits

See Events for usage.

fn Element.attach

Attaches an Element to the DOM, as a child of the specified parent target.

element.attach('#my-element-container');

Arguments

Returns

The Element instance.

fn Element.configure

Updates the configuration of the Element.

element.configure({
  style: {
    fontSize: '2em'
  }
});

Arguments

Returns

The Element instance.

fn Element.focus

Moves the user’s focus to the Element.

Note: Safari on all devices will only allow focus to be moved to an Element when a user has already interacted with the Element.

Params

None

Returns

The Element instance.

fn Element.remove

If an Element has been attached, removes the Element from the DOM. If it is not attached, does nothing.

Params

None

Returns

The Element instance.

Apple Pay

Use Recurly.js to process Apple Pay transactions

Recurly.js supports Apple Pay out of the box. To get started, ensure your site is configured to accept Apple Pay transactions.

Setting up your Apple Pay integration in Recurly.js involves two parts: a) displaying the button, and b) invoking the purchase flow.

Displaying The Button

Your button styling needs to adhere to Apple’s specifications.

See Apple’s documentation on Displaying the Apple Pay Button for guidelines on display and styling the button.

Invoking The Purchase Flow

Configure a new instance of recurly.ApplePay as follows.

// Handle when the token has been generated to keep the payment sheet in the "Processing"
// state until the onPaymentAuthorized callback has completed
function onPaymentAuthorized({ payment }) {
  const { recurlyToken: token, billingContact, shippingContact } = payment;
  // Submit the token to your server
  console.log('Apple Pay succeeded.',
              'Token:', token.id,
              'billingContact:', billingContact,
              'shippingContact', shippingContact);
}

const applePay = recurly.ApplePay({
  country: 'US',
  currency: 'USD',
  label: 'My Subscription', // This text will be displayed on the Apple Pay payment sheet as "My Subscription"
  total: '29.00',
  callbacks: {
    onPaymentAuthorized,
  }
});

// When the ApplePay instance is ready, bind the Apple Pay button click
// to applePay.begin
applePay.ready(function () {
  $('#my-apple-pay-button').on('click', function () {
    applePay.begin();
  });
});

// Handle errors. These may occur at any point in the Apple Pay flow
applePay.on('error', function (err) {
  // err.code, err.message
  console.error('Apple Pay error', err);
});

ApplePay via Braintree

If you’re processing Apple Pay transactions with Braintree, you’ll pass a client authorization during instantiation:

const applePay = recurly.ApplePay({
  country: 'US',
  currency: 'USD',
  label: 'My Subscription', // This text will be displayed on the Apple Pay payment sheet as "My Subscription"
  total: '29.00',
  callbacks: {
    onPaymentAuthorized,
  }
  braintree: {
    clientAuthorization: MY_CLIENT_AUTHORIZATION
  }
});

Additional configuration

If you are using the recurly.Pricing.Checkout class to calculate checkout prices, you may pass your pricing instance instead of providing a total.

const pricing = recurly.Pricing.Checkout();

const applePay = recurly.ApplePay({
  // ...
  pricing: pricing
});

To provide additional customer data to tokens generated by recurly.ApplePay, you may pass a form reference. recurly.ApplePay will collect customer data from the form just as would occur during credit card tokenization. See Getting a Token for more information on building such a form.

const applePay = recurly.ApplePay({
  // ...
  form: document.querySelector('#my-payment-form')
});

Integration Notes

• Recurly.js will automatically pull in the billing info from the customer’s Apple account if their Apple Pay setup is complete with full billing information in their Apple Wallet. If the user does NOT have a billing name or address attached to their card in their Apple Wallet, the Apple Pay flow will prompt the customer for a billing address.
• If you choose to include a Recurly.js payment form, any billing name or address fields entered on that form will replace the billing address in the user’s Apple Wallet on the payment sheet. The user can always change their billing address once the payment sheet has loaded.
• Integration examples

Reference

fn recurly.ApplePay

Arguments

ApplePay options.callbacks Arguments

ApplePay options.paymentRequest Arguments

Returns

A new recurly.ApplePay instance

fn applePay.ready

Arguments

Returns

Nothing.

events Emits

paymentAuthorized

This event is fired when the customer has authorized the payment presented on the Apple Pay payment sheet.

Payload

token

This event is fired when the customer has completed the Apple Pay payment sheet flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

error

This event is emitted when any error is encountered, whether during setup of the Apple Pay payment sheet, or during payment authorization. It will be useful to display errors to your customer if a problem occurs during the Apple Pay flow.

Payload

Google Pay ™

Use Recurly.js to process Google Pay transactions.

To get started, ensure your Payment Gateway is configured to accept Google Pay transactions.

Invoking The Purchase Flow

Configure a new instance of recurly.GooglePay as follows.

// Handle when the token has been generated to keep the payment sheet in the "Processing"
// state until the onPaymentAuthorized callback has completed
function onPaymentAuthorized(paymentData) {
  const { recurlyToken: token } = paymentData;
  // Submit the token to your server
  console.log('Google Pay succeeded.',
              'Token:', token.id,
              'PaymentData:', paymentData);
}

const googlePay = recurly.GooglePay({
  currency: 'USD',
  country: 'US',
  total: '10',
  googleMerchantId: 'GOOGLE_MERCHANT_ID',
  billingAddressRequired: true,
  callbacks: {
    onPaymentAuthorized,
  },
});

// When the GooglePay instance is ready, attach the Google Pay Button to the DOM
googlePay.on('ready', function (googlePayButton) {
  $('#google-pay-button-container').appendChild(googlePayButton);
});

// Handle errors. These may occur at any point in the Google Pay flow
googlePay.on('error', function (err) {
  // err.code, err.message
  console.error('Google Pay error', err);
});

Google Pay via Braintree

If you’re processing Google Pay transactions with Braintree, you’ll pass a client authorization during instantiation:

const googlePay = recurly.GooglePay({
  currency: 'USD',
  country: 'US',
  total: '10',
  googleMerchantId: 'GOOGLE_MERCHANT_ID',
  billingAddressRequired: true,
  callbacks: {
    onPaymentAuthorized,
  },
  braintree: {
    clientAuthorization: MY_CLIENT_AUTHORIZATION
  }
});

Additional configuration

To provide additional customer data to tokens generated by recurly.GooglePay, you may pass a form reference. recurly.GooglePay will collect customer data from the form just as would occur during credit card tokenization. See Getting a Token for more information on building such a form.

const googlePay = recurly.GooglePay({
  // ...
  form: document.querySelector('#my-payment-form')
});

If you choose to include a Recurly.js payment form, any billing name or address fields entered on that form will be used instead of the address in the user’s Google Pay info; the token request will contain the fields entered on the payment form. If the form is completely empty of name and address inputs, the token request will contain the name and address chosen by the user during the Google Pay flow.

Integration Examples

Reference

fn recurly.GooglePay

Arguments

Google Pay options.callbacks Arguments

Google Pay options.paymentDataRequest Arguments

It is not required to set options.paymentDataRequest.callbackIntents. They are automatically configured based on the options.callbacks and required options.paymentDataRequest counterparts provided.

Returns

A new recurly.GooglePay instance

events Emits

ready

This event is fired when the GooglePay instance has completed initialization and the Customer is ready to Pay.

Payload

paymentAuthorized

This event is fired when the customer has authorized the payment presented on the Apple Pay payment sheet.

Payload

token

This event is fired when the customer has completed the Google Pay payment sheet flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

error

This event is emitted when any error is encountered, whether during setup of the Google Pay payment sheet, or during payment authorization. It will be useful to display errors to your customer if a problem occurs during the Google Pay flow.

Payload

US Bank Accounts

Tokenize your users’ bank account information

Just as with a card form, use the data-recurly attribute to identify fields to Recurly.js. Since Recurly.js does not need to inject fields for bank accounts, all fields may be displayed as inputs on your payment form.

<form>
  <input type="text" data-recurly="routing_number">
  <input type="text" data-recurly="account_number">
  <input type="text" data-recurly="account_number_confirmation">
  <input type="text" data-recurly="account_type">
  <input type="text" data-recurly="name_on_account">
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

US Bank Account inputs

Getting a Token

fn recurly.bankAccount.token

You may call recurly.bankAccount.token with a form element:

recurly.bankAccount.token(document.querySelector('form'), tokenHandler);

Or with an Object:

const billingInfo = {
  // required attributes
  routing_number: '123456780',
  account_number: '111111111',
  account_number_confirmation: '111111111',
  account_type: 'checking',
  name_on_account: 'Pat Smith',

  // optional attributes
  address1: '123 Main St.',
  address2: 'Unit 1',
  city: 'Hope',
  state: 'WA',
  postal_code: '98552',
  country: 'US',
  vat_number: 'SE0000'
};

recurly.bankAccount.token(billingInfo, tokenHandler);

Both methods require using a handler function like this one:

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

This sends bank account billing information to Recurly to store as a token, returning that token id back to you via callback.

International Bank Accounts (IBAN)

Tokenize your users’ International Bank Account (IBAN) information in order to process SEPA transactions.

Similar to configuring a card form, use the data-recurly attribute to identify IBAN specific inputs. Since Recurly.js does not need to inject fields for bank accounts, all fields may be displayed as inputs on your payment form.

<form>
  <input type="text" data-recurly="name_on_account">
  <input type="text" data-recurly="iban">
  <input type="text" data-recurly="country">
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

IBAN inputs

Getting a Token

fn recurly.bankAccount.token

You may call recurly.bankAccount.token with a form element:

recurly.bankAccount.token(document.querySelector('form'), tokenHandler);

Or with an Object:

const ibanBillingInfo = {
  name_on_account: 'Pat Smith',
  iban: 'GB33BUKB20201555555555',
  country: 'GB'
};

recurly.bankAccount.token(ibanBillingInfo, tokenHandler);

Both methods require using a handler function like this one:

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

This sends IBAN information to Recurly to store as a token, returning that token id back to you via callback.

UK Bank Accounts (Bacs)

Tokenize your users’ UK based Bank Account (Bacs) information in order to process Bacs transactions.

Similar to configuring a card form, use the data-recurly attribute to identify Bacs specific inputs. Since Recurly.js does not need to inject fields for bank accounts, all fields may be displayed as inputs on your payment form.

<form>
  <input type="text" data-recurly="sort_code">
  <input type="text" data-recurly="account_number">
  <input type="text" data-recurly="account_number_confirmation">
  <input type="hidden" name="type" value="bacs" data-recurly="type">
  <input type="text" data-recurly="name_on_account">
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

UK Bank Account (Bacs) inputs

Getting a Token

fn recurly.bankAccount.token

You may call recurly.bankAccount.token with a form element:

recurly.bankAccount.token(document.querySelector('form'), tokenHandler);

Or with an Object:

const bacsBillingInfo = {
  name_on_account: 'Charles George',
  account_number: '55779911',
  account_number_confirmation: '55779911',
  sort_code: '200000',
  type: 'bacs'
};

recurly.bankAccount.token(bacsBillingInfo, tokenHandler);

Both methods require using a handler function like this one:

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

This sends Bacs information to Recurly to store as a token, returning that token id back to you via callback.

Arguments (form)

Alternatively, you can call recurly.bankAccount.token with a plain JavaScript object. This allows a more direct interface to the payment flow, eliminating any need to use the DOM.

Arguments (object)

A callback is always required

Callback Arguments

Returns

Nothing.

Australian Bank Accounts (Becs)

Tokenize your users’ Australian based Bank Account (Becs) information in order to process Becs transactions.

Similar to configuring a card form, use the data-recurly attribute to identify Becs specific inputs. Since Recurly.js does not need to inject fields for bank accounts, all fields may be displayed as inputs on your payment form.

<form>
  <input type="text" data-recurly="bsb_code">
  <input type="text" data-recurly="account_number">
  <input type="text" data-recurly="account_number_confirmation">
  <input type="hidden" name="type" value="becs" data-recurly="type">
  <input type="text" data-recurly="name_on_account">
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

Australian Bank Account (Becs) inputs

Getting a Token

fn recurly.bankAccount.token

You may call recurly.bankAccount.token with a form element:

recurly.bankAccount.token(document.querySelector('form'), tokenHandler);

Or with an Object:

const becsBillingInfo = {
  name_on_account: 'Charles George',
  account_number: '55779911',
  account_number_confirmation: '55779911',
  bsb_code: '082902',
  type: 'becs'
};

recurly.bankAccount.token(becsBillingInfo, tokenHandler);

Both methods require using a handler function like this one:

function tokenHandler (err, token) {
  if (err) {
    // handle error using err.code and err.fields
  } else {
    // handle success using token.id
  }
}

This sends Becs information to Recurly to store as a token, returning that token id back to you via callback.

Arguments (form)

Alternatively, you can call recurly.bankAccount.token with a plain JavaScript object. This allows a more direct interface to the payment flow, eliminating any need to use the DOM.

Arguments (object)

A callback is always required

Callback Arguments

Returns

Nothing.

Alternative payment methods

We accept the following alternative payment methods:

• Boleto
• iDEAL
• Sofort
• CashApp

Each of these payment methods share almost the same implementation, with some differences in the initial configuration and some other parameters.

Configuration

To start with any of these payment methods, call recurly.AlternativePaymentMethods.

For example:

const paymentMethod = recurly.AlternativePaymentMethods({
  allowedPaymentMethods: [
    "boleto"
  ],
  blockedPaymentMethods: [],
  containerSelector: "#payment-methods-container",
  amount: 10,
  currency: "BRL",
  countryCode: "BR",
  locale: "en-US",
  channel: "Web",
  adyen: {
    publicKey: 'adyen_public_key',
    env: "test",
    showPayButton: false,
    componentConfig: {}
  },
  returnURL: 'https://return-url.com/success',
});

See reference for details. The various payment methods may be configured as follows:

Boleto

iDEAL

Sofort

CashApp

Rendering the Payment Methods

After configuring your recurly instance, call paymentMethod.start() to show each configured Payment Method(s) within the target element.

Call paymentMethod.destroy() to safely remove the rendered payment UI from the document. This is necessary if you wish to re-render the component.

Generating a token

After filling and confirming the data, paymentMethod.submit() should be called so that the token event can be dispatched. You may optionally provide a specific customer billing address to this call.

paymentMethod.submit();

// You may wish to provide a specific customer billing address when calling `submit`.
paymentMethod.submit({
  billinAddress: {
    first_name: 'Ben',
    last_name: 'du Monde',
    address1: '1313 Main St.',
    // etc.
  }
});

After submit is called, the token will be emitted in the token event.

paymentMethod.on('token', function (token) {
  // token.id
});

Making a purchase

Having the token, a request must be sent to the server, which internally will call the Recurly API to make the purchase. The request must contain the fields from the previously filled in the element container. The response must then be handled to retrieve the action_result and pass it back to the browser. With the action result, paymentMethod.handleAction(action_result) can be called.

const form = document.querySelector('form')

fetch(form.action, {
  method: form.method,
  body: new FormData(form),
})
  .then(response => response.json())
  .then(data => {
    console.log({ data })
    if (data.error) {
      alert(data.error);
    } else if (data.action_result) {
      paymentMethod.handleAction(data.action_result)
    }
  })
  .catch(err => {
    console.error(err);
    notifyErrors([err]);
    });

Reference

fn recurly.AlternativePaymentMethods

Arguments

Returns

A new AlternativePaymentMethods instance

fn alternativePaymentMethods.start

Arguments

None.

Returns

Nothing.

fn alternativePaymentMethods.submit

Arguments

Returns

Nothing.

events Emits

error

This event is emitted when any error is encountered, whether during setup of the payment method flow, or during customer interaction with the payment method interface.

Payload

token

This event is fired when the customer has completed the payment method flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

PayPal

Use Recurly to process PayPal transactions using PayPal Business, PayPal Complete or Braintree.

A PayPal transaction is handled entirely within the PayPal checkout flow in a new window. Your customer will authorize a transaction within PayPal. Recurly will then record the authorization and return a Recurly token to you as it does for other payment methods.

First, place a button on your page specifically for checking out with PayPal.

<button>Checkout with PayPal</button>

Next, create a new recurly.PayPal instance

const paypal = recurly.PayPal({
  display: { displayName: ' My product ' }
});

If you’re processing PayPal transactions with Braintree, you’ll pass a client authorization during instantiation:

const paypal = recurly.PayPal({
  braintree: { clientAuthorization: MY_CLIENT_AUTHORIZATION }
});

If you’re processing PayPal transactions with PayPal Complete, you’ll need to pass a payPalComplete flag:

const paypal = recurly.PayPal({
  payPalComplete: true
});

Your instance must then be setup to handle error scenarios and start the checkout flow.

paypal.on('error', function (err) {
  // err.code
  // err.message
  // [err.cause] if there is an embedded error
});

Next we must bind a listener to a user action on the button and have it trigger the start function on your recurly.PayPal instance. This will open the PayPal checkout flow.

$('#paypal-button').on('click', function () {
  paypal.start();
});

Finally, add a function to receive the token once your customer completes the checkout flow. At this point you will send the token id to your server to be used in the Recurly API to create a billing info for an account.

For PayPal Business and Braintree the token also includes the email and payer_id of the billing agreement. For PayPal Complete the token contains only a id to be used in the Recurly API.

paypal.on('token', function (token) {
  // token.id
  // token.email
  // token.payer_id
});

Reference

fn recurly.PayPal

Arguments

Returns

A new PayPal instance

fn payPal.start

Arguments

Returns

Nothing.

events Emits

error

This event is emitted when any error is encountered, whether during setup of the PayPal flow, or during the checkout process. It will be useful to display errors to your customer if a problem occurs during PayPal checkout.

Payload

cancel

This event is emitted when the customer has canceled the PayPal checkout flow before completion. You may wish to reset parts of your checkout experience if this occurs.

Payload

None.

token

This event is fired when the customer has completed the PayPal checkout flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

Venmo

Use Recurly to process Venmo transactions.

A Venmo transaction is handled entirely within the Venmo checkout flow in a new window. Your customer will authorize a transaction within Venmo. Recurly will then record the authorization and return a Recurly token to you as it does for other payment methods.

You will need to use the token within our API before it expires, and expired tokens cannot be retrieved.

If you wish to make the first and last name fields optional for Venmo tokens through our API, please contact Recurly support to have us enable this feature.

First, place a button on your page specifically for checking out with Venmo.

<button id="venmo-button">Pay with Venmo</button>

Next, create a new recurly.Venmo instance

const venmo = recurly.Venmo({
  display: {
      amount: '100.55',
      currency: 'USD',
      displayName: 'Display Name',
      locale: 'en_US',
    }
});

If you’re processing Venmo transactions with Braintree, you’ll pass a client authorization and a web authentication flag during instantiation:

const venmo = recurly.Venmo({
  braintree: { clientAuthorization: MY_CLIENT_AUTHORIZATION, webAuthentication: true }
});

Braintree strongly recommends enabling the web authentication flag as it offers a better customer experience and improves conversion rates.

Your instance must then be setup to handle error scenarios.

venmo.on('error', function (err) {
  // err.code
  // err.message
  // [err.cause] if there is an embedded error
});

Next we must bind a listener to a user action on the button and have it trigger the start function on your recurly.Venmo instance. This will open the Venmo checkout flow.

$('#venmo-button').on('click', function () {
  venmo.start();
});

The start function must be called within a user-initiated event like ‘click’ or ‘touchend’

Finally, add a function to receive the token once your customer completes the checkout flow. At this point you will send the token id to your server to be used in the Recurly API to create a billing info for an account.

venmo.on('token', function (token) {
  // token.id
});

Reference

fn recurly.Venmo

Arguments

Returns

A new Venmo instance

fn venmo.start

Arguments

Returns

Nothing.

events Emits

error

This event is emitted when any error is encountered, whether during setup of the Venmo flow, or during the checkout process. It will be useful to display errors to your customer if a problem occurs during Venmo checkout.

Payload

cancel

This event is emitted when the customer has canceled the Venmo checkout flow before completion. You may wish to reset parts of your checkout experience if this occurs.

Payload

None.

token

This event is fired when the customer has completed the Venmo checkout flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

Amazon Pay v2

Use Recurly to process Amazon Pay v2 transactions

Recurly recommends the use of the renderButton function to display Amazon’s Amazon Pay button on your page. To do this you will need to place a div` element on your page where you intend to have the button rendered.

<div id="amazon-pay-button">Pay with Amazon Pay</div>

Next, create a new recurly.AmazonPay instance and pass the correct region for your Amazon Pay account. An options object param can be added to pass the account region. If not provided, it will default to ‘us’.

const amazonPay = recurly.AmazonPay();

If you are rendering the Amazon Pay button, add a listener for the ready event and call the renderButton function, passing the id of the element.

amazonPay.on('ready', () => {
  amazonPay.renderButton('amazon-pay-button')
});

Your instance must then be setup to handle error scenarios.

amazonPay.on('error', function (err) {
  // err.code
  // err.message
  // [err.cause] if there is an embedded error
});

Next, a listener must be bound to a user action on the button and have it trigger the attach function on your recurly.AmazonPay instance. This will open the Amazon Pay checkout flow in a new window.

$('#amazon-pay-container').on('click', function () {
  amazonPay.attach();
});

The attach function must be called within a user-initiated event like ‘click’ or ‘touchend’

Finally, add a function to receive the token once your customer completes the checkout flow. At this point you will send the token id to your server to be used in the Recurly API to create a billing info for an account.

amazonPay.on('token', function (token) {
  // token
});

Reference

fn recurly.AmazonPay

Arguments

Returns

A new AmazonPay instance

fn amazonPay.renderButton

Arguments

Returns

A promise.

fn amazonPay.attach

Returns

An error or a token.

events Emits

error

This event is emitted when any error is encountered, whether during setup of the Amazon Pay flow, or during the checkout process. It will be useful to display errors to your customer if a problem occurs during Amazon Pay checkout.

Payload

closed

This event is emitted when the customer has closed the Amazon Pay checkout flow before completion. You may wish to reset parts of your checkout experience if this occurs.

Payload

None.

ready

This event is emitted when the Amazon Pay script has loaded onto your page. This script must load before you can call the renderButton function.

Payload

None.

token

This event is fired when the customer has completed the Amazon Pay checkout flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

Pricing

Recurly automates complicated subscriptions, with many factors influencing the total price at checkout. With this in mind, Recurly.js provides a robust recurly.Pricing.Checkout class designed to make determining the actual checkout costs as simple and flexible as possible.

A Recurly.js checkout pricing instance can be attached to the form we created above, or to any other section of your page meant to display pricing.

Reference

fn recurly.Pricing.Checkout

const checkoutPricing = recurly.Pricing.Checkout();

Creates a CheckoutPricing instance.

No Arguments

Returns

A new CheckoutPricing instance.

fn CheckoutPricing.attach

Given the following example HTML structure

<section id="my-checkout">
  <select data-recurly="plan">
    <option value="basic">Basic</option>
    <option value="notbasic">Not Basic</option>
  </select>
  <input type="text" data-recurly="coupon">
</section>

Use checkoutPricing.attach to bind the <section> to the checkout pricing calculator.

const checkoutPricing = recurly.Pricing.Checkout();

checkoutPricing.attach('#my-checkout');

This is the simplest way to use a CheckoutPricing instance. Simply pass a container element, and the CheckoutPricing instance will use all elements with a valid data-recurly attribute to determine price. When a value changes, the CheckoutPricing instance will automatically update its calculations. This allows your customers to manipulate your checkout form at will, and have your checkout page’s prices update automatically.

Arguments

Returns

Nothing.

HTMLElements

HTMLElements bound to a CheckoutPricing instance may be for either input or output.

Input HTMLElements

Input elements should be user-manipulable elements like input or select. If you want to input a value but not let a customer manipulate it, use an <input type="hidden">.

Subscriptions

CheckoutPricing instances can calculate a checkout containing one or more subscriptions. The table below lists all available input HTMLElement types.

If you would like to calculate multiple subscriptions on a single checkout, group the values for each subscription using the data-recurly-subscription attribute. Simply set them to a unique id to group them. Here’s an example:

<section id="my-checkout">
  Subscription 1
  <select data-recurly="plan" data-recurly-subscription="0">
    <option value="basic">Basic</option>
    <option value="notbasic">Not Basic</option>
  </select>

  Subscription 1 Add-ons
  <span data-recurly="addon_price" data-recurly-subscription="0" data-recurly-addon="my_addon_code_1"></span>
  <input type="text" data-recurly="addon" data-recurly-subscription="0" data-recurly-addon="my_addon_code_1" value="0">

  Subscription 2
  <select data-recurly="plan" data-recurly-subscription="1">
    <option value="basic">Basic</option>
    <option value="notbasic">Not Basic</option>
  </select>
  <input type="hidden" data-recurly="tax_code" data-recurly-subscription="1" value="my_tax_code_0">
</section>

Adjustments

As with subscriptions, CheckoutPricing instances can calculate a checkout containing one or more adjustments.

Using an item code

You may specify an item code from your Recurly catalog. This will automatically retrieve the pricing information for your item.

Example:

<section id="my-checkout">
  My product
  x
  <input type="text"
         data-recurly="adjustment"
         data-recurly-adjustment="my-adjustment-0"
         data-recurly-adjustment-item-code="my-item-code"
         value="0">
</section>

Specifying adjustment properties inline

It’s also possible to specify all adjustment values inline.

Example:

<section id="my-checkout">
  $10 adjustment
  x
  <input type="text"
         data-recurly="adjustment"
         data-recurly-adjustment="my-adjustment-0"
         data-recurly-adjustment-amount="10"
         data-recurly-adjustment-currency="USD"
         data-recurly-adjustment-tax-code="my_tax_code_1"
         data-recurly-adjustment-tax-exempt="false"
         value="0">

  $2.99 adjustment
  <input type="checkbox"
         data-recurly="adjustment"
         data-recurly-adjustment="my-adjustment-1"
         data-recurly-adjustment-amount="2.99"
         data-recurly-adjustment-currency="USD"
         data-recurly-adjustment-tax-code="my_tax_code_2"
         data-recurly-adjustment-tax-exempt="true"
         value="1">
</section>

Other

Output HTMLElements

Output elements should be plain text elements like output, span, or div.

events Emits

CheckoutPricing instances emit events when various values are set or the price changes. See Events for usage.

CheckoutPricing API

A CheckoutPricing instance can be manipulated with a set of direct method calls. This is useful if you would like to set up a complex pricing schema for your customers, or would just like to use a more programmatic method of determining checkout price. Events fire just as they normally would when using CheckoutPricing.attach.

Note that Recurly.js’s DOM binding is one-way. Thus if you use the CheckoutPricing API on a pricing instance already attached to a container, the elements within will not update with your CheckoutPricing API calls. If you would like two-way DOM binding, we suggest using the CheckoutPricing API without attaching it to a container. If using React, consider using our react-recurly library, which contains a custom hook for interacting with the CheckoutPricing API.

The example below demonstrates all the ways that a CheckoutPricing instance can be manipulated directly.

const checkoutPricing = recurly.Pricing.Checkout();

// Add a $10 adjustment
checkoutPricing
  .adjustment({
    id: '0',
    itemCode: 'my-item-code',
    quantity: 1,
  })
  .adjustment({
    id: '1',
    amount: 10.0,
    quantity: 1,
    taxExempt: true,
    taxCode: 'my-tax-code'
  })
  .coupon('my-coupon-code')
  .giftCard('my-gift-card-code')
  .address({
    country: 'US',
    postal_code: '90210'
  })
  .tax({
    tax_code: 'digital',
    vat_number: '',
    amounts: {
      now: '0.99',
      next: '1.99'
    }
  })
  .subscription(recurly.Pricing.Subscription()
    .plan('basic', { quantity: 1 })
    .addon('addon1', { quantity: 2 })
    .catch(function (err) {
      // err.code
    })
    .done()
  )
  .catch(function (err) {
    // err.code
  })
  .done(function (price) {
    // price object as emitted by 'change' event
  });

PricingPromise

Each CheckoutPricing method will return a PricingPromise. This allows you to chain many asynchronous calls together without having to manage a complex series of callbacks.

You don’t need to worry much about the internals of a PricingPromise, as it is designed to stay out of your way and facilitate asynchronous calls for you.

The catch method, as shown in the example, is used to handle error scenarios, such as when an addon cannot be applied to the selected plan.

Example PricingState Object

emitted by the change event

{
  currency: {
    code: 'USD',
    symbol: '$'
  },
  now: {
    adjustments: '20.00',
    discount: '0.00',
    giftCard: '0.00',
    items: [
      {
        addons: '0.00',
        amount: '10.00',
        id: '0',
        plan: '10.00',
        setupFee: '0.00',
        type: 'subscription'
      },
      {
        amount: '20.00',
        id: 'adj-0',
        quantity: '2.00',
        type: 'adjustment',
        unitAmount: '10.00'
      }
    ],
    subscriptions: '10.00',
    subtotal: '30.00',
    taxes: '0.00',
    total: '30.00'
  },
  next: {
    adjustments: '0.00',
    discount: '0.00',
    giftCard: '0.00',
    items: [
      {
        addons: '0.00',
        amount: '10.00',
        id: '0',
        plan: '10.00',
        setupFee: '0.00',
        type: 'subscription'
      }
    ],
    subscriptions: '10.00',
    subtotal: '10.00',
    taxes: '0.00',
    total: '10.00'
  },
  taxes: []
}

3D-Secure

Strong customer authentication for your users.

Recurly.js provides a set of utilities that allow you to support 3-D Secure authentication on your checkout page seamlessly. For more information on 3-D Secure, see our Introduction to Strong Customer Authentication.

Recurly’s support for 3-D Secure utilizes both Recurly.js and our API. For a complete guide to this integration, start with our Strong Customer Authentication (SCA) Integration Guide.

Let’s take a look at an example implementation.

const risk = recurly.Risk();
const threeDSecure = risk.ThreeDSecure({
  actionTokenId: myActionTokenId
});

threeDSecure.on('token', function (token) {
  // handle passing the action result
  // token back to your server

  // token.type => 'three_d_secure_action_result'
  // token.id

  // optionally, you may call threeDSecure.remove() to remove the element
});

threeDSecure.on('error', function (error) {
  // handle error scenarios.

  // error.code
  // error.message

  // optionally, you may call threeDSecure.remove() to remove the element
});

threeDSecure.attach(document.querySelector('#my-auth-container'));

Additional Configuration

Preflights

Some gateways such as World Pay and Cybersouce, have API calls as a part of their device fingerprinting required for 3DS2. By default if you have Cybersource or World Pay configured in Recurly to handle 3DS2 transactions Recurly.js will make this API calls by default to ensure your implementation is properly handling 3DS2 challenges.

Below is an example of disabling this preflight fingerprinting for said gateways above.

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      preflightDeviceDataCollector: false,
    }
  }
  // ..
});

You may want to use the config above, if you are handling a transaction you are confident will not be challenged. It is important to note, that if the issuing bank or gateway does request a challenge, you will not be able to handle the challenge if this configuration is in use.

Proactive 3D-Secure

You can take your customers through Strong Customer Authentication before their initial transaction to store their card details by enabling Proactive 3D-Secure. This feature is currently available for the following gateways:

• Braintree

Below is an example for enabling this feature.

recurly.configure({
  // ...
  risk: {
    threeDSecure: {
      proactive: {
        enabled: true,
        gatewayCode: "abc123",
        amount: 0.00
      },
    }
  }
  // ..
});

With proactive 3D-Secure enabled, you will receive a three_d_secure_proactive_action_token when you tokenize your billing information. This value can be passed in as an actionTokenId to the threeDSecure class to enable the Strong Customer Authentication flow. Refer to the 3-D Secure Example Implementation for more details.

Reference

fn recurly.Risk

Arguments

None.

Returns

A new Risk instance

fn recurly.ThreeDSecure

Arguments

Returns

A new ThreeDSecure instance.

fn threeDSecure.attach

Arguments

Returns

Nothing

events Emits

token

This event is fired when your customer has completed the 3-D Secure flow. Recurly has received the authentication details, and generated this token to be used in our API.

Signature

error

This event is emitted when any error is encountered, whether during setup of the 3-D Secure flow, or during authentication. It will be useful to display errors to your customer if a problem occurs during the 3-D Secure flow.

Signature

Fraud

Recurly.js provides a fraud protection suite with support for our Fraud Management toolkit, Kount integration, and Braintree gateway integration.

With fraud protection enabled, tokens created with Recurly.js will include device data we use to analyze fraud risk and flag subsequent transactions accordingly. Configuration is simple.

Configuring Fraud Protection

Once you have enabled fraud protection on your site, modify your Recurly.js configuration call according to your fraud protection setup.

Recurly Fraud Management & Kount Integration

If you are using Recurly Fraud Management or Kount, Recurly.js will handle all device data collection when configured as follows. Recurly Fraud Managment uses Kount’s device data collector under the hood. The form parameter should be your checkout form.

recurly.configure({
  // ...
  fraud: {
    kount: {
      dataCollector: true,
      form: document.querySelector('.my-checkout-form-selector')
    }
  }
  // ..
});

This will enable device data collection and automatically apply it to your tokens.

When using a Kount Enterprise Fraud Management plan you can provide your own User Defined Fields with the udf option.

recurly.configure({
  // ...
  fraud: {
    kount: {
      dataCollector: true,
      form: document.querySelector('.my-checkout-form-selector'),
      udf: {
        FREQUENCY: 107,
        COUPON: 'BUY11',
      }
    }
  }
  // ..
});

In order to add or remove User Defined Fields after configuring Recurly, you can assign a reference to an object that you can modify later.

Braintree Gateway Fraud Integration

First, you will need to collect device data using the Braintree JavaScript client. This is required by Braintree.

Once you have obtained deviceData, you’ll provide it to recurly.configure as follows. Note that we’re passing the complete deviceData string as exposed by the Braintree library.

// Collect device data using the Braintree client
// ...

const { deviceData } = braintreeInstance;

recurly.configure({
  // ...
  fraud: {
    braintree: { deviceData }
  }
  // ...
});

This will apply Braintree fraud data to your tokens generated by Recurly.js. Transactions created with those tokens will pass the fraud data to Braintree for fraud analysis.

Validation

Recurly.js bundles a few helpful methods for validating payment information prior to processing. These methods are used when generating tokens, but you can also use them to enhance your form validations and checkout flow.

Reference

recurly.bankAccount.bankInfo

Retrieves bank info based from a given routing number.

recurly.bankAccount.bankInfo({ routingNumber: '123456780' }, function (err, bankInfo) {
  if (err) {
    // err.code, err.message
  } else {
    // bankInfo.bank_name
  }
});

Arguments

Callback signature

Errors

Errors are encapsulated by a RecurlyError, which contains a few standard properties to help you diagnose error cases and inform your customers accordingly.

Errors will be thrown if the exception will prevent proper execution. If an error can be recovered, it will be passed to the proper error handling event listener, callback, or PricingPromise handler for you to inspect.

Best Practices

The message property contains diagnostic information intended to help you diagnose problems with the form, and we do not recommend displaying its contents to your customers.

To provide the best customer experience, we recommend that you provide your own error text to be displayed, based on the error code you receive.

Error Codes

Configuration

Tokenization

Pricing

Apple Pay

PayPal

3-D Secure

Example RecurlyError object

{
  name: 'validation',
  code: 'validation',
  message: 'There was an error validating your request.',
  fields: [
    'number',
    'year'
  ]
}

Examples

Integration examples

We’ve prepared a full suite of example integrations for Ruby, Node.js, Python, and PHP using popular web frameworks for each language. These examples demonstrate the simplest method of integration, with a no-frills UI.

Code on GitHub

React Support

Recurly maintains a React component library to simplify use of Recurly.js for your React applications.

For details on getting started, see our documentation on GitHub.

TypeScript Support

TypeScript types for Recurly.js can be found on DefinitelyTyped

To install with npm, run npm install --save-dev @types/recurly__recurly-js in your project’s root directory.

Upgrading

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.

Support

Recurly.js supports Chrome, Firefox, Safari, Edge, iOS, and Android.

We’re also here to lend a hand on any Recurly.js integration questions! You can get help from us in a handful of ways:

• Take a look at the code on GitHub. We welcome bug reports through Issues and contributions through Pull Requests.

For other Recurly related questions, please contact support@recurly.com for help with your account or other general questions.