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 & account#

Set up your partner app and your own GoCardless account before you connect any users.

• Your partner app has at least one redirect_uri.
• Your partner app has a clear, public-facing name. Your users see it when they connect, and it appears in our reporting.
• 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 via 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 your users' GoCardless 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 user's organisation_id with their access token. You need it to match webhooks to them.
• Your integration handles disconnections: the organisations webhook with action disconnected.

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 can see whether they're verified.
• Your integration checks each user's verification_status after they connect, and refreshes it regularly.
• Your integration sends users 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 matches events to connected merchants by links.organisation.
• Your integration queues events for background processing, so your endpoint responds quickly.

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.
• Connected merchants can see each mandate's status 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.
• Your integration stores the mandate ID against the customer record.
• 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 user, and for replaced, stores the new mandate ID.
• Your integration validates bank details with the Bank Details Lookups API, if your users pass them to you.
• Your integration handles the transferred event when a payer switches bank account. The API only shows the last 2 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.
• 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 see each payment's status on the transaction.
• 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 stores the payment ID against the transaction.
• 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.
• 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 notifies your users when a payment fails.

Reconcile#

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

• Your integration updates the transaction status when payment events arrive: it marks the transaction as paid when the payment is confirmed, re-opens it when the payment is charged_back, and updates it again when it's 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 your users from fraud. It sets verify to recommended when it creates Billing Requests.
• 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.

Promote#

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

• Your platform follows the UX guide 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 transaction, on your payment settings page.
• 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?#