So you want to implement the latest and greatest in recurring billing functionality and ease into your app, but you're not sure where to start. Today we're going to create a quick and easy implementation using Recurly.js and our API! We'll create an account with billing info, and a subscription, for some recurring billing goodness. We love Recurly.js and are sure you will too, knowing that it will:

  • Handle all field validation and sanitization

  • Create a token that contains all the form billing information

  • Alleviate you of any PCI compliance concerns

Behind the scenes

Recurly.js is all about tokenization. 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 powerful 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.

Recurly.js + Recurly API

Let's take a look at what an implementation looks like! Today we're going to get the example from our Recurly.js Examples repository up and running. Let's start out by cloning the repo, then navigating to the `api/ruby` directory. After you're in the proper place, run `bundle` to install the necessary dependencies. Next in `app.rb` let's replace the `RECURLY_API_KEY` with our private_key and `SUBDOMAIN` with your subdomain. Next, navigate to `public/minimal/index.html` and replace `PUBLIC_KEY` with your public_key. Finally, let's update the `plan` value on line 26 of `app.rb` with an existing plan on your account.

Once you have the app configured with your keys, subdomain, and plan you're all set to create an account, subscription, and billing info! Navigate to localhost:9001 and click 'Minimal billing information' and plug in a test credit card and the other necessary details. Click 'Submit' and you're done!

You can now check out your account page page and you'll see the new account there!

Breakdown

Let's break down what's happening in our html form, and our ruby file. In `index.html` we see the form has several `data-recurly` attributes. These are for sending sensitive information over to Recurly without hitting your server.

Form HTML code snippet

With Recurly.js, the credit card number, month, year, etc. are passed to Recurly's servers for temporary storage. Recurly's servers send back a token id, which is inserted into the hidden field. Once that token is inserted, the form is POSTed to the route `/api/subscriptions/new` which is what our `app.rb` file is waiting for. Now let's look at how we handle and process the token we just received.

Recurly plan code snippet

You can see in the above example that we use our Recurly client library to create a new subscription with a plan code. We also create an account with an account code, and the billing info from our form. If all goes well, we redirect to a `SUCCESS_URL` of our choosing. If all fails, we'll rescue the call and handle the exception with a redirect to our `ERROR_URL`.

Best Practices

It’s important to note that you'll want to keep your `RECURLY_API_KEY` as an environmental variable since it's sensitive information you don't want to commit with git.

The input attributes in the example above do not include name attributes. This is very important, as it tells the browser not to include the field in the final form submission. To avoid sending sensitive card information to your servers, be sure not to include the name attribute on sensitive fields like number and cvv.

Recurly.js and our API are powerful tools, with only a fraction of that power being shown here. Feel free to drop into our IRC channel #recurly on Freenode, or reach out to support@recurly.com if you have any questions!