Skip to main content
Paylocity connections start in the Paylocity Marketplace. For each application Paylocity approves, Paylocity lists a Marketplace tile named <Your application> via Finch. Finch holds the Paylocity credentials for your tile and handles Paylocity’s approval of each employer, so you never call Paylocity or hold Paylocity credentials.

​
How the flow works

  1. A company administrator requests your tile in the Paylocity Marketplace and selects the companies to share.
  2. Paylocity sends the administrator to a Finch landing page. Finch creates a Finch Connect session with Paylocity and the selected companies already set, then redirects the administrator to your application with that session.
  3. Your application signs the administrator in and launches Finch Connect with the session.
  4. The administrator clicks Connect. Finch confirms the request with Paylocity and creates the connection.
  5. Your application exchanges the authorization code for an access token.
Your part is steps 3 and 5. The onboarding process consists of the following steps: Step 1: Set up your Paylocity Marketplace tile Step 2: Handle the redirect from Finch Step 3: Launch Finch Connect Step 4: Retrieve the access token

​
Step 1: Set up your Paylocity Marketplace tile

Paylocity reviews each application before listing its tile. To start, contact your Developer Success Engineer or implementation-team@tryfinch.com. Finch coordinates the review with Paylocity and asks you for the copy that describes your application on the tile, plus your contacts for Paylocity’s evaluation. You don’t need a Paylocity account. Once Paylocity approves your application, Paylocity publishes your tile and Finch enables Paylocity for your application.

​
Step 2: Handle the redirect from Finch

When an administrator arrives from the Paylocity Marketplace, Finch redirects them to the first redirect URI configured on your application, with these query parameters:
Example redirect to your application
Make sure that redirect URI points to a page in your application that handles these parameters, and confirm it with Finch before your tile goes live. When your application receives a request with idp_redirect=true, it should:
  1. Sign the administrator in, or let them create an account, so you know which of your customers is connecting. If they aren’t one of your customers or aren’t a fit for your product, send them to your own intake process instead of launching Finch Connect.
  2. Launch Finch Connect with the session value within 30 minutes. After that the session expires, and the administrator has to request your tile again from the Marketplace.
Don’t call POST /connect/sessions for these requests. Use the session Finch passes to your application, since it carries the companies the administrator selected in the Marketplace.
These sessions don’t include a customer_id. Use the signed-in user to associate the connection with the right customer, or carry that context through the state parameter.

​
Step 3: Launch Finch Connect

Launch Finch Connect with the session value, using either flow described in Create a Finch Connect Session. For the embedded flow, pass the session value to connect.open():
Embedded flow
For the redirect flow, send the browser to Finch Connect with your redirect_uri, which must match one of your application’s redirect URIs:
Redirect flow
By default, the session requests every product Finch supports for Paylocity. To request fewer in the redirect flow, add products as a space-separated list, for example &products=company%20directory%20individual%20employment. In Finch Connect, Paylocity is already selected and the administrator clicks Connect to finish. If they shared more than one company in the Marketplace, Finch Connect asks which of those companies to connect.

​
Step 4: Retrieve the access token

Exchange the authorization code for an access token as described in Retrieve an Access Token. The first data sync for a new Paylocity connection can take a few minutes to start.

​
When an employer starts in Finch Connect

Employers can still open Finch Connect from your application or from an emailed link. When they select Paylocity, Finch Connect explains that Paylocity connections start in the Marketplace and lists the steps:
  1. Sign in to Paylocity and open the Marketplace from the main menu.
  2. Find <Your application> via Finch and click Create Request.
  3. Select the companies to share and submit the request.
Paylocity then sends the administrator through the same flow, and they reach your application with a new session as described in Step 2. The original Finch Connect window can be closed.
See Field Support for the fields Finch returns for Paylocity. If you have any questions, reach out to your Finch Developer Success Engineer or implementation-team@tryfinch.com.