Testing Your Integration#

Before you go live, test your partner integration in the GoCardless sandbox environment. Sandbox works like the live environment, but no real money moves and you can trigger events that your integration must be able to handle, but that are not easily reproducible in live production.

This page acts as a guide for testing:

• The OAuth flow that connects a merchant to your app
• Webhook handling for the events in Webhooks for Partners
• Importing mandates from outside your partner integration

In addition to the above, you should also be independently validating that all data is being displayed correctly in your partner app and that merchants are able to complete all the actions outlined in the Integration Guide.

Test accounts#

A partner integration involves two kinds of organisations, and you need both to test it end to end:

This guide assumes you have created your partner app in a sandbox account. If you do not have access to a sandbox account with a live app, please see Partner Integrations - Before you start.

Create a merchant test account#

Create a second sandbox account with a different email address to your partner account. For testing, this will act as your merchant.

Test the OAuth flow#

As part of your integration you should have built a way to generate links to the OAuth flow using your app's client_id, client_secret and redirect_uri.

1. Connect your merchant test account#

Go through the OAuth flow via your app and sign in as your merchant test account. This should connect your merchant account to your app.

2. Check what your integration stores#

Verify that you are retrieving and storing the app access token from this connection, along with the GoCardless organisation ID of the connected merchant in your system.

3. Test each connection scenario#

If any of these scenarios produce unexpected results, refer back to Connect your merchants.

Test webhook handling#

Your partner integration should be set up to appropriately handle the events listed in Webhooks for Partners.

The following steps walk you through how to trigger these events from the sandbox environment.

1. Choose how to trigger events#

There are three ways to trigger events in the sandbox environment:

For testing against a local instance of your partner integration, the GoCardless CLI is recommended as it allows you to forward webhooks to your local handler, and will print logs of all generated events.

2. Trigger events#

Use the methods from the previous step to trigger the events your integration handles. See Key events for a list of events and their suggested handling.

Trigger events with the GoCardless CLI#

1. Install the GoCardless CLI

2. Log in using your merchant test account

3. Listen for webhooks. If running your integration locally, forward webhooks to your local instance.

You can then use the CLI to trigger events which your integration should handle appropriately.

The GoCardless CLI can create resources or transition existing resources. Run gocardless trigger --help for a full list of supported actions.

See Testing webhooks (CLI) for more information.

Trigger events with the scenario simulator#

You can use the dashboard or API triggered scenario simulator to transition resources in your merchant test account. The events from these transitions will be sent to your app's webhook URL for processing.

For more information see Scenario Simulator

Trigger events with Send test webhook#

For events that are not covered by the GC CLI triggers or the scenario simulator (e.g. payment.chargeback_cancelled), you can send test webhooks directly to your integration via the dashboard Send test webhook feature.

3. Test routing and reliability#

Run these checks as well as the individual events to verify the security and reliability of your integration:

Test mandate imports#

Merchants who already use GoCardless have mandates that exist before they connect to your app. Your integration should be able to find these mandates after the OAuth connection, match them to customers in your product, and store the mandate links. See Supporting mandates set up outside of your product for how to build this.

To test it, you need mandates to exist in the merchant test account before you connect it to your app. The steps below follow that order.

1. Use a merchant account that isn't connected#

The import flow runs when a merchant connects, so you need a merchant test account with no connection to your app. Do one of the following:

• Create a new merchant test account, as described in Create a merchant test account.
• Revoke your app in the dashboard of a merchant account you've already connected. Your integration should handle the disconnection webhook.

2. Create mandates in the merchant account#

Create mandates using the GoCardless CLI or the scenario simulator. Create enough mandates to cover each case your import handles:

Create mandates with the GoCardless CLI#

1. Log in to the CLI using the merchant test account.

2. Create a customer with the details you want your integration to match on:

   gocardless create customers \
     -d given_name=Alex \
     -d family_name=Example \
     -d email=alex@example.com \
     -d postal_code=E1+1AA \
     -d country_code=GB \
     -d address_line1=Example+Street \
     -d city=London

3. Trigger a mandate for that customer. The CLI creates the bank account and mandate, and activates the mandate:

   gocardless trigger mandate_activated customer=CU123

   Replace CU123 with the customer ID from the previous step.

4. Repeat for each case in the table. To create a mandate with an auto-generated customer, run gocardless trigger mandate_activated with no arguments.

To create a mandate in a different state, use another trigger such as mandate_failed, mandate_expired or mandate_pending_submission. Run gocardless trigger --help for the full list. See the CLI reference for details.

Create mandates with the scenario simulator#

1. Create a customer, bank account and mandate in the merchant test account, using the dashboard or the API. A new mandate starts in pending_submission.

2. Use the scenario simulator to move the mandate to the state you want to test. For example, run the mandate_activated simulator against the mandate ID, from the dashboard or the API.

3. Connect the merchant account to your app#

Before you connect, confirm the mandates exist by running gocardless list mandates or checking the sandbox dashboard.

Go through the OAuth flow from your app and sign in as the merchant test account.

4. Sync the mandates in your app#

In your app, start the sync, for example by selecting Sync Existing Mandates. Then check the following:

If any of these produce unexpected results, refer back to Supporting mandates set up outside of your product.

What's next?#