FAQ

My Devkit device indicates it is offline but it is connected to the internet, why is this happening?

We are aware of the issue and are currently addressing it. We will will have a solution for you soon.

Solution: DevAsk

My Devkit device is stuck at the activation step, it says “Error retrieving merchant information”, why is this happening?

We are aware of the issue and are currently addressing it. We will will have a solution for you soon.

Solution: DevAsk

How can I set up a test device for developing my app?

Developers can use the Development APKs to run the Clover Launcher from an emulator or personal Android device. See our Video Tutorial for a detailed walk through of setting up an emulated Clover Station

What is the merchantID? How does it relate to the employeeID?

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 employeeID 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 API calls.

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.

How can I get the merchantID and a merchant API Token for my own test merchant?

This video demonstrates how to get the merchantID and a basic merchant API Token for your own test merchant for use in development and testing. We strongly recommend that any production Clover app use OAuth API Tokens.

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

Have the merchant generate a token for you in the API Tokens section of the Setup App. This token has limited functionality (it does not support CORS) so you should only use it if OAuth is not an option.

How long do API tokens last?

API tokens will work until the merchant uninstalls your app.

How can my app differentiate between Clover devices and non-Clover devices?

See Targeting Clover Devices.

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 sales people are not billable, so you will not get paid for apps installed to these types of accounts.

  1. 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 use the Web API (V3 REST API) to create an order?

You can find detailed instructions for building an order with the REST API here.

How do I use the Web API to pay for an order?

  1. GET to /v2/merchant/{mId}/pay/key To get the encryption information you’ll need for the pay endpoint.
  2. Encrypt the card information
    1. Prepend the card number with the prefix fromGET /v2/merchant/{mId}/pay/key.
    2. Generate an RSA public key using the modulus and exponent provided byGET /v2/merchant/{mId}/pay/key.

      Note

      The modulus returned by Clover is in base 10. Various libraries expect moduli in different bases.

    3. Encrypt the card number and prefix from step 1 with the public key.
    4. Base64 encode the resulting encrypted data into a string which you will send to Clover in the “cardEncrypted” field.
  3. POST to /v2/merchant/{mId}/pay Pass the encrypted card data and order information to Clover in order to pay for the order.

When the order is paid, the order and payment data are automatically synchronized between the Clover Server and the merchant’s Clover devices.

Example Code – Java Example App

public static PublicKey getPublicKey(final BigInteger modulus, final BigInteger exponent) {
    try {
      final KeyFactory factory = KeyFactory.getInstance("RSA");
      final PublicKey publicKey = factory.generatePublic(new RSAPublicKeySpec(modulus, exponent));
      return publicKey;
    } catch (GeneralSecurityException e) {
      throw new BaseException(e);
    }
}
public static String encryptPAN(final String prefix, final String pan, PublicKey publicKey) {
   byte[] input = String.format("%s%s", prefix, pan).getBytes();
   try {
     Cipher cipher = Cipher.getInstance("RSA/None/OAEPWithSHA1AndMGF1Padding", "BC");
     cipher.init(Cipher.ENCRYPT_MODE, publicKey, RANDOM);
     byte[] cipherText = cipher.doFinal(input);
     return DatatypeConverter.printBase64Binary(cipherText);
   } catch (GeneralSecurityException ignore) {
     return null;
   }
 }

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 Intents and Broadcasts, or launch your own Activity.

More Questions?

Please ask your question on the Developer Community.