This article assumes that you currently have an integration with our Legacy API.
If you don't have an existing integration or if you're using our current API then this article won't apply to you - you can view our current API documentation here.
You might find it useful to read the overview of changes before reading this guide.
If you have or are interested in building a partner integration then this guide is relevant to you, but you should also contact us before getting started.
What do I do first?
If you've not done so already, you should create a sandbox account here. Sandbox accounts are no longer linked to your live account, so you will need to create a separate sandbox account to build your integration with the new API.
Next, create an access token. You'll need to give your access token a name and make sure you give it read-write access. Click “Create access token”, and copy the token to your clipboard. Save this somewhere secure, and note that you won't be able to access it again. If you need to, you can disable your access token and create a new one.
Have a read through our Getting Started guide and our full developer documentation to make a start on your new integration. The guide and documentation have code examples for all of our current client libraries (or HTTP requests if we don't have a library to suit your stack), and you can view the source of each library through the links in our documentation.
Making Requests to the new API
If you're using one of our client libraries then you don't need to worry about this section - the libraries take care of building requests in the correct format for you.
The base URLs for the API are:
Live | https://api.gocardless.com/ |
Sandbox | https://api-sandbox.gocardless.com/ |
You'll need to use the access token you created earlier, and provide it in an Authorization request header when making requests to the API:
Authorization
: Bearer ACCESS_TOKEN_HERE
You'll also need to need to specify the GoCardless-Version header. The currently available version at the time of writing is 2015-07-06:
GoCardless-Version
: 2015-07-06
All requests and responses are JSON-formatted and UTF-8 encoded. Providing the Accept
header is optional, but recommended. The Content-Type header must be provided when sending data to the API (using POST and PUT endpoints). You may pass either the standard JSON MIME type (application/json
), or the JSON-API variant (application/vnd.api+json
).
Webhooks
Webhooks now contain a lot more information, and can be sent to multiple endpoints. When a resource changes status we record an event, and events are batched into arrays and POSTed as webhooks.
If you want to make use of webhooks then you'll need to add a webhook endpoint here. In sandbox, you can use an HTTP URL for your webhooks, but to go live the endpoint must be HTTPS secured. You can find out more on staying up to date with webhooks here.
How do I carry on billing my customers?
In order to create payments for your customers, you'll need to use the customer's mandate ID. Whichever type of authorisation you used with the legacy API, you'll now need the mandate ID to create payments.
The resource IDs you have been using can be used in the current API, but they'll map to slightly different resources. For example, a pre-authorisation ID in the legacy API is now the ID for a mandate in the current API. The mappings are listed below:
Legacy ID | New ID |
Pre-Authorisation ID | Mandate ID |
Subscription Authorisation ID | Subscription ID |
Ad-Hoc Authorisation ID | Payment ID |
Bill ID | Payment ID |
Mandate restrictions
The legacy API had one-off bills and un-editable subscriptions, so the customers who set up those Direct Debit mandates will need to approve any new payments or subscriptions you create against their mandates. We refer to these as "restricted mandates".
You can't create restricted mandates through the current API, but they exist so that there's an easy way to charge those legacy authorisation types without customers re-entering their bank details.
Legacy Authorisation Type | Mandate Type |
Pre-authorisation | Unrestricted mandate |
Ad-hoc (One-Off) Authorisation | Restricted mandate |
Subscription | Restricted mandate |
Using an unrestricted mandate, you can create payments and subscriptions for the customer with no further authorisation - but we will email the customer to let them know when you've created a payment or subscription in order to comply with Direct Debit scheme rules.
With a restricted mandate, we will email the customer to ask for authorisation before any payments are taken from their account. The customer will just need to click on a link in the email to authorise it; they won't need to complete the payment pages or provide any details again.
Pre-authorisation mandates are not restricted, but the maximum amount and interval that you originally specified will still apply.
How do I set up one-off payments/subscriptions/pre-authorisations now?
Instead of needing to create separate links for each type of authorisation, you'll just need to use the one Redirect Flow concept.
Firstly, you'll create a redirect flow for your customer and send them to the redirect URL provided, e.g. https://pay.gocardless.com/flow/RE123.
The customer will complete the new and improved GoCardless payment pages, supplying their name, email, address and bank details.
Upon submitting the form, we'll securely store their details and will redirect the customer them back to your success redirect URL, which you specify when creating the redirect flow.
You'll then need to "complete" the redirect flow with a single API request, which will create the customer, customer bank account, and mandate - this is similar to the "confirming the resource" step in the legacy API.
Using the newly-created mandate, you can create payments and subscriptions for the customer. You should store the mandate ID so you can create future payments against it, and identify incoming webhooks related to the mandate's status.
How do I make the switch?
When you're happy with your sandbox integration with the new API, we can help you switch over in a few stages:
- We upgrade your account to our new dashboard. You'll lose access to your old developer dashboard, but your legacy integration will continue to work. All your existing data will be available in the new dashboard.
- Now your account is on the new dashboard, you'll be able to create an access token and specify a webhook endpoint for your live account.
- From your side you can phase out using the legacy API and start using the new one at your own convenience.
- When you're happy everything is working smoothly, we can disable your legacy access token and webhook endpoint.
Things to note:
- All of your account history will still be available and your customers won't need to reauthorise.
- Any resources that you create through the new Dashboard or API won't be accessible by your legacy integration, but any resources created in your legacy integration will be accessible by the new API.
- You will need to contact us so we can upgrade your account and then disable your old integration (or if you have any questions along the way!)
- If you have a legacy partner integration, you should contact us to make sure that this switch process is suitable for your integration.