Heartland Retail

Introduction

This guide explains how to obtain authentication details from Heartland Retail, as well as installing a Heartland Retail Connector.

Setup & Authentication

Overview

There are 2 options when authenticating this Connector:

• API Token - your customer obtains an API Token and provides that when authenticating the Connector.

• OAuth - you register an app to obtain a Client ID and Client Secret, store those in your Partner Console, and your customer provides the final authorization when installing the Connector.

Follow the appropriate sections below depending on the authentication type you choose.

Remote Setup in Heartland Retail - performed by your customer

If choosing API Token:

Your customer should go to their Heartland Retail account.

Accessing the Heartland Retail API requires a secret API token. The customer manages their API tokens in the API Tokens page.

To access the API Tokens page in Heartland Retail, click the name in the top right corner of the Heartland Retail dashboard. A drop down menu will open, where the user can click "my account", then click "API" to go to the API Tokens page.

Generating an API Token:

1. Click the "Generate new token" button.

2. Enter a description for the API Token.

3. Click the "Generate Token" button.

4. An API Token will be displayed. It should be copied then and won’t be shown again.

5. Click the "Done" button.

6. Save the API token which will need to be provided when installing the Heartland Retail Connector.

Remote Setup in Heartland Retail - performed by Cyclr Partner

If choosing OAuth:

OAuth2 is a protocol that lets external applications request authorization to private details in a user's Heartland Retail account without getting their password.

OAuth tokens can be limited to specific data (see Scopes), and can be revoked by users at any time.

You'll need to register your application before getting started.

A registered app is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should not be shared.

To register your application you must submit a request to Heartland Retail, which can be done on this page:
https://dev.retail.heartland.us/#support

Partner Setup in Cyclr Console - if using OAuth Authentication

Having registered an application with Heartland Retail and obtained a Client ID and a Client Secret, go into your Cyclr Partner Console:

1. Go to Connectors > Application Connector Library.

2. Use the search box to locate the Heartland Retail Connector entry.

3. Select the Pencil button.

4. Select the Settings tab.

5. Enter the below values:

6. Select Save Changes.

If you leave these values blank, they must be provided each time the Connector is installed.

Cyclr Connector Installation

When installing the Heartland Retail Connector, the following values are used, depending on the authentication chosen:

API Token

OAuth Authentication

When installing a Heartland Retail Connector, the user will be asked to give consent for your application to access their data.