Embed Finch Connect

In this method of integration, your can embed Finch Connect into your application using a Finch SDK so your user remains on your application. The authorization flow will consist of four steps:

1. Open Finch Connect - Your application uses a Finch SDK to launch Finch Connect and initiate the authorization flow for your user.
2. Obtain consent - Finch Connect prompts your user to log in to their employment system and grant your application access to the permissions you are requesting for.
3. Retrieve the authorization code - If the user successfully connects and grants your application access to their system, Finch Connect will call the registered onSuccess handler with a short-lived authorization code.
4. Exchange the code for an access token - Before sending API requests, your application will exchange the short-lived code for a long-lived access_token that represents your application's access to your user's employment system.

Currently, Finch supports Javascript and React SDKs.

Open Finch Connect

To make a request to Finch, an employer must connect their payroll or HRIS account using Finch Connect. Finch SDKs provides a drop-in and secure authorization flow for your users.

React SDK

To open Finch Connect using React, you will need to instantiate the React SDK with the useFinchConnect hook and invoke the returned open method to display the view for your user.

1. Install the React Finch Connect SDK

Inside your code base folder, use the command line to install react-finch-connect

npm install --save react-finch-connect

2. Import the 'useFinchConnect' Hook

import React, { useState } from "react";
import { useFinchConnect } from "react-finch-connect";

const App = () => {
 const [code, setCode] = useState(null);

 const onSuccess = ({ code }) => setCode(code);
 const onError = ({ errorMessage }) => console.error(errorMessage);
 const onClose = () => console.log("User exited Finch Connect");

 // 1. Initialize Finch Connect
 const { open } = useFinchConnect({
   clientId: "<your-client-id>",
   products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
   onSuccess,
   onError,
   onClose,
 });

 // ...
};

useFinchConnect Parameters

3. Launch Finch Connect

To launch Finch Connect, use the open function returned by useFinchConnect and place this on an onClick handler of an HTML button.

const App = () => {
  // ...

  // 2. Display Finch Connect
  return (
    <button type="button" onClick={() => open()}>
      Open Finch Connect
    </button>
  );
};

4. Receive the authorization code

Once a user has authorized the application to access their payroll account, the onSuccess function is called with an authorization code.

After receiving the authorization code, the React application must exchange it for an access_token. To do so, send the code to the back-end service. Let's assume that your back-end service contains an endpoint /exchange that receives an authorization code as a query parameter and exchanges it for an access_token.

const App = () => {
  // ...

  onSuccess = ({ code }) => {
    return axios.get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`);
  };

  // ...
};

Notice that your back-end service does not return the access_token. This is by design. For security, your front-end should never have access to the access_token and should always be stored in the back-end.

5. Get company information

Once the back-end has the access_token, it can send requests to a payroll provider using the Finch API. Your React app will have to send a request to the back-end service which in turn sends a request to Finch. You have to do this because your front-end does not have the access_token.

Assuming your back-end has a /company endpoint that returns information on the employer, you can make this query in your onSuccess function and set the state of the React app with the returned company attribute.

const App = () => {
  // ...
  
  onSuccess = ({ code }) => {
    return axios.get(`${process.env.REACT_APP_SERVER}/exchange?code=${code}`)
      .then(_ => axios.get(`${process.env.REACT_APP_SERVER}/company`)
      .then(res => {
       setIdentity(res.data);
      });
  }
  
  // ...
};

Javascript SDK

The Javascript SDK can be loaded via a HTML <script /> tag and then instantiated with some initialization code in your application.

1. Include the Javascript SDK Script

<html>
  <head>
    <script src="https://prod-cdn.tryfinch.com/v1/connect.js"></script>
  </head>
  <body>
    
  </body>
</html>

2. Initialize Finch Connect

Inside a <script> inside the page <body>, initialize the FinchConnect object.

The returned FinchConnect object exposes open, close and destroy lifecycle methods.

<html>
  <body>
    <script>
      const onSuccess = ({code}) => {
        // exchange code for access token via your server
      }
      const onError = ({ errorMessage }) => {
        console.error(errorMessage);
      }
      const onClose = () => {
        console.log('Connect closed');
      }
      const connect = FinchConnect.initialize({
        clientId: '<your-client-id>',
        products: ['company', 'directory', "individual", "employment", "payment", "pay_statement"],
        sandbox: false,
        manual: false,
        onSuccess,
        onError,
        onClose,
      });
    </script>
  </body>
</html>

FinchConnect Parameters

3. Open Finch Connect

To open Finch Connect, use the open function returned by FinchConnect and add an addEventListener on the click event of an HTML button.

<html>
  <body>
    <button id="connect-button">Open Finch Connect</button>
    <script>
      const button = document.getElementById('connect-button');

      const connect = FinchConnect.initialize({
        ...
      });
      button.addEventListener('click', () => {
        connect.open();
      })
    </script>
  </body>
</html>

4. Exchange the authorization code

Once a user has authorized the application to access their payroll account, the onSuccess function is called with an authorization code.

After receiving the authorization code, the front-end application must exchange it for an access_token. To do so, send the code to the back-end service. Let's assume that your back-end service contains an endpoint /exchange that receives an authorization code as a query parameter and exchanges it for an access_token.

<html>
  <body>
    <script>
      // ...
      const onSuccess = async ({code}) => {
        return await fetch(`http://your-api.com/exchange?code=${code}`)
          .then(res => res.json());
      }
      // ...
    </script>
  </body>
</html>

Notice that your back-end service will not return the access_token. This is by design. For security, your front-end should never have access to the access_token and should always be stored in the back-end.

5. Request company information

Once the back-end has the access_token, it can send requests to a payroll provider using the Finch API. Your app will have to send a request to the back-end service which in turn sends a request to Finch. You have to do this because your front-end does not have the access_token.

Assuming our back-end has a /company endpoint that returns information on the employer, you can make this query in your onSuccess function and set the state of the app with the returned company attribute.

<html>
  <body>
    <script>
      // ...
      const onSuccess = async ({code}) => {
        return await fetch(`http://your-api-server.com/exchange?code=${code}`)
          .then(await fetch(`http://your-api-server.com/company`)
          .then(res => {
            setCompany(res.json)
          });
      }
      // ...
    </script>
  </body>
</html>

Next steps

Once you have an access_token, you can begin pulling data and pushing changes into your users' employment systems! The next step is to start handling Finch API responses.