GoCardless

Swallow's native integration with direct debit providers allows you to collect payments via direct debit.

Integration setup

Connect your GoCardless account

To connect to GoCardless through the user interface:

1. Navigate to the settings section in Swallow

2. Select the "Integrations" page

3. Click "Connect to GoCardless" to create a connection

4. Give a name to this connection

5. Click on "Connect" to be redirected to the GoCardless website

6. Create a GoCardless account or log in to your existing account

7. Connect your account to be redirected back to Swallow

When the OAuth connection is active, you will see a screen with your secret key.

Create webhook endpoints

To complete this process, you will need:

• Your Swallow company reference, available in the "API keys & ID" tab of the "Developers" section; and

• Your secret key, available in the "Integrations" tab of the "Settings" section (learn more).

If you want Swallow to automatically retrieve the status of the payments processed via GoCardless, you must create a webhook endpoint in GoCardless. To do so:

1. Log in to your GoCardless account;
2. Go to the "Developers" section;

3. In the upper right corner, click "Create" and then select "Webhook endpoint";

4. Choose a name for this webhook (e.g. Swallow);

5. Enter the following URL: https://api.llow.io/sw/webhooks/gocardless/{{company_reference}}?code={{connection_code}} (you must replace company_reference with your Swallow company reference, and the connection_code by the targeted Swallow connection);

6. Enter your secret key; and

7. Click "Create webhook endpoint".

In addition to this, you must create a webhook endpoint in Swallow to retrieve the quote URL associated with each customer account (learn more). To do so:

1. Go to the "Settings" section of the Swallow application;

2. Navigate to the "Webhooks" tab;

3. Click "Add a webhook" on the right;

4. Enter your webhook URL; and

5. Click "Add webhook" to confirm.

For more information about our webhooks, please refer to the API documentation.

Redirect url after quote completion

After establishing the connection with GoCardless, set a "next button URL" where your end customer will be directed after completing the quote. Please note that if it's not defined, your end customer will be redirected to GoCardless's website.

Please note that you can edit or delete the redirect URL, and this will only affect new quote URLs created.

URL defined should always begin with `http://` or `https://`.

Customer information

To collect payments automatically, the customer must exist in both the Swallow and GoCardless databases.

New customer

If the customer does not already exist in GoCardless, you can first create them in Swallow, either via the user interface or the API. When adding customer information, you must:

1. Provide the customer's email address;

2. Define GoCardless as the default payment provider;

3. Select the GoCardless connected account;

4. Leave the field associated with the GoCardless customer ID blank; and

5. Enable the option to automatically create the customer in GoCardless.

The customer will automatically be added to GoCardless. GoCardless will then return the customer ID, which will be stored in Swallow.

When the customer is successfully created, you will receive two webhook messages:

• customer.payment_provider_created that confirms the creation of the customer in GoCardless; and

• customer.checkout_url_generated that includes the quote URL to set up the direct debit (learn more).

Existing customer

If the customer and direct debit mandate already exist in GoCardless, then you should create the customer record in Swallow, either via the user interface or the API. When adding customer information, you must:

1. Provide the customer's email address;

2. Define GoCardless as the default payment provider;

3. Select the GoCardless connected account;

4. Provide the GoCardless customer ID; and

5. Disable the option to automatically create the customer in GoCardless.

Direct debit

To collect payments via direct debit, a mandate must be created. To do so:

1. Retrieve the quote URL included in the customer.checkout_url_generated webhook; and

2. Redirect your customer to the quote page, so that they can complete the online form and approve the mandate.

The mandate must be validated by GoCardless before the first payment can be processed. It can take up to six business days to validate a new mandate. For more information about payment timings, please consult the GoCardless FAQ.

To collect payments via direct debit, the currency of the mandate must match the currency of the plan associated with the customer's subscription.

Each time a new quote with an amount greater than zero is generated by Swallow, a payment will automatically be created. GoCardless will record the quote reference and process the payment. Payments via direct debit are usually processed within five business days. If the payment is successful, the status of the payment will switch from pending to succeeded.

If the payment fails, the status of the payment will switch from pending to failed and Swallow will generate a quote.payment_failure webhook.

If you have signed up for [GoCardless Success+](https://gocardless.com/solutions/success-plus/), failed payments may be automatically resubmitted, in which case Swallow will automatically update the quote payment status.

Regenerate quote link on demand

In cases where your end customer has not had the opportunity to complete the quote process to inform their payment method or wishes to modify the saved payment information, you can generate a new quote link using the designated endpoint.

POST /sw/customers/:customer_reference/checkout_url

Upon successful generation, the new quote link will be available in the endpoint response, and it will not be delivered through a webhook message. It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.