Configuring a local connection

Installing REST Pay Display

Prerequisites

Your POS app must be installed by the merchant and they must complete the OAuth flow so your app has the bearer token needed to authenticate your requests.

Installing the REST Pay Display app

A local connection requires that your merchant's device run the REST Pay Display app. To install this app from either the web dashboard or on the device, complete the steps in one of the following appropriate sections.

Installing from the web dashboard

  1. Log on to the merchant dashboard.
  2. On the sidebar, click More Tools and then click Apps By Clover.
  3. In the search bar, type rest and click the REST Pay Display result.
  4. On the REST Pay Display page, click Connect.
    The app is automatically downloaded and installed on all the merchant's Mini and Flex devices.

Installing on the device

  1. On the home screen, tap More Tools.
  2. Tap the magnifying glass icon, type rest, and tap the REST Pay Display result.
  3. On the REST Pay Display page, tap Connect.
  4. On the Install REST Pay Display page, tap Connect.
    The app is automatically downloaded and installed on all the merchant's Mini and Flex devices.

Starting the app

📘

NOTE

By default, the device server certificate is issued by the Clover Prod Terminal Server Root CA, so you need to enable the sandbox development certificate before working in the sandbox environment.

The REST Pay Display app must be running in order to accept requests from your POS app. To start the app, do the following:

  1. On the home screen, tap REST Pay Display.
  2. Tap Start.
    The welcome screen appears.

Configuring settings

REST Pay Display uses an HTTP server on the device so your POS can establish an HTTPS connection. This connection requires your POS to trust the Clover certificate authority (CA) that has issued the HTTP Server certificate.

Device server certificates

To establish trust between your POS and the device server certificate issued by the Clover CA, you must install a Clover CA certificate on the POS. Clover provides separate certificates for development and production use.

🚧

IMPORTANT

The certificate must be installed in the Trusted Root Certification Authorities store. If the certificate is not installed in the correct store, a certificate chain error message appears when you attempt to connect.

Sandbox (development)

The device server certificate is issued by the Clover Device Server Root CA. The CA certificate is hosted at:

https://sandbox.dev.clover.com/v2/device_ca_certificate
https://sandbox.dev.clover.com/v2/device_ca_certificate.der
https://sandbox.dev.clover.com/v2/device_ca_certificate.crt

Production

The device server certificate is issued by the Clover Prod Terminal Server Root CA. The CA certificate is hosted at:

https://www.clover.com/v2/env_device_ca_certificate
https://www.clover.com/v2/env_device_ca_certificate.der
https://www.clover.com/v2/env_device_ca_certificate.crt

Changing the device certificate for development

To enable your development CA when you work in the sandbox environment, do the following.

  1. In the REST Pay Display app settings, select the Enable Development Certificate option.
  2. Select Configure and Restart Server. After the server restarts, the CA is updated.
  3. Select View Certificate Details and verify that the device certificate is issued by the Clover Device Server Root CA.

Viewing the current certificate

To see the complete device certificate, tap View Certificate Details.

Opening the options page

To open the options page, do the following.

  1. Open REST Pay Display.
  2. Tap the menu icon and then tap Settings.
    The Clover Device Server settings appear.

Changing the connection protocol

By default, the connection between a POS and Clover device is over Hypertext Transfer Protocol Secure (HTTPS). The Clover Device Server also supports an encrypted Hypertext Transfer Protocol (HTTP) connection. To change the connection type, do the following.

📘

NOTE

A non-secure HTTP connection should only be used if needed for development and testing. HTTPS connections must be enabled in production.

  1. Tap the Server is Secured check box.
  2. Tap Configure and Restart Server.
    The lock icon changes from green locked to red open. On the REST Pay Display screen, the device URLs change from https:// to http://.

Changing the server port

By default, the connection between a POS and Clover device uses port 12346. To modify the port, do the following.

  1. Tap Server Port.
  2. On the Enter Server Port Number window, type a new port number.
  3. Tap Save.
  4. Tap Configure and Restart Server.
    The port change is applied.

📘

NOTE

If the new port is used by another process on the Clover device, an Address already in use message appears. To correct this issue, repeat the previous steps using a different port number.

Ping settings

To change the device's ping settings, modify one or more of the following values.

Authentication

The REST Pay API requires that your app authenticate each request. Your application must send a valid OAuth 2.0 API access token with each request. See Using OAuth 2.0 for more information.

Changing the length of auth token validity

Auth token validity period is not enabled for REST Pay Display.

📘

The validity period here only applies to temporary tokens returned during the pairing process for Network Pay Display.

Device pairing screen

Pairing is not enabled for REST Pay Display.

Building a request

A request is built using these components:

  • An environment- and region-specific base URL
  • The required headers (X-Clover-Merchant-Id, X-Clover-Device-Id, and X-POS-ID)
  • The resource (endpoint) being used
  • The request body

See Locating UUIDs if you need help finding your app, developer, or test merchant UUID on the developer dashboard.

For PCI compliance, all requests must be made using a secure (HTTPS) connection.

Example request

Show a message on the device:

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://'yourdeviceip':12346/connect/v1/device/display',
  headers: {
    accept: 'application/json',
    'x-clover-merchant-id': 'XP571GHSRGGH5',
    'x-clover-device-id': 'C013UQ91220081',
    'x-pos-id': 'MyPOS',
    'content-type': 'application/json',
    authorization: 'Bearer OauthToken'
  },
  body: '{"text":"A message to show on the device","beep":true}'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Did this page help you?