Swallow
  • YOUR FIRST MODEL
    • Setting up your first project
    • Manual setup of a new product
    • Excel Model Upload
    • Create your team
    • Essential concepts
      • Syntax
      • Steps
      • Collections
      • Try Model
      • Spotlight
  • PROCESS
    • Team Management
    • Governance & Collaboration
  • BUILD
    • Building with AI
    • Step builder
      • Understanding step types
      • Ordering step blocks
      • Placeholder mode
      • Up/Downloading models
      • Sharing your model
      • Running tests
    • Inputs
    • Enriching Raw Data
      • Transform Data
      • Enrich via API
      • Data Set
      • Collection
      • Custom Code
    • Setting Up Decisions
      • Exclusions
      • Excesses
      • Endorsements
      • Refer
    • Making Calculations
      • Factors
      • Calculation
    • Outputs
  • TEST
    • Creating New Tests
    • Running Tests
    • Editing Tests
    • Reading & Interpreting Tests
    • Impact Testing
  • DATA
    • Working with real-time data
    • Data Views
    • Data Quotas
    • Troubleshooting
    • API Webhooks
    • Data Downloads
  • ADMIN & SETTINGS
    • Project Management
    • Account Management
  • INTEGRATIONS
    • Introduction
    • Payments
      • Stripe
      • GoCardless
      • Adyen
    • Alerting
      • Slack
      • Zapier
    • Data
      • AWS S3
      • Google Sheets
    • Admin
      • Socotra
      • Guidewire
      • Hubspot
      • Salesforce
  • Developer API
    • Introduction
    • Authentication
    • Errors codes
    • Endpoints
      • /quotes
      • /projects
      • /tests
      • /process
Powered by GitBook
On this page
  • Integration setup
  • Redirect url after quote completion
  • Customer information
  • Direct debit
  • Regenerate quote link on demand
  1. INTEGRATIONS
  2. Payments

GoCardless

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

PreviousStripeNextAdyen

Last updated 4 months ago

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. Go to the "Developers" section;

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

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

  4. 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);

  5. Enter your secret key; and

  6. 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.

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

  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.

  • 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

  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.

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 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

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.

Log in to your ;

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

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

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

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 . When adding customer information, you must:

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 .

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

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 .

GoCardless account
API documentation
the API
webhook messages
the API
GoCardless FAQ
webhook
endpoint