Overhauling API docs with GoCardless
Welcome to GET PUT POST, a newsletter all about APIs. Each edition features an interview with a startup about their API and ideas for developers to build on their platform.
This edition, I spoke with Andrew Farrell and Tim Rogers from GoCardless. The company provides a clean API to abstract away the pain of Direct Debit (a popular payment method in Europe). We discuss some of the benefits of Direct Debit and how the team rebuilt their API docs to better serve developers.
Want the latest interviews in your inbox?
What is GoCardless?
Our vision is to provide an API-first solution for Direct Debit. Direct Debit is similar to the ACH system in the US, except it’s much more widely used in the UK and Eurozone. In 2015, Direct Debit was 17% of all transactions in the UK transactions, 20% of those in France, and 50% of those in Germany. It’s used for paying phone bills, heating bills, and magazine subscriptions. In some countries, Direct Debit is even used ubiquitously for one-off payments.
Before GoCardless, companies worked directly with banks or through bureaus, which do a load of manual work on behalf of a couple hundred small businesses. That process requires hiring a payments team to make CSV spreadsheets, upload them to banks, and then manually process receipts. It also means having to handle failed payments, cancellations, and chargebacks separately, which is very time-consuming. Instead, GoCardless does all the grunt work that’s involved in running a Direct Debit system and exposes it through an API.
We started offering the product in 2011 and initially targeted small businesses who previously couldn’t access Direct Debit. They could access the service both directly and through our integrations with popular accounting software like Xero, QuickBooks and Sage.
We originally built a first-party dashboard for payments that made it possible to add a customer, take payments from them, and set-up recurring subscriptions. We had some initial growth from small merchants, but larger ones found they really needed it baked into their accounting software or membership billing service.
We found that we couldn’t build out every integration to serve each vertical perfectly. In 2013 and 2014, we refocused ourselves on perfecting the API and exposed the basic concept of the Direct Debit system: a mandate, which is a link into a particular bank account that allows users to place and pull money.
Who are some sample customers?
When we were building the second iteration of the API, we realized that we could make it valuable to larger businesses who wanted to integrate the API themselves. This dramatically increased the size of customers we work with.
For example, a travel company in the UK called Thomas Cook wanted to build a system that allowed people to pay for vacations using Direct Debit. Our API was a great answer for that because they didn’t have to build a direct relationship with a bank, hire staff to do manual work, or understand the complexities of the underlying technology. It was so cost effective that Thomas Cook created a new payment option to let customers pay by installments without charging any additional fees.
There are many niche integrations that people have built, like a tool used by window cleaners to manage their businesses or a website used by scout groups. Our API allows us to reach deeply into specialized markets through partners who really know those people and understand their workflows.
What are some of the challenges of Direct Debit?
One difficulty is timing. With credit cards, the payment is successful or the charge is declined immediately. The Direct Debit system is much more asynchronous.
When a customer creates a mandate, we open a line into somebody’s bank account and people aren’t told immediately whether a transaction is successful. That doesn’t work for some kinds of transactions. For example, businesses might not want to use it to sell gold or clothing over the internet.
Being async is not necessarily a problem for recurring payments. Importantly, making recurring charges using Direct Debit is cheaper than using a credit card.
Also, bank accounts never expire and are rarely cancelled. In the UK, for example, the average person changes their bank account 1.4 times in their life. When a business is looking to reduce churn, they can get a longer-lasting customer through Direct Debit.
We came to the decision last year that these were the benefits to target because they improve efficiency and drive up revenue.
How do you measure growth?
We focus on measuring the number of active businesses using GoCardless via our API, including through integration partners like ChargeBee.
This guides us to focus on documentation. As developers, we know that’s the key to getting customers on board with an API and making the most of it.
We developed a schema that describes our API in code. Then, we built a tool chain to automatically generate new client libraries and update documentation every time we deploy the API. That means our reference documentation is always up to date with the API.
The custom tool chain shows how much we focus on growth through docs.
What’s in that tool chain — is it open source?
The tool chain starts with schema files in the project with the API and we watch those files with every commit. There’s a Go tool to process the schema files based off a template for the documentation and client libraries. We have templates for each of the languages we support.
Last year, we realized that we weren’t providing something important: “getting started” documentation. Reference docs need an understanding of the underlying concepts of the API.
We began with some user research, which included talking to users about the process of integrating with the API, and speaking to beginners integrating for the first time.
What questions did you ask these users?
We spent time looking at what others were doing (including Spreedly, Intercom, and Twilio) and tried to assess their best practices. We looked at their onboarding experiences for developers and how this tied into documentation. We then compared it to ours and looked for where we could do better.
We mostly asked users what they found difficult in the docs. Understanding the basic data models was a problem and this seemed to stem from not knowing how Direct Debit works. We also heard that the docs weren’t well organized. Users didn’t like an alphabetically ordered list of available resources.
So, we decided to build a sequential guide to show how to build an integration and included code samples in a bunch of different languages. We wanted to convey best practices like not storing API credentials in code and using package managers as part of the guide.
We organized everything around the important workflow steps: setting up a mandate with a customer, taking payments from them, and listening for webhook responses.
Then, we put written drafts in front of users. We brought people into our office and paid them a freelance rate to go through the documentation. We asked them to build an integration for themselves and note what was confusing, what things they’d like to add, and where they thought we could do better.
What are the benefits of the improved docs?
We’ve heard feedback from the sales team that it’s now easier to explain things to folks who are signing up because they can just link to a particular section in the documentation.
We also built an onboarding wizard within our dashboard to tell users what to do to get up and running. As users follow the instructions, it ticks each step off. We built a flow for people who said they wanted to use the API that lined up with the steps we’d written in the guides.
In the getting started guide, we tell users how to add their first customer, take a payment, etc. We track their performance in the backend and give feedback in the interface. The process gives us data about how users are getting on.
The analytics milestones that we track are: setting up your access token, creating a customer, and creating a payment. The data showed that the time it took users to perform those steps decreased.
In the long-term, we expect more gains sales and revenue because we’re competing against ways of doing Direct Debit which are much more complicated and require manual work. We really want to serve that need and the simple guides really showcase the API.
What are your long-term ambitions with GoCardless?
We currently serve three markets: the UK, the eurozone, and Sweden. Our dream is to build a bank-to-bank payments network around the whole world, which will compete with Visa and MasterCard. We’re trying to make Direct Debit function as the plumbing of the internet that provides an efficient way of doing payments. We hope to improve upon existing Direct Debit schemes by building better ways to collect payments from the customer’s point of view.
Once we’re able to work in most countries, we could become interesting to companies like Netflix or Amazon, both of which have problems with selling and collecting internationally.
Many people who don’t know about Direct Debit might go to Stripe if they want to build a recurring SaaS application. However, taking those sorts of payments with a Direct Debit system would be better for their business, particularly in the UK and Europe. As a Direct Debit specialist with a laser focus, our main competitors are other payment options such as credit or debit cards.
I think it’s great to offer multiple payment options and the research suggests that doing that increases conversion. We have a recurring payments guide on our website, which is an interactive guide to show all the different benefits and costs of using different systems.
When you’re collecting Direct Debit details, are there any concerns regarding fraud?
The protections for customers using Direct Debit in the UK and Europe are even better than they are for credit cards. Since there’s no authentication per se, if a customer has been defrauded, they can contact their bank and receive a “no questions asked” refund immediately. It’s known as the “Direct Debit Guarantee” and provides the ultimate protection to the consumer.
The reason Direct Debit works for recurring payments is that the system is built on top of an ongoing relationship between merchants and their customers. If chargebacks were that easy for credit cards, Amazon probably couldn’t sell books. However, when a customer is paying a fixed amount monthly, most businesses are comfortable with that risk because it saves them money and provides a great user experience.
If you like the post, please give it a 💚 below:
Want the latest interviews in your inbox?
