Developer guidelines

Welcome to the Clover App Market, the world’s largest point-of-sale app platform. As a third-party developer, your apps can add functionality and address new use cases for the rapidly expanding Clover merchant community.

The following guidelines are designed to help you produce high quality apps, with a smooth development and launch process. These foundations can help your apps provide the kind of excellent merchant experiences that attract and keep loyal subscribers.

Hardware

We strongly encourage all developers to order a Clover DevKit. DevKits enable you to experience transactions end-to-end from the merchant and customer perspectives. Access to the same environment your customers are using is invaluable.

Clover offers merchants custom POS hardware running our own Android-based software.

Best practices

There are several best practices you should follow while developing your app.

  • Before you get started, create a Clover Developer Account for the US App Market or EU App Market.
  • Design your app to respond to the needs of Clover merchants.
  • Design your app around Clover’s modules and merchant plans.
  • Ensure that your app complies with Clover’s App Market Policies.
  • Do not require users to manually input data that’s already accessible to your app via the Clover APIs (other than login credentials).
  • Implement OAuth tokens for authenticating with Clover. Using merchant generated tokens (from the Setup app) will subject your app to removal.
  • Use Clover data objects and representations within your app and configure them to synchronize with Clover services.
  • Set up your app to process all app fees, payment from the merchant for use of your app, and merchant-customer payments within Clover and/or First Data. Refer to the Developer Agreement for details.
  • Verify that any externally-generated data is syncing with the Clover platform correctly.
  • Thoroughly test your app. Apps that do not function as expected will be rejected.
  • Provide a good end-to-end experience. Apps that do not have a significant and reasonable amount of functionality may be rejected during the review process.
  • Familiarize yourself with Clover’s Developer Agreement and Launch Checklist before you submit your app for approval.

Best practices for API usage

Security

  • Protect sensitive customer and employee data. Do not expose names, addresses, or phone numbers publicly.
  • Never expose auth tokens or passwords of any kind.

Monetary calculations

  • Your app should calculate taxes using this algorithm.
  • Always pass in monetary values as longs representing the smallest denomination of the merchant’s currency.

Rate limiting

  • If your app or service must trigger requests from multiple merchants, these requests should be staggered as much as possible to avoid bursts of high traffic volume.
  • Use webhooks to trigger updates. Avoid constant polling.
  • Cache your own data when you need to store specialized values or rapidly review very large datasets.
  • Handle 429 error codes (rate limit reached) by responding with an exponential back-off.
  • If you need to backfill data, it is best to do so during non-peak business hours.
  • Use the Export API if backfilling more than the previous two months of order or payment data.
  • We maintain two rate limits on apps to ensure quality of service for both merchants and developers.
    • We maintain a rate limit of 16 requests per second for each token.
    • Apps also have a cross-token total rate limit of 50 requests per second.
    • If your product requires more capacity, please contact us and we will review your request.

Best practices

  • Don’t multithread client POST calls. This behavior can create system delays due to deadlocks.
  • Query with modifiedTime filters when possible to avoid repolling unmodified data.
  • Minimize data usage. Merchants may be on limited mobile data plans.

Android development

Best practices

  • We strongly encourage you to integrate some form of crash reporting utility into your Android products. This will help you maintain operational awareness of your product.
  • We also recommend that you collect metrics on app usage. This will help you build better products and increase your awareness of any issues.
  • To avoid confusing consumers, do not use the term PIN in your app.

Quality code

Your app should conform to the following Java and Android programming practices:

You should also understand the difference between compileSdkVersion, targetSdkVersion, and minSdkVersion.

Leverage the native Android buttons, such as the Back and Home buttons.

Device rotations

Note that display rotation is disabled on Clover Mobile and Clover Mini.

Clover Station uses display rotation when switching from merchant-facing mode to customer-facing mode. If your app will be available on Clover Station, it must gracefully handle display rotation.

Async tasks and executors

  • Minimize or eliminate work on the main UI thread.
  • Verify that your activity isn’t finished or destroyed upon completion of an AsyncTask’s background task.
  • Use a back-off switch when responding to errors and confirm normal functioning before proceeding, instead of starting new loops.

Security

Web

Security

Familiarize yourself with basic web security principles. The Open Web Application Security Project (OWASP) offers several resources that will help you get started:

Merchant data

  • Because the Clover API allows access to a database, you will need to follow the security standards for database access.
  • Web applications should access the Clover API via server-to-server requests when possible.
  • You must store any data that your own services cache securely.

Limiting client access

  • Customer and employee-facing apps must prevent unauthorized users from accessing privileged data, including the Clover credentials your app uses.
  • Use secure logins and session tracking if needed.
  • Server logic should prevent unauthorized access to data via injection.
  • Any data passed to the client in any format should be considered vulnerable.

Clover integration

  • Make it easy for merchants to login. The URL for your web app should launch the login flow, not navigate to the general home page for your business.
  • Include your Web URL prior to submission, and test it with an example OAuth request.
  • All apps must be mobile-friendly.

Design

Image assets

Your app’s Launcher Icons should be mipmap resources. Icons must conform to standard Android sizes:

  • Clover Station – 48 × 48 (mdpi)
  • Clover Mini/Mobile – 72 × 72 (hdpi)
  • Clover Mini/Mobile (first three apps) – 192 × 192 (xxxhdpi)

You can use third-party icon generators to resize your logo.

Graphic design

  • Be aware of the screen dimensions of all of the Clover devices you plan to support, and design with these dimensions in mind.
  • A single merchant may have any or all of the Clover devices. Aim for a consistent cross-device experience.
  • If your app will include a customer-facing component, your design will reflect on the business using your app. These interfaces should be pleasing and professional.

Usability

  • Your app will be used under fast-paced working conditions. Strive for clear, easy to use, and robust workflows that involve as few steps as possible.
  • App design should emphasize clarity and accessibility. Use high-contrast, readable fonts, as well as large text and inputs.
  • If you’re adapting an app that was developed for another platform, make sure it only includes features and buttons that are relevant to the Clover user.
  • Google’s Material Design Guidelines are a good place to start.

 Publishing

App details

Your app details must include:

  • A clear, detailed description outlining the app’s features and functionality.
  • High-resolution screenshots.
  • A help/FAQ site URL.
  • Contact information for merchant support.

You can improve your app’s visibility in the Clover App Market by including descriptive keywords in the tagline.

App pricing

  • Set your subscription levels, and be sure to enable and disable them as needed.
  • Consider a freemium model to make your app attractive to download.
  • You will not be able to alter metered, pay-per-action billing events after we’ve approved your app for the Clover App Market.
  • Review the Billing section for more details.

App submission

  • Be sure that your app does not infringe on the intellectual property rights of others, including the Clover brand. For example, do not use “Clover” or any other registered trademark in your app name, as this would imply ownership. You should also avoid using the Clover brand in the root domain of your help site.
  • The Clover App Market is live in the US, UK, and Republic of Ireland.  When submitting to a new market, be aware of the differences between each country, including local currency.
  • Developers must provide relevant login credentials and any other hardware or resources required to review your app.
  • If you have an Android app, you must submit the APK with the app. Once we’ve approved your submission, be sure to publish both.