Getting started with the GoCardless Ruby gem
By GoCardlessJan 2012 3 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 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! 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
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.
GoCardless makes it easy to collect recurring payments