Configuring a local connection

Installing REST Pay Display

Prerequisites

The merchant must:

  • Install your POS app.
    —and—
  • 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. You can install this app either from the web dashboard or on the device:

Install from the web dashboard

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

Install on the device

  1. On the home screen, tap More Tools.
  2. Tap the magnifying glass icon, and enter rest.
  3. Tap the REST Pay Display result.
  4. On the REST Pay Display page, tap Connect.
  5. 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 Clover Prod Terminal Server Root certificate authority (CA) issues the device server certificate. You need to enable the sandbox development certificate before working in the sandbox environment.

The REST Pay Display app must be running to accept requests from your POS app. To start the app:

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

Configuration 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 Clover CA-issued device server certificate, 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 Clover Device Server Root CA issues the device server certificate, which 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 Clover Prod Terminal Server Root CA issues the device server certificate, which 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

Change the device certificate for development

To enable the development CA in the sandbox environment:

  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.

View the current certificate

To view complete device certificate, tap View Certificate Details.

View the device server settings

To open the options page:

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

Change the connection protocol

📘

NOTE

You can use the non-secure HTTP connection only if needed for development and testing. HTTPS connections must be enabled in production.

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 on your device:

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

Change the server port

By default, the connection between a POS and Clover device uses port 12346. To modify the port on your device:

  1. Tap Server Port.
  2. On the Enter Server Port Number window, enter 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 ping settings, modify one or more of the following values:

Setting

Description

Enable ping

When selected, the device checks that the connection is open at the specified interval.

Ping interval

Length of time between pings, in milliseconds.

Ping retry before disconnect

Number of times the server attempts to ping the client before disconnecting.

Authenticating with OAuth

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.

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

  • Environment- and region-specific base URL
  • Required headers (X-Clover-Device-Id and X-POS-ID)
  • Resource (endpoint) in use
  • 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

Display 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-device-id': 'deviceSerialNumber',
    '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?