This article assumes that you currently have a partner integration with our .
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 .
You should also read the other - they’re not partner-specific but they have lots of useful information about the differences.
What do I need to do?
- Create a new GoCardless account.
- Build an app integration with our new API.
- Upgrade your existing merchants to your new app.
These steps are described in more detail below. If you have any questions or need any advice, just open a ticket with our Developer Support team via https://support.gocardless.com/hc/en-us/requests/new
Creating a new account
Our have more information on .
Once you’ve built a working sandbox integration you’ll just need to create a new app in our live environment then switch over the credentials. If you’re taking app fees (the fee you charge per-payment on top of the GoCardless fee) or revenue shares (an agreed percentage of the GoCardless transaction fees) you will need to add a payout bank account via your company settings page and verify it.
There’s currently no separate partner dashboard like there was in legacy, but we’ll be adding more partner-specific sections to the new dashboard in the coming weeks.
Building an app integration with our new API
We’ve written a comprehensive guide to building a partner integration with our new API, which covers:
- How to using our OAuth flow
- How to set up Direct Debit and
- How to most effectively, including and
- How to
- Checklist of
- Wireframes for how to create the
These guides cover most aspects of making a new partner integration, complete with code examples for our client libraries, and is supported by our . You should also refer to our .
Testing resource migration in sandboxTo test your new partner integration, it is possible to migrate any legacy sandbox merchant access tokens that belong to your app, to your new V2 sandbox app. This will allow you to test the behaviour of existing resources in the new system.
To request the sandbox access token migration, please send an email to firstname.lastname@example.org from the email address of your current account, the app name associated with the app created in your new sandbox account and the email address associated with your new sandbox account.
Upgrading your existing merchants to your new app
Your merchants won’t need to re-authorise your app when you upgrade. The access tokens you currently use can be migrated for use with the new API - just to arrange the switch.
You’ll be able to upgrade incrementally, using both APIs side by side for your existing merchants until you’ve completed the upgrade.
The process is as follows:
- You let us know your new app ID - you can find this in the URL when you view the app in your dashboard.
- We copy your legacy app’s merchant authorisations across to the new app.
- You’ll start receiving webhooks for all these merchants to your new app’s webhook endpoint (if set) and your new app will be able to use your legacy access tokens.
- We’ll send you a list mapping legacy merchant IDs to new organisation IDs.
- Any merchants that connect to your legacy app will automatically be copied to your new app.
We’ll keep sending webhooks to your legacy webhook endpoint too, until you ask us to stop. Let us know when you’re happy you’ve completed the upgrade, and we’ll disable your legacy app and webhook endpoint.
All legacy customers, authorisations, subscriptions and bills are immediately available via the new API.
Any resources you create or update through the legacy API will be synced forwards to the new API; if you create a Bill in legacy then a corresponding Payment will be created with the same ID.
Resources you create through the new API will not be synced to legacy. For example, if you create a new Mandate then no legacy Pre-Authorization will be created.
Resources you update through the new API will be synced to legacy if there is a corresponding legacy resource. For example, if you cancel a Payment that has a legacy Bill then the Bill will be cancelled too.
As data doesn’t always get synced back to legacy, only forwards to the new API, it won’t be trivial to downgrade a merchant once you’ve started managing them through the new API. You should be confident that your new integration works before upgrading any live merchants.
Any legacy resource IDs you already have stored can be used in the new API, but they map to slightly different resources. Read through the “How do I carry on billing my customers?” section in our more general for full details of the mappings.
App fees & revenue shares
Partner app fees are now much more flexible. They are no longer configured for all payments on your account - now you can specify an app_fee for , or for . Instead of a percentage or a fixed amount, your integration will specify an amount in pence/cents so you can handle the calculation yourself.
If you’re not taking any app fees, we can configure a revenue share so that you’ll automatically receive a percentage of the GoCardless fee that is charged per payment. Any revenue shares on your legacy integration won’t be automatically copied across - you should if you need help working out which fee type is best for you, and to get your account configured accordingly.
Read through the “Mandate Restrictions” section in our general for details on how pre-authorization limits (e.g. “up to £200 every month”) and subscription mandates (e.g. “only £20 every week”) are enforced in the new API.
We currently have no plans to re-implement pre-authorization limit amounts and reset dates in the new API as they added complexity and confusion in our legacy API. However, the authorisations created by the legacy API had these restrictions so they must be carried across to protect payers who agreed to those mandates. You’ll continue to see a validation error if you attempt to exceed these limits.
If you’re using pre-authorizations you may wish to export the max amounts and reset frequencies that you created them with so you have a record of the restrictions that will continue to be applied. You can get this information by retrieving the records from our
If you have any questions or need any advice during the upgrade process, please don’t hesitate to reach out to our Developer Support team by .
You may also find these other documents useful: