Customize Railz Connect

Explore the available settings to tailor Railz Connect to your connection journey's needs

🚧

Parameter Deprecation Notice

As part of the new Railz Connect v2.0 launch, some parameters from Railz Connect v1.0 have been deprecated and assigned to new fields. See deprecated legacy parameters below for details.

Still Using Our Legacy Railz Connect (v1)?

If you're still using our legacy version of Railz Connect (v1), see Railz Connect v1 for detailed setup instructions.

All customizable options for design and functionalities are controlled by the options that are entered directly as parameters into the Railz Connect™ script.

Here's an example:

import RailzConnect from '@railzai/railz-connect';
import {useEffect, useRef} from "react";

function App() {
  const ref = useRef();

  useEffect(() => {
    const widget = new RailzConnect();
    widget.mount({
      parentElement: ref.current,
      widgetId: '<Your Widget Id>',
      businessName: '<Your Business Name>',
      redirectUrl: 'https://www.railz.ai/success',
      closeRedirectUrl: 'https://www.railz.ai',
      metadata: [
        {
          name: "businessLocation",
          value: "canada",
          webhookLocation: ["header", "body", "query"]
        }
      ],
      // Add additional Railz Connect configuration parameters here
    });
  },[])
  return (
    <div id='railz-connect' ref={ref}></div>
  );
}

export default App;

Opening Railz Connect

Choose which method you want Railz Connect™ to open when integrating it in your application.

ParameterTypeDescription
widget.openfunctionUse this function to open Railz Connect™ as a modal on your application.
widget.mountfunctionUse this function to embed Railz Connect™ into your application.

Business Name

ParameterTypeDescription
businessNamestringThe unique identifier of the business as defined by you. If left as null, a unique identifier for the business will be assigned by Railz. The business name should be 2 to 40 characters long and must not contain any of the following special characters: {% [ ] \ *( ) { } "}\.

Brand Customization

The theme parameter is used to update Railz Connect's theme settings to match your brand guidelines and needs. The attributes you can use in the theme object are detailed below.

ParameterTypeDescription
logoobjectAn object containing logo definition.
Available on Enterprise plans only.
fontFamilystringA string containing font family.
Available on Enterprise plans only.
primaryobjectAn object containing the primary color definition.
Available on Pay as You Go plans and above.
secondaryobjectAn object containing the secondary color definition.
Available on Pay as You Go plans and above.

Logo Properties

ParameterTypeDescription
urlstringImage URL.
stylestringCSS Object for styling the img tag.
Defaults to: {maxHeight: '50px'}

Primary Color Properties

Customize the primary CTA button colors by setting the primary parameter.

ParameterTypeDescription
backgroundstringA string containing a color hex code for the button's background.
Defaults to: #000000.
backgroundHoverstringA string containing a color hex code for the button's hover state background.
backgroundActivestringA string containing a color hex code for the button's active state background.
foregroundstringA string containing a color hex code for the button's foreground (text color).
foregroundHoverstringA string containing a color hex code for the button's active state foreground.
foregroundActivestringA string containing a color hex code for the button's active state foreground.

Secondary Color Properties

Customize the color of links and borders by setting the secondary parameter.

ParameterTypeDescription
backgroundstringA string containing a color hex code.
Defaults to: #38C076.

Redirects

Railz Connect™ will redirect the end user to a Railz-branded landing page once their account was successfully connected. We recommend setting the redirect URL to your custom landing page, which can be a Thank You page or a landing page specific to the next step in your process.

ParameterTypeDescription
redirectUrlstringThe URL to redirect to when the end user has successfully finished connecting the service providers required.
closeRedirectUrlstringThe URL to redirect to when the end user exits Railz Connect by closing the page. Should be used in conjunction with options.components.close=true.

Layout & Content Customization

The parameter options is used to update both the components' visibility and text content and overall service provider settings present in Railz Connect™.

ParameterTypeDescription
servicesobjectThe services object is used to configure service provider settings specific to the current Railz Connect session. See Service Providers Customization for detailed attributes.
kindsobjectThe kinds object is used to configure the business rules related to the different types of service providers. See Service Providers Customization for detailed attributes.
componentsobjectThe components object is used to hide or display specific components in Railz Connect™. See Layout Customization for detailed attributes.
contentobjectThis content object is used to change the text of specific fields in Railz Connect™. See for Content Customization detailed attributes.
Available on Enterprise plans only.

Service Providers Customization

Excluding Service Providers

You may pass a list of service providers you wish to exclude from Railz Connect™ via the options.services.exclude. This configuration will remove these service providers from the Railz Connect™ interface.

ParameterTypeDescription
excludearrayUsed to pass in the list of service providers to exclude from the Railz Connect session. See supported integrations enum values

Making Service Providers Required

The options.kinds.hideSkip array will allow you to mark types of service providers as required to complete the connection journey.

ParameterTypeDescription
hideSkiparrayUsed to pass in the list of services to mark required in the Railz Connect session. Valid values are banking and commerce.

📘

For example, options.kinds.hideSkip = ['commerce'] will require business customers to have at least one successful commerce /connection. By default, accounting service providers are required, however if you do not have any accounting integrations enabled, your business customers would be able to proceed to other enabled service providers.

Layout Customization

The components object parameter will allow you to control the layout of Railz Connect through a set of attributes in the table below.

ParameterTypeDescription
searchbooleanTo show/hide the search bar in the service provider selection page.
Defaults to: true
closebooleanTo show/hide a close button to Railz Connect™, closeRedirectUrl is required, which will redirect the end user to the provided URL when they click close.
Defaults to: false
sandboxbooleanYou can show/hide the sandbox banner when in sandbox mode using this parameter.
Defaults to: true
headerbooleanYou can show/hide the text from the header by specifying this parameter.
Defaults to: true
watermarkbooleanYou can use this parameter to show/hide the Railz logo.
Defaults to: true
Available on Enterprise plans only.
termsbooleanYou can use this parameter to show/hide the Railz terms and conditions.
Defaults to: true
Available on Enterprise plans only.
helpLinkbooleanYou can use this parameter to show/hide the need help link in the overview page and pages for service providers like Sage Intacct, Quickbooks Desktop, and Oracle Netsuite.
Defaults to: true
Available on Enterprise plans only.
overviewbooleanTo show/hide the overview page in the connection journey.
Defaults to: true
summarybooleanTo show/hide the summary page in the connection journey.
Defaults to: true
progressBarbooleanAble to show/hide the progress bar in the connection journey
Defaults to: true
navigableProgressBarbooleanAble to make the progress bar selectable and act as a navigation.
Defaults to: true
backbooleanAble to hide the back CTA in all of the Railz Connect™️ pages.
Defaults to: true

Content Customization

🚧

Available on Enterprise plans only.

The content object parameter will allow you to control the content displayed in Railz Connect through a set of attributes below.

Changing your Company or App Name

Customize the company or application name your end users will see in Raiz Connect by setting the companyName parameter in content object.

ParameterTypeDescription
companyNamestringName of company or application name to display in Railz Connect. Defaults to: Company name set in Railz Dashboard.

Changing Terms & Conditions Content

Customize the terms & conditions displayed to your end users in Railz Connect by setting the terms parameter in content object. The terms parameter is an object with the following attributes.

ParameterTypeDescription
terms.markupstring | HTMLMarkup in the footer to display a reference to the terms and privacy text/links.
Defaults to:
"<b style='font-weight: bold !important'>You will be asked to connect your account and authorize <i style='font-style: italic !important'>{{customerName}}</i> to access your financial data.</b> By selecting a service provider above, you are agreeing to the "
terms.linkstring Link to the page containing terms and privacy. Pass as null to hide the suffix link.
Defaults to: Railz Connect internal terms page.
terms.linkTextstringThe terms and privacy link text label.
Defaults to: Railz Terms & Conditions.
terms.linkTypeenum external \ nullType of link to indicate if the link should reference an external page or Railz Connect internal terms page.
Defaults to: null.

Changing Overview & Summary Pages Content

Customize the content displayed to your end users on the Railz Connect overview and summary pages by setting the step and helpLink parameters in content object.

ParameterTypeDescription
step.overview.titlestringText to display as the title on the overview page.
Defaults to: Share Financial Information.
step.overview.subTitlestringText to display as the subtitle on the overview page.
Defaults to: You will be asked to connect your account to the following services and authorize <strong>{{customerName}}</strong> to access your financial data..
step.overview.serviceKindTitles.accountingstringText to display as the accounting service provider title on the overview page.
Defaults to: Accounting Services
step.overview.serviceKindTitles.bankingstringText to display as the banking service provider title on the overview page.
Defaults to: Banking Services
step.overview.serviceKindTitles.commercestringText to display as the accounting service provider title on the overview page.
Defaults to: Commerce Services
step.summary.titlestringText to display as the title on the summary page.
Defaults to: Financial Information Summary.
step.summary.subTitlestringText to display as the subtitle on the summary page.
Text to display as the title on the summary page.
Defaults to: You have successfully connected to the following services:.
step.summary.serviceKindTitles.accountingstringText to display as the accounting service provider title on the summary page.
Defaults to: Accounting Services
step.summary.serviceKindTitles.bankingstringText to display as the banking service provider title on the summary page.
Defaults to: Banking Services
step.summary.serviceKindTitles.commercestringText to display as the accounting service provider title on the overview page.
Defaults to: Commerce Services
step.summary.skippedKindstringText to display for skipped services in connection journey.
Defaults to: Skipped
helpLink.linkTextstringThe get help link text label displayed on service provider pages like Sage Intacct, Quickbooks Desktop, and Oracle Netsuite.
Defaults to: Need help?.
helpLink.linkLocationstringLink to the help page.

Changing Service Provider Select Page Content

Customize the content displayed to your end users on the service provider selection page in Railz Connect by setting the serviceSelect parameter in content object. The serviceSelect parameter is an object with the following attributes.

ParameterTypeDescription
titlestringText to display as the title on the service provider selection page.
Defaults to: Select your service.
subTitlestringText to display as the subtitle on the service provider selection page.
Defaults to: Select or search for a service you wish to connect.
subTitleNoSearchstringText to display as the subtitle when the search field is hidden on the service provider selection page.
Defaults to: Select a service you wish to connect.
searchLabelstringText to display as the search label on the service provider selection page.
searchPlaceholderstringText to display as the search placeholder on the service provider selection page.
Defaults to: Search.
searchNoResultstringText to display if user search does not return results.
Defaults to: No results found for <type of service>

Note:
You can only replace the text prefix to (<type of service>).
connectedstringText to display on the service provider card if it is connected.
Defaults to: Connected
disconnectedstringText to display on the service provider card if it is disconnected.
Defaults to: Disonnected.
buttonstringText to display in the primary CTA button on the service provider selection page.
Defaults to: Continue.
redirectButtonstringText to display in the redirect CTA button when the connection is completed and a redirectUrl was provided.
Defaults to: Done.
loadingTitlestringText to display when connecting to a service provider is in progress.
Defaults to: Please wait while we connect to your account..

Changing Manual Service Providers Page Content

Customize the content displayed to your end users on the service provider pages requiring manual steps (non-oAuth, e.g. QuickBooks Desktop, Oracle NetSuite) by the end users by setting the manualAccountConnect parameter in content object. The manualAccountConnect parameter is an object with the following attributes.

ParameterTypeDescription
titlestringText prefix to display beside the service provider name on the manual connect page.
Defaults to: Configure.
stepTitlestringText to display as the label of the step on the manual connect page.
Defaults to: Step.
shopify.titlestringText to display as the title on the connect Shopify page.
Defaults to: Connect your store.
shopify.subTitlestringText to display as the subtitle on the connect Shopify page.
Defaults to: Please provide your Shopify domain name..
shopify.maxCharacterHelperTextstringText to display as the text field helper message on the connect Shopify page.
Defaults to: Domain name must be more than or equal to 4 characters..
shopify.minCharacterHelperTextstringText to display as the text field helper message on the connect Shopify page.
Defaults to: Domain name must be less than or equal to 60 characters..
buttonstringText to display in the CTA button on the manual connect page.
Defaults to: Next.
copiedTextstringText to display when a user copies the QuickBooks Desktop password on the manual connect page.
Defaults to: Copied to clipboard!.

Changing Account Selection Page Content

Customize the content displayed to your end users on the account selection page for service providers like FreshBooks by setting the accountSelection parameter in content object. The accountSelection parameter is an object with the following attributes.

ParameterTypeDescription
titlestringText to display as the title with the service provider name when selecting an account.
Defaults to: Select <Service> Account.

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}
subTitlestringText to display as the subtitle with the service provider name when selecting an account.
Defaults to: Choose the <Service> Account that you would like to connect to.

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}
buttonstringText to display in the CTA button on the account select page.
Defaults to: Continue.

Changing Confirmation & Error Messages Content

Customize the general confirmation and error messages displayed to end users in Railz Connect by setting the parameters below in the content object.

ParameterTypeDescription
success.titlestringText to display as the title on the success page.
Defaults to: Success.
success.subTitlestringText to display as the subtitle on the success page.
Defaults to: Your <Service> Account \<account_name> has been securely linked to \<company_name>.

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}.

To use the correct account name use {{accountName}} in the value passed, for example, Custom text {{accountName}}.

You can only replace the text prefix to \<company_name>.
success.shopifySubTitlestringText to display as the subtitle on the Shopify success page.
Defaults to: Your <Service> Store \<store_name> has been securely linked to \<company_name>.

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}.

To use the correct account name use {{accountName}} in the value passed, for example, Custom text {{accountName}}.

You can only replace the text prefix to \<company_name>.
success.buttonstringText to display in the CTA button on the success page. Only present when there is a redirectUrl and when there are additional services apart from accounting services.
Defaults to: Done.
success.linkstringText to display as the add another service link on success page. Only present when there are additional service providers apart from accounting services.
Defaults to: Add another service.
duplicate.titlestringText to display as the title on the duplicate connection page.
Defaults to: Success.
duplicate.subTitlestringText to display as the subtitle on the duplicate connection page.
Defaults to: Your <Service> Account \<account_name> is already linked to \<company_name>.

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}.

To use the correct account name use {{accountName}} in the value passed, for example, Custom text {{accountName}}.

You can only replace the text prefix to \<company_name>.
duplicate.shopifySubTitlestringText to display as the subtitle on the Shopify duplicate connection page.
Defaults to: Your <Service> Store \<store_name> is already linked to \<company_name>..

Note:
To use the correct service name, use {{serviceName}} in the value passed, for example, Custom text {{serviceName}}.

To use the correct account name use {{accountName}} in the value passed, for example, Custom text {{accountName}}.

You can only replace the text prefix to \<company_name>.
duplicate.buttonstringText to display in the CTA button on the duplicate connection page. Only present when there is a redirectUrl and when there are additional services apart from accounting services.
Defaults to: Done.
duplicate.linkstringText to display as the add another service link on the duplicate page. Only present when there are additional service providers apart from accounting services.
Defaults to: Add another service.
error.titlestringText to display as the title when there is an error in Railz Connect. This will not display if we could not authenticate your widgetId.
Defaults to: Oops.
error.subTitlestringText to display as the subtitle when there is an error in Railz Connect. This will not display if we could not authenticate your widgetId.
Defaults to: Looks like there was a connection error on our end. Would you like to try again?.
error.unauthorizedSubTitlestringText to display as the subtitle when unable to connect to a service provider.
Defaults to: It looks like we couldn't connect to your service provider. Please try again..
error.verificationSubTitlestringText to display as the subtitle when unable to verify a connection to a service provider.
Defaults to: We could not verify the connection. Please verify again or start over..
error.reVerifystringText strings to display on the failed verification button.
Defaults to: Verify Again.
error.reviewstringText strings to display on the review manual connection steps.
Defaults to: Review Steps.
error.buttonstringText to display on the try again CTA button.
Defaults to: Try Again.
expiredSession.titlestringText to display as the title when the Railz Connect session has expired.
Defaults to: Your session has expired.
expiredSession.subTitlestringText to display as the subtitle when the Railz Connect session has expired.
Defaults to: Please refresh the page to continue..
expiredSession.buttonstringText to display in the CTA button on the expired session page.
Defaults to: Refresh.
serviceUnavailable.titlestringText to display as the title when the Railz Connect service is not available.
Defaults to: This service is not available.
serviceUnavailable.subTitlestringText to display as the subtitle when the Railz Connect service is not available.
Defaults to: It looks like this service is not available at the moment..
serviceUnavailable.contactstringText to display on the instructions message for contacting you when service is unavailable.
Defaults to: Please click on '\<button_text>' to notify \<company_name>..

Note:
To use the button name below, use the{{button}} in your passed value.

You can only replace the text prefix to \<company_name>.
serviceUnavailable.buttonstringText to display on the contact CTA button.
Defaults to: Contact.

Metadata

Add up to 5 metadata objects when adding a business through Railz Connect™. You will be able to view the provided metadata through the GET /businesses endpoint.

ParameterTypeDescription
namestringThe metadata property name - e.g. country. Should be between 2 and 40 characters.
valuestringThe metadata property value - e.g. Canada. Should be between 2 and 255 characters.
webhookLocationarrayIf provided, metadata will be sent in the webhook event response header, body and/or query param. See webhooks for more details. Valid enum values: header, body, query.

Customization Example

<!-- Use this script as a guide to add Railz Connect to your code -->
import RailzConnect from '@railzai/railz-connect';
import {useEffect, useRef} from "react";

function App() {
  const ref = useRef();

  useEffect(() => {
    const widget = new RailzConnect();
    widget.mount({
      parentElement: ref.current,
      widgetId: '<Your Widget Id>',
      theme: {
        fontFamily: 'Inter',
        logo: {
            url: 'https://github.com/railz-ai/railz-connect/raw/master/assets/images/railz-logo.svg',
            style: {maxHeight: '200px', height: '100px'}
        },
        primary: {
          background: '#A52EFF'
        },
        secondary: {
            background: '#3D58F3'
        },
     },
     options: {
       content: {
         serviceSelect: {
           title: 'Select the service below',
           subTitle: 'Your selection will help us serve you better',
           searchPlaceholder: 'Begin typing to search',
           searchLabel: 'Search Field'
         },
         terms: {
            markup: '<br/><br/><br/>Using this application confirms you have read our ',
            link: 'https://railz.ai',
          linkText: 'Terms and Condition',
          linkType: 'external',
        }
      },
        services: {
        exclude: ['dynamicsBusinessCentral','wave']
      }
     }
    });
  },[])
  return (
    <div id='railz-connect' ref={ref}></div>
  );
}

export default App;

Result

Railz Connect branded. Click to Expand.

Railz Connect branded. Click to Expand.

Deprecated Legacy Parameters

The following parameters from Railz Connect V1 have been deprecated and replaced with new ones in v2.

ParameterReplaced with
brandColortheme.primary.background
accentColortheme.secondary.background
serviceFilterEnabledoptions.components.search
closeEnabledoptions.components.close
headerEnabledoptions.components.header
removeRailzWatermarkoptions.components.watermark

Read Next