Developer Kits

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

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 Install 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 with a test merchant account. 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; 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, for example, 85.
2. Hold the power button again for 10 seconds. Your device should boot up normally.
   See the Clover Help for more information on troubleshooting Clover devices.
   For best practices on using Clover devices, see Clover 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 it for all non-payment capabilities.

To continue using your Dev Kit:

1. On your Dev Kit, go to the Setup > Payments > PIN Entry section.
2. Select Do not prompt for PIN.
3. 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. Make sure 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 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.

For more information, see OAuth flows in Clover.

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 URL (link) 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 (link).

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, 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.

What regions is REST Pay Display supported in?
REST Pay Display is supported in the United States, Canada, and Europe.

Are requests to REST Pay Display API rate limited?
No, due to the synchronous nature of the 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 must make sure 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 Understand 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 the sandbox and production environments. A Developer Relations (DevRel) support member can configure this in the 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 EBT-related scenarios, but cashback is not supported in both:

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

Are PayPal™ or Venmo QR codes supported?
Yes, PayPal or Venmo can be enabled for merchants through standard Fiserv and Clover boarding tools and procedures. These upstream systems communicate with Clover to enable PayPal or Venmo to make payments on Clover. When the tender becomes enabled for merchants, the QR Code is automatically displayed on the screen as customers are prompted to use 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 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 not available 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 default printing device on your Clover device, go to Setup > Devices. 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 adds 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 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 Clover Help.

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 the 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 select 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.

Device certificates

What is a device certificate?
A device certificate establishes trust between the point of sale (POS) application, the host operating system (OS) that runs the POS application, and the Clover device server certificate issued by the Clover Certificate Authority (CA). Each device needs a certificate. You need to install a Clover Device Server Root CA certificate on the POS application's host OS.

Do I need separate certificates for sandbox and production environments?
Clover provides separate certificates for sandbox and production use. Use the appropriate certificate for your environment. See Work with device server certificates for more information.

On the Secure Network Pay Display (SNPD) or REST Pay Display app, what is the Enable Development Certificate checkbox?
When using a Dev Kit in the sandbox environment, select the Enable Development Certificate checkbox to create a secure connection between your POS application and the Clover device. In the production environment, clear the checkbox.

I enabled the device certificate. What do I do now?
Click Configure and Restart Server any time you change the Clover Device Server settings. See Work with the device pairing screen for more information.

What is the Server is Secured checkbox?
The Server is Secured checkbox turns on and off the secure connection between the POS application and the Clover device. Clover recommends that you select the Server is Secured checkbox. See Select the connection protocol for more information.

How do I troubleshoot the message, Error connecting: RemoteCertificateChainErrors?
Possible solutions to this error include:

• Install the Clover Device Server Root CA certificate in the OS Trusted Root Certification Authorities Store.
• Install the correct certificate for the environment you are using. For example, use a sandbox device certificate with the Clover Dev Kit.
• Verify that you installed the Clover Device Server Root CA certificate inside the Trusted Root Certification Authorities Store.
• If you use a Clover production device, clear the Enable Development Certificate checkbox. The Enable Development Certificate checkbox is used only for sandbox devices.

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 must also 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 a third-party or not.

Alternatively, if you do not want to submit your passport and address, another associate of your corporation may do so. Log in to the Developer Dashboard and change the information in your developer app to correspond to the supporting 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. 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?

A merchant identifier, also known as merchantId or merchant_id is a universally unique identifier that Clover assigns to a merchant or business account authorized to use your app. An employee_id is a unique identifier assigned to the business owners, managers, and employees associated with the merchant_id. When reviewing the OAuth response], you can use the employee_id to view the current users. The merchant_id 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 lets you 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 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 your app's identity with the Clover server when you request an API token. The OAuth API token lets you access the Clover API for a specific merchant. See OAuth flows in Clover for more information.

Similarly, a merchant API token is used to access Clover APIs for specific test merchants. See Create an 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.

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 e-commerce 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 the Developer Dashboard. These IDs differ for sandbox and production accounts, so make sure you are logged into the correct environment.

Here is an example of how to locate the test merchant identifier (merchantId).

Miscellaneous

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:

What SSL/TLS cipher suites should my app support?

All Clover devices and servers follow the industry's best SSL/TLS configuration practices.

• SSL/TLS configuration—To make sure interoperability, you must make sure 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:

• 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.
Ciphers using HMAC-MD5, RC4, or single-key DES are not supported for security reasons.

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.

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 card type, you can retrieve unencrypted track data. Clover defines a financial card as one with the following:

• 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 swipe a non-financial card, such as an employee ID card, and retrieve the unencrypted track data. Clover Station cannot read non-financial cards.

📘

NOTE

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.

Voids and refunds

General

What are the timelines for performing a void, refund, or credit?

Voids, refunds, and credits are allowed under the following conditions:

• Void—Allowed when a transaction is authorized but not submitted for settlement. Within 25 minutes of a sale, the merchant can void a transaction. After 25 minutes, Clover processes it as a refund.
• Refund—Allowed once a settlement has begun. Refunds can be full or partial.
• Credit—Allowed on a credit or debit charge type.

Can a partial sale amount be voided?
No. Since a void cancels an authorization, you cannot void a transaction for less than the authorized amount.

Can I void a refund?
No. Voiding a refund is not possible currently.

Can debit card transactions be voided?
Yes, you can void debit card transactions.

Are debit transactions refundable?

For fraud prevention reasons, Clover lets you debit payment refunds if all of the following conditions are met:

1. The debit Application Identifier (AID) is a common AID.
2. It had a routing indicator of C to indicate that the payment was processed over credit rails. The routing indicator may or may not be returned in the XML response.
3. The merchant has a rare or special entitlement to indicate that debit refunds are allowed. Very few merchants receive this entitlement.

Where can I find more information about voids and refunds?
See the following resources for more information:

• Working with voids and refunds blog
• Transaction Types: Sales, Auths, Voids, and Refunds blog
• Handle voids and refunds —Semi-integration
• Refund payments — Ecommerce
• Reverse a payment — Clover Android Pay API

Semi-integration

I'm semi-integrating my point of sale (POS) with Clover. How do I reverse transactions?
The Clover Connector interfaces provide three ways for a semi-integrated POS to reverse transactions. Clover performs a void if it is possible to do so; that is, you don't have to know where the transaction is in its life cycle to reverse it.

Call the correct API for a particular instance. Then, Clover determines if it can process a void:

• VoidPayment performs voids. Call VoidPaymentRequest immediately following an incorrect transaction—for example, when a merchant realizes that they just charged the wrong amount.
• RefundPayment performs refunds. Call RefundPaymentRequest when time has passed since the transaction occurred, such as when a customer comes back to return an item. To get a refund, the customer uses the same card from the original transaction and inserts the card in the device when prompted.
• ManualRefund performs a credit. Call ManualRefundRequest when RefundPaymentRequest fails—for example, when a customer wants a refund for a debit transaction after the void window is closed. A manual refund occurs when a merchant refunds an amount without an associated sale or order. Manual refund is also known as credit, unmatched refund, unreferenced refund, or naked refund. Manual refunds are supported by Clover as follows:
  • US—Supported; reversals not supported. A reversal in this context means to void (or cancel) a manual refund.
  • Canada—Supported, including reversals of Interac manual refunds (coming soon).
  • UK/Ireland—Manual refunds are governed by an entitlement in the United Kingdom (UK) and Ireland. They are not allowed for Maestro cards. Reversals are not allowed.
  • Germany/Austria—Supported, including reversals.
  • Latin America (LATAM)—Not supported.

More Questions?

• Post or review questions on Clover Developer Community.
• Email Clover Developer Relations