Skip to main content

Data Source

The GoCardless API connector enables you to ingest payment data — including payments, mandates, customers, subscriptions, payouts, refunds, and events — directly from your GoCardless account into Nexla data flows. Follow the instructions below to create a new data flow that ingests data from a GoCardless API source in Nexla.
go_cardless_api.png

GoCardless API

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the GoCardless API connector tile from the list of available connectors. Then, select the credential that will be used to connect to GoCardless, and click Next; or, create a new GoCardless API credential for use in this flow.

  3. In Nexla, GoCardless API data sources can be created using pre-built endpoint templates, which expedite source setup for common GoCardless API endpoints. Each template is designed specifically for the corresponding GoCardless API endpoint, making data source setup easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    GoCardless API sources can also be configured manually, allowing you to ingest data from GoCardless API endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common GoCardless API endpoints. Each template is designed specifically for the corresponding GoCardless API endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    List Payments

    Returns a list of all payments in the GoCardless account, useful for financial reporting and payment status monitoring.

    • Sends a GET request to the GoCardless payments endpoint and returns an array of payment objects.
    • Response data is located at $.payments[*].

    No parameters are required. For incremental pulls, use the Date/Time Macros feature to filter payments by creation date using the created_at[gte] query parameter.

    List Refunds

    Returns a list of all refunds issued in the GoCardless account, useful for reconciliation and customer service workflows.

    • Sends a GET request to the GoCardless refunds endpoint and returns an array of refund objects.
    • Response data is located at $.refunds[*].

    No parameters are required. Each refund record includes the amount, associated payment, and refund status.

    List Mandates

    Returns a list of all mandates in the GoCardless account, representing authorized Direct Debit agreements with customers.

    • Sends a GET request to the GoCardless mandates endpoint and returns an array of mandate objects.
    • Response data is located at $.mandates[*].

    No parameters are required. Mandate status (e.g., active, cancelled, failed) is included in each record.

    List Payouts

    Returns a list of payouts made from GoCardless to your bank account, useful for reconciling settlement activity.

    • Sends a GET request to the GoCardless payouts endpoint and returns an array of payout objects.
    • Response data is located at $.payouts[*].

    No parameters are required. Each payout record includes the amount, currency, arrival date, and associated payment IDs.

    Retrieve Account Metadata

    Retrieves metadata information for a specific bank account via the GoCardless Bank Account Data API.

    This endpoint uses the GoCardless Bank Account Data (Open Banking) API, which requires a separate access token from the standard GoCardless API. Ensure your credential is configured for bank account data access.

    Retrieve Account Balances

    Retrieves current balance information for a specific bank account via the GoCardless Bank Account Data API.

    Returns both booked and available balance types where provided by the institution. Requires bank account data (Open Banking) access credentials.

    Retrieve Account Details

    Retrieves detailed information about a specific bank account, including IBAN, account name, and owner details.

    The level of detail returned varies by financial institution and the data they share via Open Banking. Requires bank account data access credentials.

    Retrieve Account Transactions

    Retrieves transactions for a specific bank account within an optional date range, returning booked transaction records.

    Date From and Date To are optional. Use date/time macros in the URL for incremental transaction pulls. Requires bank account data access credentials.

    Retrieve End-User Agreement

    Retrieves details of a specific end-user agreement (EUA) by its ID, including consent scope and access duration.

    End-user agreements define the scope and duration of bank account data access. Monitor expiry dates to refresh consent before access lapses.

    Accept End-User Agreement

    Accepts a pending end-user agreement using user agent and IP address information, completing the consent process.

    All three parameters are required. User Agent and IP Address are used to record the acceptance context for compliance purposes.

    Retrieve EUA Reconfirmation

    Retrieves reconfirmation details for a specific end-user agreement, used to manage ongoing consent for bank account data access.

    Reconfirmation is required periodically for some institutions to maintain ongoing access to bank account data under Open Banking regulations.

    List Supported Institutions

    Retrieves all financial institutions supported by GoCardless Bank Account Data, with optional filtering by country and supported capabilities.

    • Sends a GET request to https://bankaccountdata.gocardless.com/api/v2/institutions/ with optional filter parameters and returns an array of institution objects.
    • Response data is located at $[*] (the top-level array).
    • Configure the following parameters: Country Code — filter by two-letter country code; additional boolean filters for account types and capabilities such as Business Accounts Supported, Card Accounts Supported, Pending Transactions Supported, and others.

    All parameters are optional. Use the Country Code filter to narrow results to institutions operating in a specific country.

    Get Institution

    Retrieves details for a specific financial institution supported by GoCardless Bank Account Data by its unique ID.

    Institution IDs can be obtained via the List Supported Institutions endpoint. Each institution record includes its name, logo, and supported capabilities.

    Get Requisition

    Retrieves details for a specific GoCardless Bank Account Data requisition, which represents a user's bank linking session.

    Requisitions contain the list of account IDs that were linked by the user. Use the returned account IDs with the account-level endpoints to retrieve balances and transactions.

    List Customer Bank Accounts

    Lists all customer bank accounts registered in the GoCardless account, used for Direct Debit mandate creation.

    • Sends a GET request to the GoCardless customer bank accounts endpoint and returns an array of customer bank account objects.
    • Response data is located at $.customer_bank_accounts[*].

    No parameters are required. Customer bank account IDs are needed when creating new mandates.

    List Customers

    Lists all customers in the GoCardless account, providing a complete view of the customer base for reporting and analysis.

    • Sends a GET request to the GoCardless customers endpoint and returns an array of customer objects.
    • Response data is located at $.customers[*].

    No parameters are required. Each customer record includes contact details, creation date, and associated bank accounts and mandates.

    List Subscriptions

    Lists all subscriptions in the GoCardless account, representing recurring payment schedules set up against mandates.

    • Sends a GET request to the GoCardless subscriptions endpoint and returns an array of subscription objects.
    • Response data is located at $.subscriptions[*].

    No parameters are required. Each subscription record includes the amount, interval, start date, and associated mandate ID.

    List Events

    Lists all audit events in the GoCardless account, capturing state changes across payments, mandates, subscriptions, and other resources.

    • Sends a GET request to the GoCardless events endpoint and returns an array of event objects.
    • Response data is located at $.events[*].

    No parameters are required. Events are useful for building audit trails and triggering downstream workflows based on payment state changes. Consider using date-range filtering for incremental ingestion.

    List Payout Items

    Lists all line items within a GoCardless payout for detailed reconciliation of settlement activity.

    • Sends a GET request to the GoCardless payout items endpoint and returns an array of payout item objects.
    • Response data is located at $.payout_items[*].

    No parameters are required. Each payout item represents an individual payment or fee included in a settlement payout.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

GoCardless API sources can also be configured to ingest data from any valid GoCardless API endpoint. The GoCardless REST API base URL is https://api.gocardless.com for the live environment and https://api-sandbox.gocardless.com for sandbox. Common endpoints include resources such as payments, mandates, customers, subscriptions, payouts, refunds, and events.

First, select the method that will be used for calls to the GoCardless API from the Method pulldown menu. The most common method for data ingestion is:

  • GET: For retrieving lists of resources or individual resource details from GoCardless.
  • POST: For triggering actions or filtering list endpoints that require a request body (some GoCardless list endpoints accept filter parameters via POST).

API Endpoint URL​

  1. Enter the URL of the GoCardless API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

    Some commonly used GoCardless API endpoints for data ingestion include:

    • https://api.gocardless.com/payments — List all payments with optional filters for status, mandate, customer, or date range.
    • https://api.gocardless.com/mandates — List all mandates, optionally filtered by customer, customer bank account, or status.
    • https://api.gocardless.com/customers — List all customers in your GoCardless account.
    • https://api.gocardless.com/subscriptions — List all subscriptions, optionally filtered by mandate or customer.
    • https://api.gocardless.com/payouts — List all payouts made to your bank account.
    • https://api.gocardless.com/refunds — List all refunds issued.
    • https://api.gocardless.com/events — List all events, useful for building audit trails or tracking status changes across all resource types.

    GoCardless returns paginated responses. Most list endpoints return results nested under a key matching the resource type (for example, payments, mandates, customers). Use the Path to Data field to extract just the resource array from each response.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros — all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that adapt to different time periods or data requirements. This is particularly useful with GoCardless endpoints that support date-range filtering, such as created_at[gte] and created_at[lte] query parameters.

For example, to ingest only payments created within the last day, you could construct a URL such as https://api.gocardless.com/payments?created_at[gte]={'{now-1}'} using date/time macros.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime — for example, enter (now-7) to indicate the datetime seven time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro — i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu — for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that adapt based on existing data. This is useful when you need to retrieve GoCardless records for specific customer IDs, mandate IDs, or payment IDs sourced from another Nexla dataset.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

GoCardless API responses wrap resource arrays under a top-level key matching the resource name. For example, a request to /payments returns a response with the structure {"payments": [...], "meta": {...}}. By specifying the path to the relevant data, you instruct Nexla to treat each element of the resource array as a record rather than the entire response object.

Specifying the correct path to data is strongly recommended for GoCardless sources. Without it, Nexla will treat the entire response object (including pagination metadata) as a single record rather than ingesting each payment, mandate, or other resource as an individual record.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For the /payments endpoint, enter $.payments[*] to extract each payment as a record.
    • For the /mandates endpoint, enter $.mandates[*].
    • For the /customers endpoint, enter $.customers[*].
    • For the /subscriptions endpoint, enter $.subscriptions[*].
    • For the /events endpoint, enter $.events[*].
    Path to Data Example:

    If fetching payments from https://api.gocardless.com/payments, the API response includes a top-level array named payments that contains the payment records. The path to the response should be entered as $.payments[*].

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the GoCardless API endpoint. Suggested data paths generated based on the content and format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. GoCardless list responses include a meta object that contains pagination cursor information (cursors.before and cursors.after). This metadata can be useful for tracking pagination state or enriching records with response-level context.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For GoCardless JSON responses, enter the JSON path to the object or array that contains the metadata (for example, $.meta).

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers and corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers may be required for GoCardless API versioning — GoCardless recommends including a GoCardless-Version header to pin your integration to a specific API version and avoid breaking changes.

    You do not need to include the Authorization header here, as it is handled automatically by Nexla based on your GoCardless credential configuration. Common headers to consider for GoCardless include GoCardless-Version (e.g., GoCardless-Version:2015-07-06) to specify the API version your integration targets.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows you to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched and displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new GoCardless API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.