Integration guide#

We want to help you build a great integration that delivers real value to your users. Use each section as your checklist while you build, and work through all of them before going live. We look for these items when we review your demo, and each section links to the guide that explains how to build it.

App and account#

Creating and configuring your partner app is the first step of your build. Set it up, and your own GoCardless account, before you connect any users.

• Your partner app has at least one redirect_uri
• Your partner app has a webhook URL, so you get events for all your connected users
• Your partner app has a clear, public-facing name. Your users see it when they connect
• Your partner app has a post_onboarding_url, so your users land back on your product once they finish verification
• Your partner app has a payment_setup_url, so the "Get started with payments" step in the GoCardless dashboard links to your product
• Your GoCardless account has contact details, so your users can see them
• Your GoCardless account is verified, so you can receive revenue share or app fees

Connect your merchants#

Let your users connect their GoCardless account to your platform with OAuth.

• Connected merchants can see their account name, account ID, and verification or connection status
• Connected merchants can disconnect
• Connected merchants can configure the integration after connecting, such as when payments are collected or how failed payments are handled
• Your integration uses the OAuth flow to connect merchant accounts
• Your integration offers both sign-up and login entry points, using initial_view
• Your integration prefills each user's details in the OAuth flow (prefill[email], prefill[given_name], prefill[organisation_name] and so on)
• Your integration exchanges the code for an access token on your server, and stores the token securely. Your client secret never reaches a browser or device
• Your integration stores each merchant account's organisation_id with its access token. You need it to match webhooks to the right account
• Your integration handles disconnections: the organisations webhook with action disconnected. Its event id is null, so make sure your duplicate check doesn't reject it

Verify your merchants#

Check whether your users are verified, and help them finish onboarding. This is mandatory before they can start collecting payments and receiving payouts.

• Connected merchants who aren't verified see a message, like a banner on your home page, telling them they can't collect payments or receive payouts until they do
• Your integration checks each merchant's verification_status after they connect, and refreshes it regularly
• Your integration sends merchants with the status action_required to the verification flow, and shows a message to those in_review

Webhooks#

Handle events for all your users on one endpoint, including events your integration didn't trigger.

• Your integration verifies the signature of every webhook
• Your integration processes each event only once. Webhooks can be delivered more than once
• Your integration processes each event in a webhook separately. A webhook can carry up to 250 events
• Your integration matches events to connected merchants by links.organisation
• Your integration queues events for background processing, so your endpoint responds quickly
• Your integration handles events it didn't trigger, like payments your users create in the GoCardless dashboard, without failing
• Your integration fetches a resource's current state before acting on its events, since events can arrive out of order
• Your integration lists recent events to catch any it missed, after downtime and on a regular schedule

Mandates#

Let your users ask payers for a mandate, so they can collect Direct Debit payments from them.

• Connected merchants can request a mandate from a customer record or from a transaction, by email or with a link
• Connected merchants can see each mandate's status, reference and bank account on the customer page
• Connected merchants can share a mandate link that isn't tied to a customer, in emails or on their website
• Connected merchants can send mandate requests in bulk, to onboard many payers at once
• Connected merchants can remind payers who haven't set up their mandate yet
• Connected merchants can preview mandate request emails, and edit the copy
• When your user creates a bill or invoice for a customer without a mandate, your product says so and offers to request one
• Your integration stores the mandate ID against the customer record, from links.mandate_request_mandate in the Billing Request fulfilled event
• Your integration sends payers to GoCardless hosted payment pages, or to custom pages that have passed our compliance review
• Your integration prefills the payer's details, and bank details if you have them, on the payment page
• Your integration shows payers a confirmation page that explains what happens next
• Your integration handles failed, cancelled, expired and replaced mandates: it updates the status, tells the merchant, and for replaced, stores the new mandate ID
• Your integration validates bank details with the Bank Details Lookups API, if merchants pass them to you
• Your integration handles the transferred event when a payer switches bank account. The API only shows the last few digits of the new account number

Import mandates#

Let merchants who had GoCardless before connecting to you link their existing mandates to customer records in your product.

• Connected merchants can import their existing mandates and match them to customers in your product
• Connected merchants can see matched and unmatched mandates at any time, not only during setup, from your GoCardless settings page
• Connected merchants can unmatch a mandate
• Your integration matches mandates automatically by email, then by metadata, and lets your users review anything that doesn't match

Collect payments#

Let your users collect payments by Direct Debit or Pay by Bank.

• Connected merchants can collect one-off and recurring Direct Debit payments
• Connected merchants can collect payments with Pay by Bank
• Connected merchants can view payment statuses and IDs directly from their list views and individual records
• Connected merchants can pick a charge_date to schedule payments
• Connected merchants can take an instant first payment with a mandate (dual flow)
• Connected merchants can split a transaction into instalments
• Connected merchants can add a "Pay with Direct Debit" or "Pay by Bank" button to what they send payers, like invoices
• Your integration collects payments from payers who already have a mandate, without asking them again
• Your integration stores the payment ID against the corresponding record. If a Billing Request creates it, use links.payment_request_payment
• Your integration uses idempotency keys when creating payments and mandates

Failed payments and refunds#

Help your users deal with failed payments, and let them cancel or refund payments.

• Connected merchants can refund a payment, and see the refund's status
• Connected merchants can cancel a payment before it's submitted
• Connected merchants can see why a payment failed, and manually retry it
• Connected merchants can resend the mandate request when a payment fails because of a mandate issue
• Your integration shows your users when a payment fails, independently from your internal record status (such as a bill or order)

Reconcile#

Keep each record in your platform up to date with its payment, through to the payout.

• Your integration automatically updates record statuses based on payment events: marking items as paid when the payment is confirmed, reopening them if a payment is charged_back or fails late, and updating them once paid_out
• Your integration reconciles payouts using payout items, and posts GoCardless fees as expenses

Enhancements#

These are optional. Add them to improve payment success rates and payer conversion.

• Your integration supports Success+, which retries failed payments automatically, and shows your users when a retry is happening (resubmission_requested, will_attempt_retry)
• Your integration supports Protect+, which protects merchants from fraud. It sets verify to recommended when it creates Billing Requests
• Your integration proactively alerts your users when a payment fails, by email, in-app notification or by showing payment status
• Your integration supports outbound payments, so your users can send money
• Your integration uses Components to show our payment page components on your own pages
• Connected merchants can choose which bank or ledger accounts receive GoCardless payouts and fees

Promote#

Make your integration easy to find and understand, so your users actually use it.

• Your platform follows the design guides for where to add your features and how to talk about them
• Your platform suggests GoCardless at the right moments: during onboarding, when adding a customer, when creating a bill or invoice, on your payment settings page, and when they're dealing with a problem GoCardless solves, like overdue transactions or manual reconciliation
• Your platform uses the GoCardless brand assets
• Your platform has a landing page and a user guide, and mentions GoCardless in your FAQs and welcome emails

What's next?#