Frequently asked questions (FAQ)

Dev Kit

How can I identify a Clover Go Dev Kit?
The Clover Go device is an Ingenico Card Reader as shown in the following example.

400400

What is included with the Dev Kit?
The Dev Kit includes an Ingenico Card Reader, charging cable, and a test card. For more information, see Clover Developer Kits.

After ordering the Clover Go Dev Kit, how can I associate it with my sandbox account?
You cannot physically assign the Clover Go Dev Kit to your sandbox account. However, to use the Clover Go device, you need a sandbox API (goApiKey) and Secret (goSecret) keys. See Create a sandbox account for more details.

Can I associate my Dev Kit in the production environment?
Dev Kits are designed only for you to test your apps in the sandbox environment. You must create a developer account in the sandbox environment to use your Dev Kit. Note the difference between the URL (link) for the sandbox environment and the production environment.

How do I get my app approved and published before I can test my app on my Dev Kit?
You do not need an approved or published app for testing on your Dev Kit. You can install the app for your test merchant on the Developer Dashboard. See Installing your app to your test merchant.

My Dev Kit device is stuck at Error retrieving merchant information during activation. Why is this happening?
This message displays when your Dev Kit is not associated with your test merchant. Disassociate and re-associate your device to your merchant in your sandbox account. See Associate your Dev Kit to associate your Dev Kit with the test merchant.
If the issue is not resolved, factory reset the device and reactivate it.

Where can I get a debug cable?
Clover Dev Kits do not include debug cables and you have to purchase the cable externally. See Clover Developer Kits to identify the cable required for your device.

My Clover Flex Dev Kit isn't powering on. How do I troubleshoot?
If your Clover Flex is not powering on, make sure the device is charged, then follow these steps:

  1. Hold the power button for about 35 seconds. You should see a battery icon with a charge indicator, example: 85.
  2. Hold the power button again for 10 seconds. Your device should boot up normally.
    See the Clover merchant-facing help for more information on troubleshooting Clover devices.
    For best practices on using Clover devices, see device-specific storage guidelines.

I received a PIN entry is disabled or Device has malfunctioned message for my Dev Kit. What does this mean?
PIN entry is disabled on Dev Kits to meet the payment card industry (PCI) security requirements. This should not impact your development and testing activities. Similarly, if your Dev Kit has malfunctioned, you can still use use the Dev Kit for all non-payment capabilities.
To continue using your Dev Kit:

  1. Go to Setup > Payments > PIN Entry section and select Do not prompt for PIN.
  2. Continue to complete non-PIN (non-debit) transactions.
    If you cannot process a credit card sale or payment using the Register app, try different credit cards. The test magnetic stripe card sent with Dev Kits (ending in 6668) will work, as should other types of credit cards. Ensure that you are not using debit-only cards as it will result in a Transaction Failed error.

REST Pay Display

Why do I need OAuth 2.0 as part of my integration?
Clover uses the Open Authorization (OAuth) 2.0 security framework. When a merchant selects and installs your app, Clover uses OAuth 2.0 to first secure the communication between your app and the merchant, and then gives your app the necessary access to merchant data.
When an authorized merchant logs in to their Clover merchant account, the Clover server redirects the merchant to your app. The Access Token returned to you in the OAuth session is the Authorization (Auth) key for the REST Pay Display API.
Note: If your app does not require a server, see OAuth facilitator service.

Why do I need to create a Web App in Clover to use REST Pay Display?
A web app (REST client) in Clover that represents your point-of-sale (POS) integration is needed to complete the OAuth flow. The configuration of this web app includes:

  1. Permissions from the merchant so that you can access their merchant account and data, and
  2. Site link (URL) endpoint on your server, to which the OAuth flow redirects you, along with the appended access token.
    When your app is pushed to the merchant, the merchant logs in with their Clover credentials, and needs to grant permissions for your app. If the merchant grants the permission, they are redirected to your site URL.

What permissions does my Clover web app (REST client) need from the merchant?
Merchant Read is the minimum required permission.

  • If your integration only consists of REST Pay Display, then you do not need to submit a privacy policy for Clover App Approval.
  • If your integration uses the Ecommerce API, then Ecommerce API and Payments Read/Write permissions are required and you need to submit a privacy policy.

What apps need to be installed for my merchant?
The merchant needs to install one of the following:

  • Cloud Pay Display—If you are using a Cloud Connection
  • REST Pay Display—If you are using a Local Connection
  • Regardless of the connection, you also need to push your private web app to the merchant so that they can authenticate through OAuth.

REST Pay Display is supported in what regions?
REST Pay Display is currently supported in the United States (US) and Canada.

Are requests to REST Pay Display API rate limited?
No, due to the synchronous nature of REST Pay Display API, and how device activity is managed, Clover does not limit the rate of this API.

What if I use a proxy server to make calls to REST Pay Display using the local connection?
For your app to connect to the device, you need to ensure that the Clover Production Certificate is properly installed on your proxy server.

REST Pay Display—Payments

Are gift cards supported by REST Pay Display?
Yes, you can redeem physical Clover gift cards, as well as co-branded network gift cards.
If you have to support a closed-loop gift card system, Clover needs to approve your use of the read card data endpoint for a bank identification number (BIN) range that is safelisted on Clover.

Does Clover support PIN debit, surcharge and cashback?
Yes, Clover supports all the options. See the guide on understanding surcharges.

Is Electronic Benefits Transfer (EBT) supported?
Yes, you can set up your apps to accept EBT transactions with the following configurations:

  • Merchant needs to have the EBT entitlement both in sandbox and production environments. A DevRel support member can configure this in sandbox, if needed.
  • Use the EBT test card number: 5076 5800 0011 1112
    Note: Clover does not provide physical EBT test cards, but you can manually enter the EBT test card number to trigger "cardType":"EBT" in the payment response for an EBT transaction.

Is cashback supported for EBT cards?
There are two scenarios but cashback is not supported in both:

  • EBT Cash account holders may get cashback with a purchase and withdraw cash; however, these operations are not currently supported by Clover.
  • EBT Food (also called SNAP) does not support cashback.

Is Paypal™ or Venmo QR codes supported?
Yes, Paypal/Venmo can be enabled for merchants through standard Fiserv-Clover boarding tools and procedures. These upstream systems communicate with Clover to have Paypal/Venmo enabled for payments on Clover. When the tender becomes enabled for merchants, the QR Code is automatically displayed on the screen as customers are prompted for their payment method.

How do I handle Online Refund Authorizations?
When issuing a refund, most card brands now require online authorization of the card, which makes it subject to decline. Currently, this is supported for Discover®, Interac®, Mastercard®, and Visa® cards.
Online refund authorization applies to both refunding an existing payment for a partial or full amount, and issuing a credit to a customer.

Can I tokenize a customer's card on REST Pay Display and use it on Clover Ecommerce API?
Yes, see Interoperability with Ecommerce API for more information. The same application that handles REST Pay Display’s OAuth flow should be used for payment processing through the Ecommerce API.

Is Incremental Auth supported on Clover Ecommerce API?
Yes, incremental authorizations are available for:

  • Discover®, Mastercard®, and Visa® cards, and
  • Merchant types—aircraft rentals, amusement parks, bicycle rentals, boat rentals, car rentals, cruise lines, drinking places, eating places, equipment rentals, lodgings, motor home rentals, motorcycle rentals, trailer parks/campgrounds, and truck rentals. The merchant's merchant category code (MCC) must be under one of the preauth categories.

Devices and Printers

What happens if the merchant's printer is offline?
If the job does not print within 2 minutes of the request, a failed printing email is sent to the merchant. This email lets the merchant know the printer is unavailable and provides a link to an HTML version of the order receipt. When the printer is back online, the order receipt prints as requested.
If a print event is not printed within 1 hour of the request, Clover deletes the print event of the order. The order itself is not deleted, and the merchant can view it in the Orders app.

Can the merchant change the default firing device/printer at any time?
To select a device, go to Setup > Devices on any Clover device. For default printers, merchants can only change the printer visible on the device.

Can more than one device be configured as a default firing device?
No, the merchant can only select a single default firing device.

What happens if a merchant has a Clover Mini and then they add a Clover Station Duo in the future? Does the default firing device automatically change to the Station Duo?
A new device is not auto-selected until the merchant fully deactivates the Clover Mini. Orders print on the Mini unless the merchant changes the default firing device to Station Duo.

What Clover devices can be configured as a default firing device?
The following Clover devices are set up by default to send out prints to your printer.

  • Clover Mini
  • Clover Flex
  • Clover Station 2
  • Clover Station Duo

Can I re-fire an online order from the Orders app?
Yes, but only if the merchant has an order printer configured for the device on which you are trying to fire the order.

How does a merchant add order notes to receipts?
Order notes are enabled in the Setup app. See the merchant help site for more information.

Can a merchant customize their order receipts?
Yes, several settings are available in the Select options for printed order receipts, such as:

  • When to print order receipt
  • Font size on the printed order receipt
  • Order numbering (automatic or employee entered)
  • Order notes
  • How to display line items and modifiers
  • Whether to print customer information

Can customers place orders when the merchant's devices or printers are offline?
Yes, the orders are queued and printed when the printer is available again.

What happens if the default Clover device is replaced?
When the device is deactivated, another device is selected as the default firing device for printing orders or receipts on behalf of the merchant. Merchants can always change the default device in the Setup app.

If the default firing device has more than one order printer connected, can the merchant choose which order printer to fire online orders to?
No, the merchant cannot select an order printer in this case.

Will online orders fire to my kitchen display system (KDS), if the KDS is configured as the order printer for the default firing device?
Yes, you can set up a KDS as the order printer for a default firing device.

If a device has multiple order printers connected and an order is reprinted, where is the order reprinted?
A message displays enabling the merchant to select the order printer to print the receipt.

Developer Account Approval

Why does developer account approval require a passport?

In the e-commerce and financial services sector, we must meet compliance obligations and request proof of identity as a critical part of protecting our customers and our organization. While verifying a corporation is part of the process, we also need to validate an individual’s identity. For our international developers, passports are used to verify the individual since cryptographic information makes it difficult to forge a passport. This verification process determines if we will assume the risk as a payment processor with the third party or not.

As an alternative, if you do not want to submit your passport and/or address, another associate of your corporation may do so. Log in to the Developer Dashboard and change the information in your developer app so that it corresponds to the supportive documentation submitted.

How to securely submit your passport?

For your security, we request you add documents to a secure folder we create. You should not send any identification documents through email. For your convenience, you may also share a secure link to a secure site to access your passport.

Merchants

What is the merchant ID? How does it relate to the employee ID?

The merchant ID is an ID assigned by Clover to the business. A business may have multiple devices and employees. The owner of the business (along with managers and employees) each have an employee_id associated with their account. When looking at the OAuth response, keep in mind that you can see who the current user is by using the employee_id. You can use the merchant_id to see which business the user belongs. You must use themerchant_id when making REST API calls.

How can my app differentiate between real merchants and test merchants?

If you have a paid app, you may want to know whether you can bill a given merchant. For example, test merchant accounts used by developers and salespeople are not billable, so you will not get paid if apps installed for these types of accounts.

GET to /v3/merchants/{mId} to get merchant info, including an isBillable property.

How can my app differentiate between owners, managers, and employees?

If your app has the EMPLOYEE_R permission, then you can fetch information about the current user via a GET to /v3/merchants/{mId}/employees/{employeeId}?expand=roles. This will give you information about the role of the current user. If your app has the MERCHANT_R permission, then you can fetch the information about the owner via a GET to /v3/merchants/{mId}?expand=owner.

How do I notify a merchant of important changes?

You can notify your Android app running on the Clover devices via App Notifications. Once your app launches you can show a notification in the Android notification area, launch a Clover app via Broadcasts & Intents, or launch your own Activity.

When do I use an OAuth API Token, a merchant API Token, and my App Secret?

For production apps, developers should use an API token that is generated via OAuth. This token gives a particular app access to the Clover API for a specific merchant. Remember to use the App Secret when using the authorization code method of OAuth. For testing purposes only, it is possible to get a merchant API Token for your test merchant via the Setup App.

What is the API expiration period?

API tokens don't have time-based expiration. However, if a merchant uninstalls and reinstalls the app the token gets expired. You need to generate and use a new API token after the reinstallation.

Where can I get an API token for a particular merchant account without creating an app and having the merchant install the app?

See our guide on creating test Merchant API tokens. Note that these API tokens should only be used for testing and development purposes. Production apps must programmatically generate API tokens through OAuth or the Android SDK.

Are gift cards supported by the Ecommerce API?

  • Open-loop gift cards are associated with a major card brand like American Express, Discover, Mastercard, and Visa. These open-loop gift cards are tokenized and processed like a normal credit card.
  • Closed-loop gift cards, those issued by and redeemable at a single merchant or retailer, cannot be used for Ecommerce transactions.

What are my UUIDs?

For your app, developer, subscription, or test merchant universal unique identifier (UUID), log in to the Developer Dashboard to get this information. These IDs are different in sandbox and production, so ensure you are logged in to the correct environment:

What is my test merchant's UUID?

  1. To view your merchant universal unique identifier, log in to the Developer Dashboard.
  2. Select the test merchant from the Dashboard drop-down list.
  3. From the left navigation menu, select Setup > Merchants. On the Account Settings page, the ID displays in the Merchant column under the merchant name.
783783

See Test merchant IDs & API tokens for more information on retrieving your test merchant ID and a merchant API Token for use in development and testing. We strongly recommend that any production Clover app use OAuth API Tokens.

What is my app UUID?

Each of your app's basic information is shown in a card on the Developer Dashboard. The app universal unique identifier (UUID) is a 13-character value under the app name.

479479

The App Settings page also displays the UUID.

531531

What is my developer UUID?

  1. To view your developer universal unique identifier (UUID), log in to the Developer Dashboard.
  2. From the account menu in the top right, select Developer Settings.
  3. On the settings page, the ID displays in the Developer Info section.
510510

What is my app's subscription UUID?

Each Clover app has at least one subscription universal unique identifier (UUID) for the free tier. If you add additional pricing tiers, each new tier has its own ID.

  1. To view your subscription ID, log in to the Developer Dashboard.
  2. From the left navigation menu, select App name > Pricing & Distribution.
  3. On the Pricing & Distribution page, the IDs are listed in the Subscription Pricing section next to the tier name.
694694

Miscellaneous

Why does my YouTube or Vimeo video not play on the More Tools app on my Clover device?

Certain Clover devices have limitations on the video codecs they support. This affects how videos are played in Clover App Market on these devices:

  • Clover Station 2018 and Mini 2 support YouTube and Vimeo
  • Clover Station and Mini 1 support only YouTube
  • Clover Flex supports only Vimeo

Depending on the Clover devices you are building your apps for, we recommend that you keep these limitations in mind. Note that the web version of Clover App Market has no such limitations.

How do I get my magnetic stripe card's BIN to work on Clover devices?

As a security measure, Clover follows an encryption-by-default model for magnetic stripe cards and does not automatically allow Bank or Issuer Identification Numbers (BINs) for magnetic stripe cards in the US. However, depending on the Clover devices you are building your app for and the type of card you are using, you can retrieve unencrypted track data.

Clover defines a financial card as one that has:

  • Either track 1 or track 2 data that conforms to ISO/IEC 7813:2006, and
  • Primary Account Number (PAN) on the track with 12 or more characters

On Clover Station (2018), Mini 1 and Mini 2, Flex, and Mobile, you can simply swipe a non-financial card, such as an employee ID card, and retrieve the unencrypted track data. On Clover Station, non-financial cards cannot be read.

📘

NOTE

We highly recommend gift card developers to use QR codes for reading physical cards using the merchant-facing camera on Clover devices. Also, many Clover devices support near field communication (NFC) for reading digital cards.

What SSL/TLS cipher suites should my app support?

All Clover devices and servers follow industry best practices for SSL/TLS configuration. To ensure interoperability, you must ensure that your servers use a compatible SSL/TLS configuration.

SSL/TLS versions: Clover devices and servers are only guaranteed to support TLS 1.2. Some devices and servers may support TLS 1.1 and TLS 1.0. For security reasons, SSL 3.0 is not supported.

Cipher suites: Clover devices and servers are guaranteed to support the following cipher suites:

  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_AES_256_GCM_SHA384

Additional cipher suites may be supported on some servers and device models. For security reasons, ciphers using HMAC-MD5, RC4, or single key DES are not supported.

Certificate signatures: Use only SHA2 signed certificates with at least 2048 bit RSA keys.

📘

NOTE

Clover guarantees support only for the above TLS versions and cipher suites. Alternative configurations may be supported by some devices and servers, but support may be removed at any time.

For example, some cipher suites supported on Clover Station are not supported on Clover Mini, but Clover may remove support for these cipher suites at any time.

More Questions?

You can post questions on Clover Developer Community.