Merge requires a partnership for the ADP Workforce Now API based integration. To obtain partner credentials, you must first establish a partnership with ADP Workforce. After that, you may follow the steps below!

Enabling the ADP Partnership in Merge

Step 1: In your Merge dashboard, go to Configuration > HRIS and find ADP Workforce Now in the list of platforms.

Step 2: Check the box that says you'd like to authenticate users using your partner credentials.

Generating your signed ADP Certificate (SSL Certificate File and SSL Key File).

Step 1: Go to your ADP Partner self-service portal by visiting this link and click "Certificate" in the left navigation.

Step 2: Click the "Request Certificate" button.

Step 3: Fill in your details on the first screen and click Next.

Step 4: Copy your Private Key from the second screen (the entire text portion, including ---BEGIN PRIVATE KEY--- and ---END PRIVATE KEY---)

Step 5: Open a text or code editor (i.e TextEdit, VS Code) and paste the Private Key. Save the file with the extension ".key". You will need this later!

Step 6: Continue through the Certificate process until you get back to the main screen. On the main screen, click "Download", which should download a ".pem" file to your computer.

Step 7: In your Merge Dashboard, put in the ".pem" file as the SSL Certificate File and the ".key" file as the SSL Key File.

Finding your Client ID, Client Secret, and Consent Link

Step 1: In your ADP Partner self-service portal, click "Projects" in the left-side navigation.

Step 2: Select "My Development Project."

Step 3: Click "Development API Credentials" at the top of the page

Step 4: You'll see your Client ID and Client Secret in the first section. The second section has your Consent Link.

Step 5: Copy and paste all of this information into the Merge Dashboard under OAuth Client ID, OAuth Client Secret and Consent Link.

Finding your ADP Marketplace App URL, Client ID, and Client Secret

Step 1: In ADP Marketplace, go to the Developer dashboard by clicking your name in the top right corner, then clicking “Developer”.

Step 2: Click “Edit” under your product that corresponds to your data connector app.

Step 3: Click “Credentials” in the left navigation under “Integration”.

Step 4: You will see your Marketplace Client ID & Client Secret under the “Inbound Credentials” section.

Step 5: Copy and paste this information into the Merge Dashboard under Marketplace OAuth Client ID and Marketplace OAuth Client Secret.

Step 6: 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.

Configuring your ADP Marketplace App to Send 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.

Step 1: In ADP Marketplace (here), go to the Developer dashboard by clicking your name in the top right corner, then clicking “Developer”.

Step 2: Click “Edit” under your product that corresponds to your data connector app.

Step 3: Click “Edit Integration” in the left navigation under “Integration”.

Step 4: Enter the value for the “Subscription Create Notification URL” field. You can find this in the Merge dashboard under Configuration > HRIS > ADP Workforce Now.

Step 5: Be sure to append “?eventUrl={eventUrl}” to the end of the URL provided by Merge.

Step 6: Click “Add Required Info” underneath the “Subscription Create Notification URL” field.

Step 7: 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.

Step 7: 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

Step 8: Click Save at the bottom of the screen.

Step 9: 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.

Step 10: Click Save to confirm your changes

Testing your connection with ADP

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.

Step 1: Log into ADP Marketplace using your ADP Workforce Now Connector App’s Test Instance User.

Step 2: In your Merge dashboard, go to Linked Accounts > Test Linked Accounts and Add an ADP Workforce Now 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.

Step 3: Copy the Merge Token you are presented with in Link. Don’t close this window.

Step 4: 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.

Step 5: Finish the subscription flow, and continue with these steps once you’ve successfully subscribed.

Step 6: Go back to Merge. The “Next Step” button should now be clickable. Click the button to go to the next step.

Step 7: 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.

Step 8: 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. Reach out to [email protected] if you run into any issues.

ADP Workforce Now - How do I link using a practitioner role?

Google Workspace - Partnership Set up

ADP Workforce Now - How do I link to a partnered organization?

Setting up Xero Partner Credentials

Setting up Salesforce Partner Credentials for OAuth

Enabling the ADP Partnership in Merge

Step 1: In your Merge dashboard, go to Configuration > HRIS and find ADP Workforce Now in the list of platforms.

Step 2: Check the box that says you'd like to authenticate users using your partner credentials.

Generating your signed ADP Certificate (SSL Certificate File and SSL Key File).

Step 1: Go to your ADP Partner self-service portal by visiting this link and click "Certificate" in the left navigation.

Step 2: Click the "Request Certificate" button.

Step 3: Fill in your details on the first screen and click Next.

Step 4: Copy your Private Key from the second screen (the entire text portion, including ---BEGIN PRIVATE KEY--- and ---END PRIVATE KEY---)

Step 5: Open a text or code editor (i.e TextEdit, VS Code) and paste the Private Key. Save the file with the extension ".key". You will need this later!

Step 6: Continue through the Certificate process until you get back to the main screen. On the main screen, click "Download", which should download a ".pem" file to your computer.

Step 7: In your Merge Dashboard, put in the ".pem" file as the SSL Certificate File and the ".key" file as the SSL Key File.

Finding your Client ID, Client Secret, and Consent Link

Step 1: In your ADP Partner self-service portal, click "Projects" in the left-side navigation.

Step 2: Select "My Development Project."

Step 3: Click "Development API Credentials" at the top of the page

Step 4: You'll see your Client ID and Client Secret in the first section. The second section has your Consent Link.

Step 5: Copy and paste all of this information into the Merge Dashboard under OAuth Client ID, OAuth Client Secret and Consent Link.

Finding your ADP Marketplace App URL, Client ID, and Client Secret

Step 1: In ADP Marketplace, go to the Developer dashboard by clicking your name in the top right corner, then clicking “Developer”.

Step 2: Click “Edit” under your product that corresponds to your data connector app.

Step 3: Click “Credentials” in the left navigation under “Integration”.

Step 4: You will see your Marketplace Client ID & Client Secret under the “Inbound Credentials” section.

Step 5: Copy and paste this information into the Merge Dashboard under Marketplace OAuth Client ID and Marketplace OAuth Client Secret.

Step 6: Your app must be published to the ADP Marketplace to get your Marketplace App URL. If it is, please input your Marketplace APP URL.

Configuring your ADP Marketplace App to Send Notifications to Merge

Step 1: In ADP Marketplace (here), go to the Developer dashboard by clicking your name in the top right corner, then clicking “Developer”.

Step 2: Click “Edit” under your product that corresponds to your data connector app.

Step 3: Click “Edit Integration” in the left navigation under “Integration”.

Step 4: Enter the value for the “Subscription Create Notification URL” field. You can find this in the Merge dashboard under Configuration > HRIS > ADP Workforce Now.

Step 5: Be sure to append “?eventUrl={eventUrl}” to the end of the URL provided by Merge.

Step 6: Click “Add Required Info” underneath the “Subscription Create Notification URL” field.

Step 7: 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.

Step 7: Populate the required fields in the form.

Step 8: Click Save at the bottom of the screen.

Step 9: 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.

Step 10: Click Save to confirm your changes

Testing your connection with ADP

Step 1: Log into ADP Marketplace using your ADP Workforce Now Connector App’s Test Instance User.

Step 2: In your Merge dashboard, go to Linked Accounts > Test Linked Accounts and Add an ADP Workforce Now linked account.

Step 3: Copy the Merge Token you are presented with in Link. Don’t close this window.

Step 4: 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.

Step 5: Finish the subscription flow, and continue with these steps once you’ve successfully subscribed.

Step 6: Go back to Merge. The “Next Step” button should now be clickable. Click the button to go to the next step.

Step 7: 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.

Step 8: Go back to the Merge Linking Flow and click “I have provided consent” after providing consent in ADP Marketplace with your Test Instance User.