Recurly.js: The Basics

July 25, 2013 — Accepting Recurring Payments from A to Z with Recurly.js Series

One of my goals with WiseCash is to bring you more freedom of choice and encourage you to build income sources.

Learning how to accept online payments will help you out build your own SaaS product.

So I’m starting this Recurly.js series, both to share what I learned while building WiseCash and to build linkable content to promote our nice bootstrapped service.

Why Recurly?

My criteria for picking a payment solution for WiseCash were:

I reviewed a number of billing providers and Recurly came first based on those criteria.

Picking a gateway

Recurly includes a gateway out of the box if you are US-based.

Since we’re EU-based, I opened a gateway access / merchant account bundle at WireCard. I had to send quite a bit of papers, but the people I exchanged with were very nice and super helpful.

I pay a small monthly fee to WireCard — in turn they acquire USD transactions from Visa, MasterCard and Amex for me, which get transferred to our company bank account weekly.

Why Recurly.js?

Recurly offers three ways of integrating payments in your app. Here’s a quick comparison to explain you why I ended up using Recurly.js.

Hosted integration pages

The simplest way to create monthly subscriptions is to use the hosted integration pages.

I quickly dismissed that option since I wanted a more integrated sign-up workflow as well as more control over account cancellation. That said it’s a great option to get started for less technical users.

Full API

This is the full-fledged mode.

While I use this API for some operations, I preferred to avoid using it for subscription creation, since it would have required full credit-card data to go through my servers (albeit just temporarily).

This would have required going through the PCI SAQ C questionnaire.


Recurly.js lets you embed a CSS-customizable JavaScript form that posts directly to the Recurly servers, without having full credit-card data going through your servers. The form is numerically signed with a private key to avoid tampering.

Recurly mentions that using Recurly.js qualifies you for the PCI SAQ A, which is only 13 questions long (much shorter than the SAQ C).

You still need to take care about avoiding JavaScript injection issues.

This solution was on a sweet spot for me, so this is what I ended up using.

How the subscription creation form works

I’ll share Ruby and JavaScript code in a coming episode of this series. Until then, here’s a first overview of the subscription creation process:

Recurly.js Overview

So what is happening here?

First you configure your app with the “API key” (used for API calls) and the “private JavaScript key” (used to numerically sign the form), using for instance the Recurly ruby gem.

Then you create a signature based on key information that should not be tampered (like the “account code” uniquely identifying the account you are creating a subscription for, the trial end date, and the plan code).

Once this is done, you render a web page which includes Recurly.js and use their buildSubscriptionForm call.

Once loaded, the form makes a JSONP call to determine the visitor country and adjust VAT accordingly, and issues another call to retrieve up-to-date plan data (pricing etc).

If the user enters a coupon code, a JSONP call is made again to verify and apply it.

The user then enters his data (including VAT number, which is verified if provided).

After a local validation, the form securely submits the information to Recurly’s servers, and a “token” is returned and posted back to a callback page you specified, by the form itself.

Your callback page should then use the “token” to make an API call to Recurly, verify the subscription status, and update your local database accordingly.

That’s it, mostly!

What’s next?

In the next article of this series, I’ll outline the different ways you can handle your sign-up workflow with Recurly.js.

Thibaut Barrère (WiseCash founder)


Thanks for sharing this article around!

Still managing your business cash-flow in a spreadsheet?
That must hurt, right?

WiseCash helps you rule your finances with an iron fist,
without having to labor a spreadsheet!

comments powered by Disqus