Recurly

Recurly.js v2 deprecated

Note: Recurly.js v2 has been deprecated in favor of v3.

While we will continue to support v2 for any important future fixes, all new feature development will occur in v3.0.0+, and we highly recommend customers migrate to the new version.

Please refer to the Recurly.js v3 documentation for more information.

Recurly.js is a Javascript library designed to be easily embedded and customized to match your website. The library performs in-line validation, real-time total calculations, and gracefully handles errors. Your customer stays on your website while their billing information is securely sent to Recurly for approval. Because the cardholder data is sent directly to Recurly, your PCI compliance scope is dramatically reduced.

How it Works

Your Server Generates a Page to Contain the Form

Recurly.js does most of its work in the user's browser, dynamically building a form tailored to the type of transaction you need (such as processing a new subscription, or a one-time transaction).

To do this, it will need to be configured with some tamper proof data from your server.

Ruby One-Time Transaction Example

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

This signature contains your customer's account code, and some information about the transaction, that cannot be modified. It will be passed in to the JavaScript code which calls Recurly.js to build the form.

Form Creation Example, JavaScript + ERB (Embedded Ruby)

<script>
  Recurly.buildTransactionForm({
    target: '#recurly-form',
    successURL: 'http://myserver.com/transactions/confirm',
    signature: '<%= signature %>'
  });
</script>

The target option is specifying an HTML element in your web page that will be replaced with the new form.

Your Customer Fills Out and Submits the Form

Now your customer fills out the form, enters their credit card data, and hits Submit. If all of the data validates, it will be sent directly to Recurly where the transaction is run. If it fails, an appropriate error message will be displayed in their browser, so they can try again.

If the transaction succeeds, we move on to the last part of the process, where...

Your Server Processes the Results

Finally, a token will be HTTP POSTed to the URL on your server that was specified in the successURL option of the form building function. The token is used to fetch the resulting API object from Recurly. For more information on this step, see the Handling Results section of the Integration Guide.

Simply update your own database with the results, generate a "success" page for your customer, and you're done!

Ready to Get Started?