Frequently asked questions (FAQs)

United States



Dev Kit

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.

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.


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

A merchant_id (mId) is a unique identifier ID that Clover assigns to a merchant or business account which is authorized to use your app. An employee_id is a unique ID assigned to the business owners, managers, and employees associated with the mId. When reviewing the OAuth response, you can use the employee_id to view the current users. The merchant_id to helps to identify the business to which these users belong. You must use the merchant_id when making REST API calls.

How does my app identify the difference between real merchants and test merchants?

Your app uses the following API to get the merchant information: GET to /v3/merchants/{mId} to get merchant information, including an isBillable property.
The isBillable property indicates, it is a real merchant. Developers and sales teams use test merchant accounts for testing purposes and are not billable. Hence, you are not paid for the apps installed by these accounts.

How does my app identify the difference between owners, managers, and employees?

Your app uses an API to get the user role details.

  • If your app has the EMPLOYEE_R permission, use the following API for information about the current user role:
    GET to /v3/merchants/{mId}/employees/{employeeId}?expand=roles.
  • If your app has the MERCHANT_R permission, use the following API for information about the current user role:
    GET to /v3/merchants/{mId}?expand=owner.

How do I notify a merchant of important changes?

The Clover app notification infrastructure allows you to send a message to either a single instance of an app running on a merchant device or to all of them. You can also implement your own app notification system or use an external message delivery service.
See Send app notifications app notifications and Set up broadcasts and intents for more information.

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

App Secret is a secret key that Clover assigns to your app. It is used to authenticate the identity of your app with the Clover server when you are requesting for an API token. The OAuth API token allows you access to the Clover API for a specific merchant. See Use OAuth for more information.

Similarly, a merchant API token is used to get access to Clover APIs for specific test merchants. See set up a new app for more information.

Can I generate a test API token for a particular merchant account without creating an app and having the merchant install the app?

Yes, you can generate a test API token for a test merchant account without the merchant installing the app.
Important: The test API token is only for testing and development. Your apps in production must programmatically generate API tokens through the OAuth or the Android SDK.

What is the API expiration period?

API tokens don't have time-based expiration. An API token expires when a merchant uninstalls and reinstalls the app. You need to generate and use a new API token after the app is reinstalled.
However, if a merchant installs the latest APK or version of the app without uninstalling it, the API token continues to function as expected.

Are gift cards supported by the Ecommerce API?

Yes, Clover supports:

  • Open-loop gift cards—Cards associated with a major card brand, such as American Express®, Discover®, Mastercard®, or Visa®.
  • Closed-loop gift cards—Cards issued by and redeemable at a single merchant or retailer for Ecommerce transactions.

What are my UUIDs?

Clover generates app, developer, subscription, and test merchant Universally Unique Identifiers (UUIDs). All of these identifiers (IDs) are available in Developer Dashboard. These IDs are different for sandbox and production accounts, so ensure you are logged into the correct environment.

Here is an example of how to locate the merchant ID.


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

Some Clover devices have limitations on video codec support. However, the web version of Clover App Market has no such limitation. Keep the following in mind when building apps for specific Clover devices:

Clover deviceSupports videos on
- Clover Station 2018
- Clover Mini 2
YouTube and Vimeo
- Clover Station
- Clover Mini 1
Only YouTube
Clover FlexOnly Vimeo

What SSL/TLS cipher suites should my app support?

All Clover devices and servers follow industry best practices for SSL/TLS configuration.

  • SSL/TLS configuration—To ensure interoperability, you must ensure that your servers use a compatible SSL/TLS configuration: All Clover devices and servers only guarantee to support the TLS 1.2 version.
  • Some devices and servers may support TLS 1.1 and TLS 1.0.
  • For security reasons, SSL 3.0 is not supported.

Cipher suites—All Clover devices and servers guarantee to support the following cipher suites:


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.



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.

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 United States (US). However, depending on the Clover devices for which you are building your app and the type of card, you can retrieve unencrypted track data.
Clover defines a financial card as one with:

  • 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. Clover Station cannot read non-financial cards.



Clover recommends gift card developers to use QR codes for physical cards that the merchant-facing camera on Clover devices can read. Also, many Clover devices support near-field communication (NFC) for reading digital cards.

More Questions?

You can post questions on Clover Developer Community.