Getting started (4.10.3)

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 payment fields.

Self-hosting Recurly.js

The Recurly-hosted version of recurly.js is designed and updated to maintain compatibility
with system update deployments that take place from time-to-time. Locally hosted versions of recurly.js run the risk of encountering issues with system interaction and incompatibility which may result in avoidable service interruptions on your client page. It is for this reason, we highly recommend against and do not support locally hosted copies of recurly.js.

Framework support

Due to the necessity of gathering customer payment data within iframe elements, and the nature of
reactive framework re-rendering requirements, Recurly does not at this time provide native support for reactive frameworks like React and Angular.

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

Use your site's public key

Be sure to replace sc-ABCDEFGHI123456789 with your own public key.

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

Build a card form

Build a form however you like. Use the data-recurly attribute to identify input
field targets to Recurly.js. For this, we recommend using simple div elements.

There are two ways to display card fields to your customers: a combined card field, and individual card fields.

Combined card field

This is the simplest and most streamlined way to accept customer card date. Recurly will inject
a single field that will accept all card data. This field is responsive to various device widths and includes helpful UX enhancements to make card entry as smooth as possible.

<form id="recurly-js-sample-combined-card-form">
  <div data-recurly="card"></div>
</form>

<form>
  <input type="text" data-recurly="first_name">
  <input type="text" data-recurly="last_name">
  <div data-recurly="card"></div>
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

Individual card fields

If you would like to display card fields separately from each other. This is helpful
when the combined field does not fit your design needs.

<form>
  <input type="text" data-recurly="first_name">
  <input type="text" data-recurly="last_name">
  <div data-recurly="number"></div>
  <div data-recurly="month"></div>
  <div data-recurly="year"></div>
  <div data-recurly="cvv"></div>
  <input type="hidden" name="recurly-token" data-recurly="token">
  <button>submit</button>
</form>

To collect card payment information from your customers, you'll create a form similar to this one.
Recurly.js uses the data-recurly attributes on the input tags to gather customer information before sending it to our servers.

Note: In order for recurly.js to inject the card payment hosted fields into your form, the target elements must be present in the document at the time you make the recurly.configure call.

Note that card data is not present in the form but merely given a placeholder element. This is because Recurly.js must inject those fields onto the page within iframes to ensure strict security of customer card data.

This particular form contains the minimum required input fields, and the table below documents all possible input fields.

Card fields

Depending on how you've configured your billing address requirements, some of the following fields may be required.

Billing address fields