Getting started with the GoCardless Ruby gem

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 gocardless.com/example-checkout.

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,
  manage_merchant:MERCHANT_ID'
}

# 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,
  manage_merchant:MERCHANT_ID'
}

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
end

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"}
  %input{:type=>"submit"}

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! Interval_length and interval_unit 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 first_name and last_name. 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
end

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}"
  end
end

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