Recurly.js Integration Guide

Note—Recurly.js is now at version 2.1. Please review our upgrading guide to see what you'll need to change. View documentation for Recurly.js verions < v2.1 here.

Code Requirements

Using Recurly.js requires code that operates on the server side, as well as in the browser. In the rest of this document, code samples in Ruby, PHP, and Python all reference functionality provided by Recurly's client libraries. Please refer to the appropriate section of our documentation for obtaining and including these libraries in your source code:

The Recurly.js library itself should be included in the <head> section of your generated HTML pages. Recurly provides both normal, and minified versions of the library, named recurly.js, and recurly.min.js, respectively.

jQuery

Recurly.js requires jQuery. jQuery must be included before Recurly.js in your document.

Example

<!DOCTYPE html> 
<html> 
  <head>
    <title>RecurlyJS Example</title>
    <link rel="stylesheet" href="/css/themes/default/recurly.css">
    <script src="jquery-1.7.1.js"></script>
    <script src="recurly.js"></script>
  </head>
  <!-- ... -->

Setting Your Private Key

Before using any of the server side Recurly.js functions, you must set your private key.

Recurly_js::$privateKey = 'abcdef01234567890abcdef01234567890';

Recurly.js.private_key = 'abcdef01234567890abcdef01234567890'

recurly.js.PRIVATE_KEY = 'abcdef01234567890abcdef01234567890'

Understanding Protected Parameters

When a user submits any of the Recurly.js forms, the data is transmitted directly to Recurly's servers. While the majority of the data is entered by the user into the form, some of it needs to be specified ahead of time when your server generates the page that contains the form.

How are the parameters secured?

Your server and Recurly's make use of a shared secret, or private key, to generate an HMAC-SHA1 signature based on the protected parameters. This signature is passed into the JavaScript form building functions, and transmitted along with the other form data.

If a would be attacker alters any of the protected parameters, the signature will no longer match, and Recurly will reject the request.

Which Languages are Supported?

Recurly provides code to generate the signatures in our PHP, Ruby, and Python client libraries. If you're not using one of those languages, the signatures page fully describes how to generate a valid signature in your language of choice.

Creating the Signature

In all of our client libraries, only one method is required to sign parameters, regardless of which type of form you are using. Here are some examples for common scenarios:

When inserting the signature into html, make sure that the raw signature is inserted and that the signature is not escaped. Many template engines do this by default so you may need to override that functionality.

Signing a New Subscription

$signature = Recurly_js::sign(
  array('subscription' => array('plan_code' => 'gold_plan'))
);

signature = Recurly.js.sign :subscription => { :plan_code => 'gold_plan' }

signature = recurly.js.sign({'subscription': {'plan_code': 'gold_plan'}})

Signing a Billing Info Update

$signature = Recurly_js::sign(
  array('account' => array('account_code' => 'user123'))
);

Recurly.js.sign :account => { :account_code => 'user123' }

signature = recurly.js.sign({'account': {'account_code': 'user123'}})

Signing a One Time Transaction

$signature = Recurly_js::sign(
  array('transaction' => array('amount_in_cents' => 1999, 'currency' => 'USD'))
);

signature = Recurly.js.sign(
  :transaction => { :amount_in_cents => 19_99, :currency => 'USD' }
)

signature = recurly.js.sign({
  'transaction': {'amount_in_cents': 1999, 'currency': 'USD'}
})

Handling Results

Once a Recurly.js form has been submitted, and Recurly has successfully processed it, a token will be POSTed to the URL you specified in the successURL parameter of the form building function.

The token will be posted as a parameter named recurly_token. This token is used to retrieve the result of the transaction from Recurly via the API. This will be either a subscription, billing_info, or invoice object, depending on the type of form that was used.

Example

$result = Recurly_js::fetch($_POST['recurly_token']);

result = Recurly.js.fetch params[:recurly_token]

result = recurly.js.fetch(params['recurly_token'])

Now you can make the appropriate changes in your own system, and present a results page to the customer.

(Push notifications are another mechanism that can be used to keep your system in sync with the results of Recurly.js interactions.)

Ruby on Rails users: CSRF protection should be turned off for successURL handler pages, as recent Rails revisions will reset session data on a missing CSRF token.

Handling Results via Javascript

(This is an advanced use case, and can be skipped over)

While you will still need to process the response data from Recurly on your server, you may choose to have the result token passed to a Javascript function you supply with the options to the form building call (i.e. buildSubscriptionForm, buildBillingInfoUpdateForm, or buildTransactionForm.)

This function, passed in via the successHandler option, will receive the token as a single argument. The function would send the results back to your server via an AJAX call, the server would handle them, and then respond to the AJAX request as needed.

Note, you must not set the successURL option when calling the form building functions, otherwise the user will be redirected as usual immediately after your supplied Javascript function is called.

Please be advised, this is an advanced use case for which Recurly can only provide limited support.

Global Settings (Javascript)

Before any of the forms can be built, you must specify some general settings. At a minimum, you must specify your Recurly subdomain, and currency.

Example

Recurly.config({
  subdomain: 'mycompany'
, currency: 'USD' // GBP | CAD | EUR, etc...
});

Building Forms

Recurly.js builds forms by injecting them into an empty DOM element you place in your page, i.e.

<div id="recurly-form"></div>

Each type of form available in Recurly.js has a specific Javascript function used to generate it. These are:

buildSubscriptionForm(options)
buildBillingInfoUpdateForm(options)
buildTransactionForm(options)

You must pass each of these functions the name of the target HTML element the form will be injected into, and the signature you created on the server side. Some of the forms may require a few additional parameters, as noted below. Additionally, all of the forms support a variety of customizations. These are fully documented on the Reference page.

New Subscription Example

buildSubscriptionForm requires that you specify the plan code that will be subscribed to.

Recurly.buildSubscriptionForm({
  target: '#subscribe'
, planCode: 'myplancode'
, successURL: 'http://myserver.com/subscriptions/confirmation.php'
, signature: '<?=$signature?>'
});

Billing Info Update Example

Recurly.buildBillingInfoUpdateForm({
  target: '#billingInfoForm'
, successURL: 'http://myserver.com/billing_updated_confirmation.php'
, signature: '<?=$signature?>'
});

One Time Transaction Example

Recurly.buildTransactionForm({
  target: '#transactionForm'
, successURL: 'http://myserver.com/purchase/thank_you.php'
, signature: '<?=$signature?>'
});

Currency

If you are taking advantage of Recurly's multi-currency support, please be advised that Recurly.js can only work in one currency per page. If you wish to accept multiple currencies, you should have the user make their selection on a separate, preceeding page.

Additionally, for new subscriptions—the plan you specify must be configured within Recurly for the currency you pass to Recurly.config()

Pre-Populating Form Data

All of the form building functions provide options to pre-populate the form fields. Below is an example for building a subscription form which makes use of all of the available fields. Note that some of the fields do not apply to all of the forms. For instance, coupon codes only apply to subscriptions, and so will have no effect if used with buildTransactionForm.

Example

Recurly.buildSubscriptionForm({
  account: {
    firstName: ''
  , lastName: ''
  , email: ''
  , phone: ''
  , companyName: ''
  }
, billingInfo: {
    firstName: ''
  , lastName: ''
  , address1: ''
  , address2: ''
  , country: ''
  , city: ''
  , state: ''
  , zip: ''
  , vatNumber: ''
  // Following 2 should be reserved for testing purposes only
  , cardNumber: ''
  , CVV: '123'
  }
, subscription: {
    couponCode: 'bigdiscount'
  }
// additional parameters omitted
})

Theming/Customization

A theme is just a recurly.css file and images in the themes/ directory. Recurly supplies only one theme, "default", but creating your own is not that hard. We use stylus, but you don't have to.

There are two approaches to customizing:

Use a stock theme, and separate stylesheet to override individual styles. This approach makes updating easier later if you only want to tweak a few things.
Fork the repository and modify an existing theme, or create a new theme. Note: The stylus source for the "default" theme has many options as variables at the top of the file.

Recurly.js Integration Guide

Basics

Server Side (Protected) Parameters

Handling Results

Building the Form (Browser)

Other Topics

Code Requirements

jQuery

Example

Setting Your Private Key

Understanding Protected Parameters

How are the parameters secured?

Which Languages are Supported?

Creating the Signature

Signing a New Subscription

Signing a Billing Info Update

Signing a One Time Transaction

Handling Results

Example

Handling Results via Javascript

Global Settings (Javascript)

Example

Building Forms

New Subscription Example

Billing Info Update Example

One Time Transaction Example

Currency

Pre-Populating Form Data

Example

Theming/Customization