Skip to content
Go to GoCardless homepage
LoginSign up

Getting started with the GoCardless Ruby gem

By GoCardlessJan 20123 min read

This post relates to the Legacy GoCardless API. If you're starting a new integration, you'll need to use the new GoCardless API - for help getting started, check out our guide.

In this post, we’re going to learn how to implement recurring payments with GoCardless into a Ruby-powered website in just a few minutes. We’ll be using the GoCardless Ruby gem. You can find the full documentation for our Ruby library here and the source code is on Github.

The code below also powers our example site at

Before we start, check out our overview of getting started with GoCardless and follow the instructions for signing up for a sandbox account and getting your authentication details from the Developer panel

  • you’ll need them later.

We’re going to use Sinatra, a lightweight Ruby framework, for this demo. Nathan Humburt has written a simple post on getting Sinatra running on Heroku if you need a refresher.

First of all, let’s initialize our GoCardless client:

# In app.rb, or your main app file
# We're using the sandbox environment for testing

GoCardless.environment = :sandbox
GoCardless.account_details = {
  :app_id => 'XXXXXXX',
  :app_secret => 'XXXXXXX',
  :token => 'XXXXXXX,
# In app.rb, or your main app file
# We're using the sandbox environment for testing

GoCardless.environment = :sandbox
GoCardless.account_details = {
  :app_id => 'XXXXXXX',
  :app_secret => 'XXXXXXX',
  :token => 'XXXXXXX,

We’ll then fetch some information about existing subscribers from the API;

# Define the index path in app.rb

get '/' do
  @subscriptions = GoCardless.client.merchant.subscriptions
  haml :index

Now we need a view to display that information, and a form for creating new subscriptions:

# views/index.haml

%h2= "We've had #{@subscriptions.length} signups so far!"

%form{:action => url('/subscribe'), :method => 'POST'}
  %h2 Enter your email to subscribe
  %input{:type=>"text", :name => "email"}

Next, we need to handle the post request sent from the form submission. It’s extremely important that you don’t allow user input for sensitive values - particularly the amount! Intervallength and intervalunit tells you how often the user will be billed - in this case, every 2 months.

You can provide a more information about the user, including their firstname and lastname. This is used to pre-populate the checkout form, and is particularly useful if the person has already filled in the details as part of your website’s signup process. See the docs for more details

# Implement the subscribe path in app.rb

post '/subscribe' do
  # We'll be billing everyone £10 per month
  # for a premium subscription
  url_params = {
    :amount => 10,
    :interval_unit => "month",
    :interval_length => 2,
    :name => "Premium Subscription",
    # Set the user email from the submitted value
    :user => {
      :email => params["email"]

  url = GoCardless.new_subscription_url(url_params) redirect to url

At this point, the user will be redirected to GoCardless to enter bank details and create a new subscription. After this is complete, he will be redirected back to the path you’ve set as the “Redirect URL” in the Developer Panel. You can use localhost:9292/confirm if you’re developing on a local machine.

Every 2 months from now on, GoCardless will generate a new payment for £10 and debit it directly from the user’s bank account. The first payment will be taken immediately.

Finally, you’ll need to confirm that your server has received this new subscription before it’s activated. We can do this with a new route in app.rb

# Implement the confirm path in app.rb

get '/confirm' do
  begin GoCardless.confirm_resource
    params "New subscription created!"
  rescue GoCardless::ApiError => e
    @error = e
    "Could not confirm new subscription. Details: #{e}"

You’re all done! The great thing about this simple solution is that you don’t need to store any user data.

GoCardless makes it easy to collect recurring payments

Sign upContact sales

Interested in automating the way you get paid? GoCardless can help

Contact sales

Contact Us


Contact sales

+44 20 8338 9539


Request support

+44 20 8338 9540

Seen 'GoCardless Ltd' on your bank statement? Learn more

GoCardless Ltd., Sutton Yard, 65 Goswell Road, London, EC1V 7EN, United Kingdom

GoCardless (company registration number 07495895) is authorised by the Financial Conduct Authority under the Payment Services Regulations 2017, registration number 597190, for the provision of payment services. GoCardless SAS (23-25 Avenue Mac-Mahon, Paris, 75017, France), an affiliate of GoCardless Ltd (company registration number 834 422 180, R.C.S. PARIS), is authorised by the ACPR (French Prudential Supervision and Resolution Authority), Bank Code (CIB) 17118, for the provision of payment services.