Connect with Railz Connect™

Use Railz's connection authorization journey in your application.

Railz Connect™ is a plug-and-play embeddable widget that provides a secure, fully customizable and conversion-optimized connection authorization flow to make it easy for business customers to connect their financial service provider accounts.

Railz Connect - Service Provider Selection. Click to Expand.

Railz Connect service provider selection page. Click to Expand.


Supported Browsers

Railz Connect is only supported using the latest version of Google Chrome, Safari, Firefox and Microsoft Edge. If you have issues using Railz Connect in other browsers, please try again using one of our supported browsers.

Business Authorization Flow


Dummy Authorization in Sandbox

When connection a business in Sandbox you will be promted for a dummy authorization flow. See Sandbox for more details.

As you might have noticed, you use both a server and a client-side component to create a connection and access the Railz APIs. The business authorization flow looks like this:

  1. A business customer will see an overview page of the integrations you have enabled and have allowed them to connect to.
  2. If you want your business customer to connect to all 3 integration types, Accounting, Banking and Commerce, they will follow a step-by-step process to connect to all 3. Each integration is by default set to mandatory in the connection process. You can configure your instance to allow your business customers to skip connecting their banking or commerce service provider accounts.
  3. A business customer will follow the online authorization process as established by each service provider. This process will redirect the user to the service provider's website or instructions on how to connect to validate their login credentials and explicitly authorize consent for your app to access their data.
  4. Upon successful authorization, Railz will encrypt and store the business' connection credentials which creates a new connectionId associated with the businessName and serviceName. Typically, connection credentials are valid for 12 months after authorization.
  5. Once the service provider is successfully authenticated and authorized, Railz Connect™ will redirect the end user to the success page or an overview page. You will be able to choose what that page is to ensure a seamless experience for your users.


Service Provider Authorization Role

Depending on the service provider, authorization requires a user with an administrator or account owner role to connect.


Reauthorizing a Connection

To reauthorize a connection you need to ask your business customers to go through the authorization flow again through Railz Connect. You can do so by loading Railz Connect with the businessName populated.

About widgetId

The unique widgetId is provided to you in the Railz Dashboard and identifies your instance of Railz Connect™.

About businessName

The businessName corresponds to a unique business name that you provide to identify the business authorizing access to their service providers. This will allow you to specify which businesses you want to request data on when calling the API.

If no businessName was provided when initiating Railz Connect™, Railz will generate a unique identifier.


Connection Flow Recommendations in Railz Connect

We recommend using the POST /businesses endpoint to create a new business, then using it as a value for the businessName parameter when initiating Railz Connect™. If your application workflow doesn't support identifying a business name when initiating Railz Connect™, we recommend you assign a temporary value then updating the business name using POST /businesses.