Overview
This guide will help you set up your partnership credentials in Merge for ADP Workforce Now and ADP RUN. Before you proceed, please ensure you have an active partnership with ADP.
Finding credentials
Step 1: Enable the ADP partnership in Merge
In your Merge dashboard, go to Configuration > HRIS and find either ADP Workforce Now or ADP RUN in the list of platforms
Check the box that says you'd like to authenticate users using your partner credentials
Step 2: Generate your signed ADP Certificate (SSL Certificate File and SSL Key File)
Go to your ADP Partner self-service portal
On the menu bar on the left, click Certificate
Click Request Certificate
Fill in the appropriate details on the first screen
Click Next
Copy your Private Key
Copy the entire text portion including ---BEGIN PRIVATE KEY--- and ---END PRIVATE KEY---
Open a text or code editor and paste your Private Key
Save the file with the extension ".key"
You will need this later!
Back in ADP, Continue through the Certificate process until you reach the main screen again
From the main screen, click Download
This should download a ".pem" file to your computer
In your Merge Dashboard, put in the ".pem" file as the SSL Certificate File and the ".key" file as the SSL Key File
Step 3: Find your Client ID, Client Secret, and Consent Link
In your ADP Partner self-service portal, on the menu bar on the left, click Projects
Select My Development Project
At the top of the page, click Development API Credentials
From the first section, note your Client ID and Client Secret
From the second section, note your Consent Link
Copy and paste all of this information into the Merge Dashboard under OAuth Client ID, OAuth Client Secret and Consent Link
Step 4: Find your ADP Marketplace App URL, Client ID & Client Secret
Log into ADP Marketplace
In the top right corner, click your name and then click Developer
Under your product that corresponds to your data connector app, click Edit
On the navigation tab on the left, under Integration, select Credentials
Under the Inbound Credentials section, note your Marketplace Client ID and Marketplace Client Secret
Copy your Marketplace Application URL
Copy and paste this information into the Merge Dashboard under Marketplace OAuth Client ID and Marketplace OAuth Client Secret
Your app must be published to the ADP Marketplace to get your Marketplace App URL. If it is, please input your Marketplace APP URL.
If your app is not published, you can input https://www.merge.dev as a placeholder for testing purposes.
Sending notifications to Merge
In the following steps, we will configure your ADP Marketplace App to send notifications to Merge whenever an end user subscribes to your app.
In ADP Marketplace (here), go to the Developer dashboard by clicking your name in the top right corner, then clicking “Developer”
Click “Edit” under your product that corresponds to your data connector app
Click “Edit Integration” in the left navigation under “Integration”
Enter the value for the “Subscription Create Notification URL” field. You can find this in the Merge dashboard under Configuration > HRIS > ADP Workforce Now or ADP RUN
Be sure to append “?eventUrl={eventUrl}” to the end of the URL provided by Merge
Click “Add Required Info” underneath the “Subscription Create Notification URL” field
Name the Form Title / Description whatever you would like. Add a text field within the form with the input code merge_token, and input title “Token”. You can set the input descriptor to whatever would be most helpful for your users
Populate the required fields in the form
You must also populate the following fields in order for your application to be approved by ADP Marketplace. You can use the same URL as the “Subscription Create Notification URL” field if these events are not relevant to your use case. If they are relevant to you, you can populate these fields with webhook listeners from your application.Subscription Change Notification URL
Subscription Cancel Notification URL
Subscription Status Notification URL
User Assignment Notification URL
User Unassignment Notification URL
Click Save at the bottom of the screen
After saving, go to the “Credentials” tab. Under Outbound Credentials, select Basic Authentication for Type, and input merge as your username and your organization’s name (mixed case) as your password
Click Save to confirm your changes
Testing the ADP connection
In this step, we will test the connection between Merge and your ADP Marketplace App. You can begin these steps once the steps above are complete.
Log into ADP Marketplace using your ADP Workforce Now or ADP RUN Connector App’s Test Instance User
In your Merge dashboard, go to Linked Accounts > Test Linked Accounts and Add an ADP Workforce Now or ADP RUN linked account
You should see a screen like the one below. If you don’t, make sure you’ve configured all of the necessary Partnership configuration parameters for ADP
Copy the Merge Token you are presented with in Link. Don’t close this window.
Once logged in, go to your data connector app in ADP Marketplace and click “Buy Now”. When prompted for the Merge Token in the ADP Marketplace flow, input the value you got from Merge Link in step 3
Finish the subscription flow, and continue with these steps once you’ve successfully subscribed
Go back to Merge. The “Next Step” button should now be clickable. Click the button to go to the next step
Now you must provide consent to the data connector app in ADP Marketplace
To do this, go to the "My Apps" section in ADP Marketplace, and click on the data connector app, where you will be prompted to provide consent. If it doesn't prompt you, it means that you have already consented.
Go back to the Merge Linking Flow and click “I have provided consent” after providing consent in ADP Marketplace with your Test Instance User.
This will kick off the initial sync, and if successful, a test linked account will be created