Mandates: Supporting mandates set up outside of your product
We’ve already looked at setting up new Direct Debits through your product.
To provide the best experience, you should consider allowing your users to “import” mandates set up outside your product so they can bill their customers within your product. There are three reasons why your users might have mandates in this situation:
Existing users of GoCardless: It’s likely that some of your users will have already been using GoCardless before connecting it to your product, so they may already have Direct Debit mandates set up with their customers.
Bulk changes: If your user was previously using Direct Debit through another provider, they, subject to availability, can “bulk change” their existing mandates from their existing provider to GoCardless.
Mixing and matching ways of using GoCardless: Your users might choose to add customers using our Dashboard, our API (for example on their website) or using another integration to better match their workflow.
You can support importing mandates in two main ways:
Automated imports: Fetch a list of the user’s mandates using the Mandates API, then match the customers’ personal details (
given_name,family_name,company_numberandemail) against your application’s internal records to automatically suggest matches, allowing the user to approve these pairings or manually correct them if incorrect (see below for more detailed instructions)Manual imports: Allow users to export a list of customers from your product as a spreadsheet, fill in the mandate IDs from GoCardless, and then upload the completed spreadsheet or email it back to you so you can update your internal records
We recommend supporting automated imports - this makes it as easy as possible for your customers to get set up and then get the best value out of your integration, whilst keeping manual administrative work for you to a minimum.
Building automatic mandate matching
Automatically loading and matching existing Direct Debit mandates provides the best customer experience, making importing your users’ existing customers an easy and integrated part of the process of connecting GoCardless to your product.
We’d suggest building a flow like this:
Prepare a database table that links GoCardless mandates to one of your users, and includes columns for the customer’s given name, family name, company name, email, the GoCardless mandate ID and the GoCardless customer ID.
Load all mandates using the API, filtering for those in statuses “active”, “submitted” and “pending_submission”.
For each of them, load the customer using the customer ID in
links[customer], so you have the details for both the mandate and the customer it’s attached to.Automatically try to match the GoCardless mandates against customer records in your product, for example using the names or email, and record these suggested matches in your database. You’ll need some way of storing in your database suggested matches between GoCardless mandates and your product’s internal customer records, and what match, if any, your user has picked.
Provide a UI where your user can confirm the suggested pairings between mandates and customers, or override the suggestions where they’re incorrect, picking another mandate
Use webhooks to track when new mandates are created or existing ones become inactive and then, following steps 3-5 above, record them. This will allow you to support users' “bulk changing” mandates to GoCardless from another Direct Debit provider or adding customers outside of your product throughout the time they’re using your software, rather than this just being a one-off process when the user first connects their GoCardless account to your product.
In addition to importing existing mandates, you may want to consider querying your user’s GoCardless account for existing subscriptions, payments, refunds, and payouts to ensure that your product can reflect a complete record of your user’s ongoing Direct Debit activity.