To begin, 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">

Note: Including recurly.css is optional but recommended as it provides helpful default styles for Recurly Elements during setup.

Prerequisites & limitations

• You must have a valid Recurly account with API access.
• Basic familiarity with HTML, JavaScript, and RESTful APIs.
• Using Recurly.js is optional but recommended for enhanced security and reduced PCI scope.

How it works

Recurly.js streamlines your checkout by securely capturing customer payment information. When a customer submits your payment form, Recurly.js encrypts their payment data and stores it on our servers, returning an authorization key (or token). With this token, you can complete the subscription process using our API—without ever directly handling sensitive payment data. This reduces your PCI compliance requirements significantly.

Self-hosting Recurly.js

We highly recommend using the Recurly-hosted version of Recurly.js. This version is updated to maintain compatibility with Recurly’s system updates. Locally hosted copies may encounter integration issues or service interruptions.

Configure

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

recurly.configure('sc-ABCDEFGHI123456789');

Use Your Site's Public Key: Replace sc-ABCDEFGHI123456789 with your own public key.

Note:recurly.configure accepts additional options. For further details, refer to the source.

Build a payment form with elements

Design an HTML form to collect customer payment details. Use the data-recurly attribute to identify non-card billing fields. Recurly.js builds the card fields using Elements.

<form id="my-form">
  <input type="text" data-recurly="first_name" placeholder="First Name">
  <input type="text" data-recurly="last_name" placeholder="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 type="submit">Submit</button>
</form>

The card element

The Card Element is the simplest way to accept customer card data. Recurly.js injects a single, responsive field for the card number, expiry, and CVV. This field includes helpful UX enhancements for smooth entry on any device.

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

Other elements

Recurly.js also offers individual Elements for separate card fields if a combined field doesn't fit your design needs. See the Elements documentation for further details.

Billing fields

Below is a table of potential billing fields supported by Recurly.js. Some fields may be required depending on your billing address requirements.