Setting up mandates#

A mandate is permission from your user's customer (the payer) to collect payments from their bank account. Your user asks for it once, then charges against it for every payment. In your platform, a mandate belongs to the customer or membership it pays for. We recommend one mandate per customer. For how your other records map to GoCardless, see how partner integrations work.

Setting up mandates takes four steps:

1. Choose what kind of mandate you need
2. Trigger mandate requests from your product
3. Send the payer to a checkout
4. Link the mandate to your records

1. Choose what kind of mandate you need#

• Direct Debit mandate: The payer sets up a Direct Debit mandate once, and your user can then collect one-off or recurring payments without asking them again
• Instant first payment with mandate: Your user collects the first payment within minutes by Pay by Bank, then collects others by Direct Debit
• Variable Recurring Payments: Your user collects payments of varying amounts by Pay by Bank, within limits the payer agreed in their banking app

Direct Debit mandates stay open until they're cancelled, so your user can schedule payments in your platform.

2. Trigger mandate requests from your product#

Add a "Request Direct Debit" action where your user is already thinking about payments:

• On the customer record, when your user adds or edits a customer
• On invoices, memberships and subscriptions, when your user sends or sets one up
• As a generic shareable link your user can add to emails, messages or their website

For examples, see the payment creation design guide.

3. Send the payer to a checkout#

You'll need to create a Billing Request for your checkout. Use an idempotency key, so retrying the request never creates a duplicate. You can do it with:

• GoCardless hosted pages: Fastest to implement
• Components: Highly customisable, pre-built UI components. See Components for partners
• Custom payment pages: Build your own checkout. Most customisable. Note that we need to review all custom payment pages before you can go live

To compare them, see how do you want to integrate.

Hosted pages show the payer a success screen. If you skip it with skip_success_screen and send them to your redirect_uri, show a confirmation there that tells them what happens next.

You can improve your payer experience and improve conversion by:

• Pre-filling payer details, and their bank details if you have them, so they have fewer steps to complete. If your user gives you bank details, check them first with a bank details lookup. If it returns an error or an empty available_debit_schemes, we can't collect from that account
• Setting up Protect+ to ask risky payers to verify their bank account. Leave verify on the mandate request as recommended, the default. It only verifies payers for merchant accounts where we've turned on Protect+

4. Link the mandate to your records#

Link each mandate to your customer record in both directions, so you can always find one from the other. When you receive the Billing Request fulfilled webhook, use the IDs in its links:

• From your platform to GoCardless: save the mandate ID from the event's links.mandate_request_mandate against your customer record
• From GoCardless to your platform: update the GoCardless customer in the event's links.customer with your own customer ID in its metadata. You can use any metadata key. We've used partner_id in these docs, for example {"partner_id": "CUST-123"}. Use the same key every time, so you can match on it later. You can add up to 3 keys. Don't put personal data in metadata. It also means you can match mandates back to your records later, for example when importing mandates

Show mandates in your product#

Show each customer's mandate and its status on your customer list and on the customer's page. Your user can then see at a glance which customers they can charge. For examples, see the mandate status design guide.

A mandate's status can change at any time after it's set up: it can fail, be cancelled or expire. Listen for mandate events to keep the status up to date, and let your user ask the payer for a new mandate when one stops working.

What's next?#