in Engineering

Building our new developer experience: Part 1

Our API is at the heart of everything we do. Not only does it allow developers to build powerful Direct Debit solutions, but it also powers the GoCardless Dashboard along with our integrations with partners like Xero, Teamup and Zuora.

As engineers, we know firsthand the importance of having great resources at your disposal when you’re getting started with an API. So back in September we kicked off a major project to revamp our developer onboarding experience. We wanted to build something we could be really proud of and which would also delight our customers.

In this blog post, the first of a series of two, we’ll take you through the journey of building our new developer site from idea to delivery.

Where we started

From the earliest days of GoCardless, developers have been a major focus for us. We’ve invested a lot of time in building an intuitive and powerful API with great tooling.

When we were building the current API in 2014 we learnt lots of lessons from our original legacy API from 2011 - we sought to provide consistency and predictability, implemented versioning from the get-go and made pagination the default.

One of the biggest problems with many APIs is that the documentation and libraries get out of date all too easily. When you’re moving as fast as we do and trying to continuously add value for customers, you’ll always be making improvements to to your API. Making regular changes every few weeks means that your developer resources quickly become stale. Typically, this means lots of manual work, painstakingly and manually updating documentation and libraries when the API itself changes. For instance, when we add a new optional attribute when creating a payment via the API, within minutes it’s mentioned in the documentation and supported within our API libraries.

To reduce friction in making changes to the API and help developers stay up to date, we’ve automated this process as much as possible. We describe our API in the form of a JSON Schema, embedding all the different resources, attributes and endpoints available. We then use an internal tool to apply this schema to templates we’ve built for our documentation and each of our client libraries.

Every time either the schema or one of these templates changes, we re-generate the resulting source code and automatically deploy it to our website or push it to GitHub.

This has provided a great base to work from for building documentation that we could be proud of and delivering what we saw as the bare minimum: up to date and complete documentation. We heard from satisfied users every week who found our docs great to work with. But we were aware that we didn’t have the right experience for people entirely new to the API - beyond a blog post, there were no code samples or step-by-step walkthroughs to help developers hit the ground running.

Working out what to build

With a basic understanding of the problem, we needed to decide what to build. To help us make the right choices, we defined three goals for the project:

  1. Help developers see the value in our API and reach that “aha!” moment as soon as possible
  2. Make it easy and seamless for people to transition from our sandbox environment to a live integration when they’ve finished building
  3. Identify the right developer leads and pass them to the sales team, so they can reach out and offer help at the right time

With the APIs we know and love, we can all remember the time when we first grasped their power. But as things stood, we were doing almost nothing to bring users to that point - after signing up to our sandbox environment, developers were just pointed to the docs and left to their own devices. We knew we could do better.

With that in mind, we started researching onboarding flows for other APIs, taking a look at Intercom, Stripe and Clearbit, amongst others, seeking to learn from what they did and didn't do well. For example, Clearbit did a great job with their “quick start” documentation, but it was frustrating that the flow didn’t remember your choice of what platform you wanted to integrate with.

I also spent time with our Sales and API Support teams internally - they spend all of their time talking directly with customers, so they could give us great insights into what our customers found most confusing and unintuitive. Both teams flagged up demand for code samples, which we weren’t providing beyond the readme files of our libraries.

Talking to the sales team made us all the more conscious of the importance of great documentation in the sales cycle - when large prospective users of our API are weighing up options for managing their Direct Debit payments, they’ll tend to get their developers to have a look.

The API Support team were able to give us great access to customers who had recently finished building integrations. We reached out to them and got direct feedback on what they found hardest in working with our API and what was least clear.

Considering our own internal feedback, chatting to real users of the API and our own intuitions as developers, it seemed clear that the biggest source of value would be adding a dedicated “getting started” guide for developers new to our API, supported by in-product messaging to guide them to and through it.

Delivering the new

The first improvement we made was to add code samples to our reference docs. We did think about automating this, but decided it would make it harder to provide contextually relevant code examples.

These examples made a big difference in terms of making our libraries easier to use but they didn’t do much to help customers understand the underlying concepts behind the API or point them to what they should be doing first. For this, we decided to write a “getting started” guide, separate from the reference documentation. Trying to merge the two together didn't make sense - they’re very different kinds of content: for example, a guide is naturally read start-to-finish whereas reference documentation is something you dip into as required.

First, we had to decide which steps should be in the guide. We wanted to introduce users to the basic concepts of Direct Debit (e.g. mandates and payments), help them set up their API client and then take them through the key API flows: adding customers, taking payments, and handling webhooks. This gave us what we needed to decide on a rough layout for the guide:

  • Setting up your language’s API client
  • Adding a customer using the Redirect Flow
  • Collecting payments
  • Listening for webhooks
  • What to do next (how to go live, further resources for more advanced integrations)

We decided to write a prototype guide with PHP code samples (our most-used language) as soon as possible, so we could test it out with real users and iterate, before writing code samples for all of the other languages we wanted to support.

From the beginning, we emphasised conveying best practices in a way which didn’t really fit with the reference documentation. For instance, we wanted to encourage developers to use a package manager, store their credentials in environment variables and take advantage of our API’s idempotency keys. We also wanted to show people ways to test their code and iterate quickly - for example by using ngrok to test webhooks locally and testing code snippets in a REPL like Ruby’s irb.

Having written a first version, we put the draft in front of two developers completely new to the API who were considering an integration with us. We thought at this stage it’d be really useful to work with people who’d never used the API or Direct Debit at all, since the code is not just about showing you what code to write, but explaining the structure of GoCardless and the underlying Direct Debit system. We learnt a huge amount from this - not only about minor mistakes (like missed syntax errors in our code samples), but also where we’d not conveyed concepts as clearly as we’d hoped.

After iterating on our draft, we added code samples in other languages. Knowing that the quality (and thus copy-and-pastability!) of the samples is vitally important, we implemented automated syntax checking of our snippets as part of the continuous integration (CI) process, alongside a bunch of other automated tests (like checking the validity of links and making sure all our images have alt attributes) using HTMLProofer.

In parallel, we also wanted to bring the design of our developer content up to date with our current website and brand to provide a consistent experience from first discovering GoCardless to integrating with the API to landing in your Dashboard. So James and Achim got to work on designing and implementing a brand new look for the site.

Our developer homepage

When trying to get the guides looking and feeling perfect, we spent a lot of time on our code samples — which are in many ways the heart of the guides. On the page, you can instantly switch between languages, with your choice remembered between pages. Many hours of painstaking effort went into the apparently simple and non-consequential task of stopping the page from jumping around when you switch languages - but we felt that this attention to detail was hugely important in providing the experience we wanted.

Similarly, we wanted to make it easy to link to and bookmark parts of the guide, marked by subheadings. Eventually, we managed to get the behaviour just right so that the anchor in the address bar changes as you scroll up and down the page, whilst maintaining great performance.

Having finished and launched the “getting started” guide for the API, we had demand from elsewhere in the business to go further so we also built and launched a guide to our Partner API for our partnerships team and a guides to our developer tools for our Developer Support team.

Our getting started guide

As a final icing on the cake, while getting inspired at the Write the Docs EU conference in Prague in September, I translated the guide into French, with a member of the French sales team, Côme, helpfully proofreading my work: a great way of carrying over the great new experience and showing our commitment to the French market.

What we’ve learnt

We’re hugely proud of what we’ve built: a beautiful new site for developers which not only includes up-to-date reference documentation, but also provides step-by-step help for developers using the API for the first time.

Through the process of building the new site, we learnt two key lessons which will feed into how we work in the future on our developer experience and the rest of our product:

1. Attention to detail is key

When we reviewed others’ API documentation as part of research for this project, the difference that love and attention to detail makes was clear. The small touches are hugely impactful - for instance, the animated transition when changing languages on the Stripe docs brought a real smile to our faces and was something that we wanted to show others on the team.

These small touches - things like stopping the page jumping when you change language - often take a disproportionate amount of time but are a key part of a polished final product and demonstrating just how much we care about our API.

2. Talk to users as early, and as often, as you can

It’s difficult to write a “getting started” guide as someone who is already familiar with an API and the concepts behind it. You can try and put yourself in the shoes of another developer but this will never be as effective as actually putting your work in front of someone.

We used the experiences of people who had just finished working on integrations to inform our first draft. We then showed that to people who’d never used to API or Direct Debit at all, to get a real sense of how effective our guide was for a complete beginner.

This project has given us a clear reminder of just how important it is to talk to customers, in terms of getting an awesome end result that delivers real value. We’re going to double down on this and make sure that our engineers as well as our Product team get regular developer-to-developer contact with our users.

Coming up next: building an in-product experience for developers

In part 2 of this series, I’ll introduce our new in-dashboard developer experience which guides developers through building their integration with real-time feedback, as well as generating valuable data which we can use to further improve the onboarding experience in future.

Interested in joining GoCardless?
We're hiring
in Announcements

Introducing our new developer site

The brand new

The API is at the centre of everything we do at GoCardless - thousands of our customers use it to integrate Direct Debit into their applications and business processes, and it powers our Dashboard.

We’ve long had a great API reference, but we wanted to create a real home for developers with a wider range of content about our API.

To that end, we’ve launched our brand new developer site, with revamped reference documentation and a brand new getting started guide, helping you get up and running with the GoCardless API.

The guide takes you through, step-by-step:

  • Using our API libraries in PHP, Ruby, Java and Python
  • Creating your first customers
  • Taking your first payment
  • Staying up to date with webhooks

Throughout the guide, we’ve included copy-and-paste code samples in PHP, Ruby, Java and Python to make things as simple as possible.

We’ve also launched a new guide to building a partner integration, and helpful content which explains our developer tools.

We’d love to hear your feedback and answer any questions you have about our API - just get in touch at [email protected].

Interested in taking payments with GoCardless?
Sign up here!
in Announcements

Improvements to our CSV exports

At GoCardless we make recurring payments invisible for tens of thousands of organisations. We know that small details can make all the difference and we’re committed to continuously improving our service. We’re also very aware that although the changes we make improve our service for countless customers, some users need time to adapt to them.

This is particularly true of the exports available from our dashboard. These help make it easy for GoCardless customers to reconcile their accounts and keep track of how much they have collected. Many of our merchants use exports regularly and build processes around them, so we often receive feedback on how to make them more valuable.

We’ve reviewed this feedback and we’re making a few tweaks. These are designed to:

  • Add extra information to make exports more useful for common tasks
  • Make sure the format for exports is as stable as possible
  • Add the ability to improve exports while minimising customer impact

What’s changing?

In most cases – nothing! We’ve made some improvements behind-the-scenes to make the format of these exports more stable and reduce the time to export larger files.

We’ve also added new information to provide more useful reporting to our users:

  • We’ve added the customer data to payment and mandate exports from the events page, so it’s easy to reconcile which payments have failed
  • We’ve added details such as the payment reference and customer metadata to our payout summary export, so you can get all the information you need in one place

We’ve also fixed the date format in the exports so that it’s now fully readable by popular spreadsheet software packages, meaning you can filter and sort our exports by date

The column order in some exports is changing slightly to accommodate the new information and to provide a fixed order by moving optional elements like metadata to the end.

One of our most popular types of export is the payouts export. This comes in three types, so we’ve added a menu system to make navigation easier. From the payouts page you can export a list of payouts:

Exporting a list of payouts

After clicking on an individual payout, you can then export our recommended summary with fees, or click to access a list of the related events:

Exporting payout details

As part of this change we’re also increasing the security of our exports by making all exports downloadable to your computer via your browser using a secure connection.

When is it changing?

We’re launching the new exports in early September. We know that many of our customers have built workflows using our exports, and some might be affected by the changes. To reduce the impact of this we’re making the previous version available for a transition period. When you click to export a report you’ll automatically download the new version, but the old versions will still be available at the click of a button until 19th October.

We hope these changes to our exports improve and enhance your GoCardless experience. If you have any questions please don’t hesitate to contact us at [email protected].

Interested in taking payments with GoCardless?
Sign up here!
in Business

A day in the life of a GoCardless software engineer

I’m Tim, and I’m a software engineer at GoCardless. I’ve been here for about four and a half years. I work on our UX team, building customer-facing bits of GoCardless, such as our dashboard and developer API. My team focuses on making them as powerful and easy to use as possible.

The early days

I first joined the team back in 2012, just a few months after GoCardless had launched into beta. I was attracted by the boldness of what the company was trying to do: making life better for small businesses and disrupting banks’ traditional monopoly. Since then I’ve worked in a variety of roles across the company, from setting up and running our customer support operation to running our partnerships team, to where I am now.

On a typical day, I travel in from my flat south of the Thames and arrive in the office at about 8:20am. I’ll usually spend about 40 minutes catching up with my emails and doing little things on my to-do list while it’s still quiet in the office. Then I go to the gym across the road for a run or to lift some weights. Keeping fit is really important to me and I notice the difference in my productivity.

Once I get back to the office, the UX team starts its day with a “stand-up”. There, we spend about ten minutes as a team sharing what we were working on yesterday, what we’re planning to work on today and raising any areas where help would be useful or where something is blocking us from making progress. Next, I grab some breakfast (there’s a big choice provided by the company!) and a cup of tea before getting back to work.

We usually work on projects in small teams of three or four people - this means we can bounce ideas off of each other, pair programme (where two people work together on the same piece of code), review one another’s work and make progress as quickly as possible.

Connecting and communicating

Most recently, I’ve been leading a project improving our CSV exports. Our customers, especially larger ones, rely on these for their reporting and reconciliation. As a small project team, we scope out the projects, and then divide up the work between us, working in two week “sprints” towards our goal.

I’ve been writing the backend code in Ruby, which builds the CSVs in just the right format. One of our brilliant interns, Henri, has been working on the frontend interface in JavaScript and HTML, which our customers see, getting lots of support from me to get up to speed on our codebase and make the right design decisions.

Throughout the project, I’ve been working with others across the company (usually over a coffee!) - for example, I’ve been in regular contact with one of our salespeople, Michael, and one of our Support team, James, to work out exactly how the CSVs should look to meet our customers needs. I’ve also been working with our Product Lead, Duncan, to work out how we should communicate the changes we’re making to users. Henri has stayed connected with our Design team to make sure the customer experience looks and feels as good as possible.

I hugely enjoy interacting with people across the company. The people are brilliant and it’s interesting to hear about what others are working on. It’s also good to think about how a little investment from engineers like myself could make day-to-day working lives much more efficient for people here. We’re always looking to improve processes and reduce manual work, so people have more time to do what they do best.

Flexible working and side projects

I’ll usually power through work from 10am until about 3pm, and then grab a late lunch at about 3pm (I’m invariably too engrossed in my work to eat until then!). Once I’ve eaten, I’ll get back to work for the last few hours of the day before usually going home at about 6pm (although sometimes I’ll stick around if there’s something I’m particularly enjoying and am keen to keep working on!).

I love working at GoCardless. I’m incredibly fortunate to work in a company packed full of incredibly smart people, to have flexibility to work how I want to (whether that means heading to a coffee shop to work sometimes, going to the gym in the middle of the day or working lying on a sofa) and to get to constantly improve a product used by tens of thousands of people.

If you want to be a software engineer somewhere as great as GoCardless, I’d recommend one big thing: play around with side projects. I’ve worked on lots of fun projects in my spare time from a tool to help people use their air miles are effectively to an open-source API library for Rap Genius. These kinds of things are great fun, give you lots more experience of writing code and look great on your CV.

Growth and…we’re hiring!

GoCardless is growing fast - and we need a lot of great people to help us continue that growth. Our Engineering team is hiring, so if you like what you've been reading, why not take a look at our careers page.

Interested in joining the GoCardless team?
We're hiring
in Engineering, Support

Getting started with the GoCardless PHP library

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.

PHP is the web's most popular coding language, used by nearly 40% of websites, so we've made it super simple to integrate with GoCardless using our open-source API library.

In 90% of cases, you'll be wanting to set up pre-authorizations. These are variable Direct Debits, letting you have your customer authorise once through our secure payment pages, after which you'll be able to charge them automatically whenever you need to with just two lines of code.

1. Add the PHP library to your project

First of all, you'll need to sign up for a GoCardless account and enable developer mode. Once you've done that, you'll get your authentication details which you'll be able to copy and paste into your code. This will take about 5 minutes - just follow our guide here.

Next, you'll need to grab the latest version of our library. There are two options for doing this:

  • Download the ZIP file here and add it to your project.
  • Add GoCardless to your composer.json file:
    "require": {
        "gocardless/gocardless": ">=0.4.2"

We'd recommend storing the extracted GoCardless.php file and the gocardless folder inside a lib/ directory. This makes it easy to organise your code's dependencies.

Next, create a central configuration file. Using this will make it easy to share all the GoCardless setup between different pages, meaning you only have to change your settings in one place. I'll call it


  // By default, your application will run in the sandbox - here,
  // you can test with no money changing hands. When you're
  // reading to go live, simply uncomment this line.
  // GoCardless::$environment = 'production';

  // Let's add your authentication details for the production and
  // sandbox. You can get them both from your Dashboard - copy them
  // in to replace the examples.
  if (GoCardless::$environment == 'production') {
    $account_details = array(
      'app_id'        => 'INSERT_LIVE_APP_ID',
      'app_secret'    => 'INSERT_LIVE_APP_SECRET',
      'merchant_id'   => 'INSERT_LIVE_MERCHANT_ID',
      'access_token'  => 'INSERT_LIVE_MERCHANT_ACCESS_TOKEN'
  } else {
    $account_details = array(
      'app_id'        => 'INSERT_SANDBOX_APP_ID',
      'app_secret'    => 'INSERT_SANDBOX_APP_SECRET',
      'merchant_id'   => 'INSERT_SANDBOX_MERCHANT_ID',


2. Send the customer to the GoCardless payment pages

Setting up a pre-authorization will allow you to get authorisation from your customer once, and then charge them whenever you need to in the future. To do that, you'll need to send the customer through our secure payment process.

Our API library makes this simple:

// Bring in the file we made earlier, which includes the GoCardless
// library and all of our configuration

// Provide the details to use to set up the Direct Debit. In
// particular, make sure you set the amount to be higher than
// you'll ever need to collect in a month.
$pre_authorization_details = array(
  "amount" => "10000",
  "interval_length" => 1,
  "interval_unit" => "month"

// The GoCardless library puts everything together and
// generates a personalised link to our secure payment pages
$pre_authorization_url = GoCardless::new_pre_authorization_url($pre_authorization_details);

// Now we could put that generated URL behind a link...
echo "<a href='" . $pre_authorization_url . "'>Set up a Direct Debit</a>";
// or we could redirect the user right away...
header("Location: " . $pre_authorization_url);

3. Confirm the setup of the Direct Debit

Once the customer has finished going through our payment flow, we'll send them back to your website, where you'll need to confirm the authorization via our API.

Let's create a file called callback.php. You'll need to set the URL of that as your "redirect URL" in your Dashboard's developer settings:

Setting your redirect URI

// Let's include our central configuration file again.

// Pull out the required data from the redirect
$confirm_params = array(
  'resource_id'    => $_GET['resource_id'],
  'resource_type'  => $_GET['resource_type'],
  'resource_uri'   => $_GET['resource_uri'],
  'signature'      => $_GET['signature']

// We'll add this - it'll come into effect if you implement
// a more advanced integration,
if (isset($_GET['state'])) {
  $confirm_params['state'] = $_GET['state'];


// If all has gone well, you'll now be able to charge this
// customer. To do this, you'll need to store their
// pre-authorization's ID somewhere - for instance on a
// user's database record.
$pre_authorization_id = $resource_id;

<p><b>Thank you!</b></p>

4. Charge your customer

When you're ready to charge your customer, it's just a few simple lines of code:


// You'll need to pull our the customer's pre-
// authorization ID which you saved somewhere in
// the previous step.
$pre_authorization_id = fetch_id_from_database();

$pre_auth = GoCardless_PreAuthorization::find($pre_authorization_id);

// Set the details for the payment to collect. We'll
// display the "name" in emails sent to the customer.
$bill_details = array(
  "name" => "Invoice for June 2014",
  "amount" => "25.00"

$bill = $pre_auth->create_bill($bill_details);

// It's likely that you'll want to store the bill's ID
// - this is useful for staying up to date on its status
// later.
$bill_id = $bill->id;

What next?

You've now seen how to set up the GoCardless PHP library, create your first Direct Debit and then take a payment. Here's a few things to check out as your next steps:

  • Web hooks allow you to be informed about the progress of a payment or any changes to your customers' Direct Debits - so for example, we'll let you know when money has been successfully collected.
  • Pre-populating information makes it simpler for your customers to pay and increases conversion.
  • Using the "state" parameter lets you pass data through the payment process, and collect it at the other end.

If you have any questions or we can help at all, just get in touch - email us.

Want to find out more or ask questions?
Book a chat with an expert
in Business, Engineering

Rolling your own cloud phone system

At GoCardless, we're committed to providing great support to all of our users. This means building great tools, both for our customers and for internal use.

We've previously looked at our Nodephone cloud phone system which uses Twilio's telephony APIs and hooks up our phone support with our user data, as well as various internal tools.

Quite a few people have asked us about open sourcing the application. We might well do this, but my experience shows that different users will have very different requirements, so it makes sense to roll your own. This is a guide that will help you do just that.

Choosing the framework: Ruby on Rails + Backbone

I've previously experimented with Node.js and its Express framework and Ruby on Rails for these kinds of applications. Rails is the stand-out choice for three reasons:

  • It's the framework of choice for GoCardless and most other startups too, meaning the expertise is most likely already there
  • Rails provides so much for free, so you spend less time reinventing the wheel and more time building functionality
  • Ruby has an incredibly rich ecosystem of gems, providing functionality from Twilio API access in twilio-ruby to tagging with just one line of code with acts-as-taggable-on

On the frontend, I opted for Backbone.js. Nodephone was my first time working with a JavaScript framework like this, but I'm absolutely converted. Its models and collections made data super easy to handle, and encapsulating presentation logic in bound views helped avoid inevitable callback hell.

Choosing the platform: Heroku

We're experienced at deploying and scaling Rails apps at GoCardless, but a service like this didn't justify giving our dev ops team another service to manage. Instead, we chose Heroku to give us:

  • super simple deployments
  • high availability so users can always reach us

Heroku offers a lot of addons as well, making it easy to add extras like log management, a Redis database or exception tracking in a couple of clicks with no billing complications.

Heroku can be a little expensive. If you're looking for a cheaper alternative and more flexible customisation, a great choice would be Amazon Web Services Elastic Beanstalk, especially with the benefits of the AWS free tier.

Working with external services

One of the great things about building a custom phone system is the freedom to integrate with other services you use.

Nodephone pulls in the profiles of callers from GoCardless itself based upon their phone numbers, as well as working with external apps like Salesforce.

When you're working with Twilio, response times of your app are critical to providing a decent experience for callers. Slow external services, and worse still, applications that inevitably go down, threaten that.

The ever-popular background job library Resqueprovides an ideal solution, allowing tasks depending on background services to be performed asynchronously.

When someone calls in, we look up their phone number in GoCardless to see if we know who they are. To do this, we enqueue a Resque job to perform the API request whilst displaying a progress indicator to the client:

Looking up...

Once the job has finished in the background (which usually takes seconds) the app provides a real-time update to clients using Pusher's web sockets:

response = Gocardless::Merchant.find(args["merchant_id"])
Pusher.trigger('calls', 'lookup', { id: args["call_sid"], merchant: response })

Looked up caller

If GoCardless is slow to respond or out of action, there will only be a slight degredation of service, rather than failed calls.

Avoiding missed calls

We've all called customer support lines, and one of the biggest frustrations is having to wait for ages to speak to someone who can help.

In order to manage bursts of incoming calls, we introduced a queuing system. Since our average call lasts less than 3 minutes, most callers can get through to someone within a few minutes. However, we also wanted to ensure we didn't miss calls from people getting frustrated by longer waits in the queue.

We achieved this with more Resque magic. Once a caller has chosen an option, they're placed in the queue and agents can pick it up by hitting the "Answer" button on their screen. When a call is answered, we mark it as such in our database.

When the call joins the queue, at the same time we schedule a job for 3 minutes time which will check if the call has been answered:

Resque.enqueue_in(3.minutes, ForwardUnansweredCall,

If, 3 minutes from now, it hasn't, it'll ring on all of the phones in the office immediately. This means that every single call is answered within 3 minutes during office hours - but usually much sooner!

Open for business

A particular challenge when building phone systems, as simple as it sounds, is managing opening hours, thanks to complications like time zones. Existing gems that I found like business_time were one step removed from what I needed.

It quickly became clear that I wanted something that didn't already exist, so I built it myself in no time at all. My in_business library lets you set your business hours on a daily basis, and provides simple open? and closed? methods to call in your code:

# Configure the gem with hours of your choice, on a day-by-day basis
InBusiness.hours = {
  monday: "09:00".."18:00",
  tuesday: "10:00".."19:00",
  # ...
  saturday: "09:00".."12:00"
} # => true [if now is within the set hours] DateTime.parse("9th September 2013 08:00") # => false

Taking inspiration from business_time, I added support for the holidays gem, making it possible to take into account public holidays with just two lines of code:

Holidays.between(Date.civil(2013, 1, 1), 5.years.from_now, :gb).
  map{ |holiday| InBusiness.holidays << holiday[:date] } DateTime.parse("25th September 2013 10:00") # => false

An important final addition was adding overrides for the set hours. From time to time, you inevitably want to open and close on an ad-hoc basis. For instance, you might decide to open on a bank holiday when you hadn't planned to.

Overriding business hours

The end result

Twilio, accompanied by popular tools and frameworks and some ingenious thinking makes it relatively simple to build powerful bespoke phone systems which run entirely in the cloud.

Do you love talking to customers and building great tools to track and improve the service you provide?
Join the GoCardless team.

Talking to our customers 2.0

Back in January, I wrote about our customer support phone system, Nodephone. Based on Twilio's telephony platform, it allowed us to collect valuable data about our phone calls with customers.

Since then, GoCardless has grown to become the UK's largest Direct Debit provider. On support, we now generate huge amounts of data every day. We've continued iterating our phone system to help us:

  • Prioritise development by generating user request data
  • Train our staff by recording calls
  • Distribute our product by linking up with Salesforce
  • Deliver great customer support by routing calls efficiently
  • Allow flexible working so support agents can work from across the UK

This post describes how the system works.

Prioritising development by collecting feedback

Around two months ago, we started using our new feature tracking tool to log our customers' thoughts and comments. Often, however, we found feedback from calls was lost, as the process for recording it was still too time-consuming.

With our new phone system, it is extremely simple to log a feature request whilst on a call.

The agent simply enters the information in a textbox on-screen either during the call or immediately after.

It is then submitted instantly to the tracker, complete with the caller's details, so we can keep them up to date on progress or get in touch if we want to delve deeper into their thoughts.

Training our staff with call recordings

Providing great quality support means providing great training for our support agents. Further, to keep close to our customers we insist that everyone in the company spends time on support. That means a lot of people who need training!

One powerful way we've found to help people improve is to play back calls and discuss them. Our new phone system makes that easy - thanks to Twilio, we're able to record every phone call, providing amazing resources for training and monitoring.

Linking up with Salesforce

Many of our potential customers first contact us via our support channels, so we want the handover to our sales team to be as smooth as possible.

Now, we record data about prospects into Nodephone, and this is passed through automatically to our Salesforce CRM using their API.

Recording a prospect

What's more, the process for our sales team of calling back leads is massively simplified with a smart integration between Nodephone and our internal Chrome extension.

Call from Salesforce

Click the "Call" button and your phone rings and connects you straight through. Make some notes or schedule a callback in the window that pops up, and all the data gets passed back through to Salesforce automatically, including the recording. Magic.

Salesforce tagging

This has increased the call volume our sales agents are able to make by about 20% - a real difference for our productivity.

Providing a great customer experience

We want to provide awesome support, and that doesn't include waiting ages for an answer and then being sent around the houses. Our new phone system makes call routing simple, and ensures no-one waits longer than 3 minutes to speak to us.

Now, when customers call, they begin at a quick 10-second menu where we work what they're calling about - whether they're paying someone, already collecting or looking to start taking payments with us.

Once they've chosen an option, they enter the queue and show up in our revamped agent interface.

Queued call

After 3 minutes, if no-one has answered, all calls are forwarded to every phone in the office, ensuring a speedy response.

Allowing flexible working

As GoCardless has grown, we've needed to expand our support team. As we've done so, we've become more and more interested in a distributed support model, where agents work part-time from wherever they are.

Historically, it's always been easy to answer emails from home but not so simple for phone calls. Our new phone system fixes that.

When configuring Nodephone, agents enter the phone number they'd like to use when answering calls. Then, when they hit the "Answer" button, the call is put through to that phone. Agents can choose any phone number or even take the call direct from their laptop using Twilio Client.

More accessible data

In the original Nodephone, we recorded plenty of data for long-term stats, but it wasn't easily accessible on a day-to-day basis. We've taken two steps to fix this.

Firstly, we have a full interface for looking back at previous calls, incorporating recordings, notes and other data.


Secondly, if a caller has called before, at the click of a button you can get an at a glance view of their previous interactions.

Previous calls modal

To sum up

Nodephone 2 is already bringing great benefits to our internal processes and our customers.

If you're more of a technical type, stay tuned - in a few weeks' time, we'll have an in-depth look at the technical implementation of this new app.

Are you excited by building great tools to solve real business problems? Join the GoCardless team.

What do you think?
Share on Twitter

New features in the GoCardless API

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.

Today we're extending our developer API to include three great new features: payouts, pagination & improved filtering.


You can now query payouts in our REST API, making it possible to build features like bank reconciliation into your integration.

For each payout we'll tell you the amount, the fees charged and the reference that will appear on your bank statement.


Using our new pagination features through the page and per_page parameters, you can cycle through your data in manageable chunks.

This is especially useful for merchants with a large number of customers or payments.


API requests can now be filtered by a wide range of attributes. Full details are available here.

Available now

These additions have already been included in our API libraries.

If you have any questions, don't hesitate to get in touch by emailing us at [email protected] or giving us a call on 020 7183 8674.

in Customers, Motm

Merchant of the Month: Has Bean Coffee

Has Bean Coffee

One of the nicest things about having businesses as GoCardless customers is that we get to see the great use they make of the service. Our 'Merchant of the Month' programme recognises and thanks some of our favourite customers each month for being so awesome.

For December 2012, we've selected Has Bean Coffee, who sell coffee beans and coffee-making equipment online. They've been using GoCardless since November 2011 via KashFlow to collect payments from their wholesale customers conveniently and affordably.

We had been looking for years to find some way of taking Direct Debits. GoCardless have looked after us so much. I need systems that just work and this is what GoCardless gives us.

Stephen Leighton, Managing Director of Has Bean

They also offer coffee subscriptions, and are working on an integration with our API to allow them to take payments for these each month via Direct Debit for a fee of just 1%.

Interested in discovering all the great benefits of GoCardless for yourself? Simply sign up today in just 60 seconds!

in Business, Engineering

Data-driven support

Here at GoCardless, we try to make all our decisions in a data-driven way. Staying customer-centric whilst we do so means making sense of all the interactions we have with our customers.

On the Customer Support team, we spend more time than anyone else speaking to customers. We generate a lot of rich but unstructured data: our email, calls and other interactions. Recently, we’ve been working on new ways to analyse it to improve our support and drive product development.

How things were

When I joined GoCardless we were providing great support but our tracking was ad-hoc. We were manually recording some interactions, but the data was patchy and the process was time-consuming.

Worse still, our support data wasn’t linked with the rest of our data, meaning we weren’t using what we did record. It was buried.

Enter Nodephone

We decided to begin our overhaul of support-tracking with our phone channel, and I set about building a new, metrics-driven system.

We had a good foundation to build on - all external calls come in on a Twilio number and are forwarded to phones in our office. To get good quality tracking I built a system called “Nodephone” to sit in the middle. Built in Node.js with the Express framework and, it’s on the other end of Twilio, responding with TwiML, but it also communicates with GoCardless and a web interface.

Any incoming call is logged and looked up in our merchant records. We then display the call on a simple web interface, where the support agent can see the caller’s name and click straight through to their records. At the end of the call, they can add descriptive tags and notes.

Nodephone interface

Now when customers call we know who they are and can greet them personally! If we don’t recognise their number and we find out who they are on the call, we can save it from the web client for future calls.

All the data entered, alongside the duration of the call, is saved on the merchant’s account for future reference.

A logged call

Data, data, data

All that data we’re collecting has already proved incredibly useful since we can analyse it to find the trends. For example, we want to know between what hours we should provide support, so I graphed the number of calls in different hours of the day over a typical month:

Calls over hours of the day

Clearly the vast majority of people call between 9am and 6pm, so we decided to set our office hours for then. We also use this kind of data to inform recruitment for the customer support team.

We can also see why people are calling - that is, whether they’ve paid via GoCardless (customers), collected money (merchants) or are interested in taking GoCardless payments (prospects) from the tags:

A logged call

As a start-up that prides itself on reducing friction to signup we were amazed to see so many prospects trying to call us. What’s more, they were finding our number from parts of our site designed for our current users. From the data above, we decided to put our number front and centre on our merchant signup pages - check it out here.

The tags we logged on calls from merchants also showed that there was a lack of helpful information on the site to answer common questions, so we’re revamping our FAQs with a whole range of new content.

What’s next

We’ve built a powerful new automated metrics system for logging our phone calls.

Next we’re targeting our other support channels. We’ll be using’s API to analyse our email support, providing the ability to do all sorts of calculations which aren’t possible with the software’s own analytics.

We're also going to build an internal dashboard so anyone can see the headline stats for support in a couple of clicks.

Over time, we want to make all our internal analytics as powerful as we can. If you find problems like this interesting, we’re hiring and would love to hear from you.

in Customers

Spencer Hockey Club

Spencer Hockey Club are one of several sports clubs collecting their membership fees with GoCardless. With over 400 members they wanted a simple way to collect fees, and to keep track of who had paid. As a non-profit they didn't want to pay high fees.

The GoCardless API was the perfect solution. Integrated into the Spencer Hockey Club website, it makes paying and keeping track of whose paid incredibly simple. Mark McDermott, who wrote the integration, describes the benefits:

"We'd wanted a way for members to pay their fees online for a couple of years, but PayPal and the rest were just too expensive. With fees of only 1%, GoCardless changed that. It's made collecting membership fees much less time consuming, so our volunteers can focus on what they do best."

The GoCardless API is incredibly flexible, and with client libraries in PHPJavaPython,Ruby and .NET it's easy for any developer to use.