Clover Platform Docs

Setting app permissions

Watch Webinar

Review Clover's webinar on data minimization in the app permissions process. Here’s what you will learn in the webinar:

  • The significance of permissions in the app-making process
  • What is PII? How does PII relate to data minimization?
  • Tips for trimming unnecessary permissions

You can view or download the webinar slides here.

Based on the features you are building in your app, you will require a specific set of data permissions from merchants. When a merchant installs your app, they approve the permissions your app is requesting.

🚧

IMPORTANT

You must only request the permissions your app needs.

If you change app permissions after a merchant (including your test merchant) downloads your app, the new permissions don't take effect until the merchant uninstalls and reinstalls the app.

Clover generates a new APK token:

  • After approving your new APK
  • When a merchant uninstalls and reinstalls your app

πŸ“˜

NOTE

For any of your Android app permission settings to take effect, your app's APK must be approved and a Clover merchant must install your app on their Clover device.

Provide permission justifications

Certain permission sets control access to data containing Personally Identifiable Information (PII). PII is protected by national or international law and regulations. Hence, you must justify why you requested for those specific permissions before Clover approves your app for installation on Clover devices.

While setting your app permissions, provide in-line justifications about how your app is using this information. The Developer Relations team uses this information during the app approval process to ensure only relevant permissions are requested and used by your app.

Set up app permissions

To view or set app permissions for your app:

  1. On the Developer Dashboard, click App Settings on the side-nav.
  2. On the App Settings page, click Requested Permissions.
  3. On the Edit Requested Permissions modal that appears, select your app's READ or WRITE permissions for each REST API endpoint as required. For any selected permission, provide a clear justification for how your app is using this information.
  4. Click Save. Your selected permissions appear on the App Settings page.

Based on the permissions you set, you can use your app's API token to request for Clover merchant data:

Understand permissions mapping

Clover's REST API is divided into categories of data such as inventory, orders, and merchants. Each category of endpoints in the Clover REST API corresponds to either a Read or Write permission.

Actions that retrieve data from an endpoint require the merchant to grant your app the Read permission. Actions that create, update, or delete merchant data require the Write permission.

For example, if your app retrieves data from the GET /v3/merchants/{mId}/employees endpoint, your app must have the Read employees permission granted by the merchant. If your app modifies information about a merchant's employees using POST /v3/merchants/{mId}/employees/{empId}, the Write employees permission is required.

Read customers

The Read customers permission is required to read customer data.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/customers

List all customers

GET /v3/merchants/{mId}/customers/{customerId}

Retrieve the specified customer

Write customers

The Write customers permission is required to add and update customer data.

Sample REST API calls

Operation

Description

POST /v3/merchants/{mId}/customers/{customerId}

Update the specified customer

DELETE /v3/merchants/{mId}/customers/{customerId}

Delete the specified customer

Read employees

The Read employees permission is required to read employees. If you want to see who created an order, you'll need this permission.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/employees

List all employees

GET /v3/merchants/{mId}/employees/{empId}/shifts

Retrieve all shifts of the specified employee

Write employees

The Write employees permission is required to add and update employees.

Sample REST API calls

Operation

Description

POST /v3/merchants/{mId}/employees/{empId}/shifts

Create a shift for the specified employee

DELETE /v3/merchants/{mId}/employees/{empId}

Delete the specified employee

Read inventory

The Read inventory permission is required to read inventory.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/inventory/items

List all items in the merchant's inventory

GET /v3/merchants/{mId}/inventory/categories

List all categories and the number of items in each category

GET /v3/merchants/{mId}/inventory/discounts

List all custom discounts

GET /v3/merchants/{mId}/inventory/modifiers/groups

List all modifier groups

Write inventory

The Write inventory permission is required to add and update inventory.

Sample REST API calls

Operation

Description

POST /v3/merchants/{mId}/items

Add a list item to the inventory

POST /v3/merchants/{mId}/inventory/items/{itemId}

Update the specified list item

DELETE /v3/merchants/{mId}/categories/{categoryId}

Delete the specified category

Read merchants

The Read merchants permission is required to read merchant properties. If you want to see basic information about a merchant, you'll need this permission.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/tip_suggestions

List all tip suggestions for a merchant

GET /v3/merchants/{mId}/address

List the specified merchant's address

Write merchants

The Write merchants permission is required to update merchant properties.

Sample REST API calls

Operation

Description

DELETE /v3/merchants/{mId}/order_types/{orderTypeId}

Delete the specified order type

POST /v3/merchants/{mId}/properties

Update the specified merchant's properties

Read orders

The Read orders permission is required to read orders.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/orders

List all orders

GET /v3/merchants/{mId}/orders/{orderId}?expand=customers

Retrieve the customer(s) for an order

Write orders

The Write orders permission is required to add and update orders.

Sample REST API calls

Operation

Description

POST /v3/merchants/{mId}/orders/{orderId}/line_items

Add a new line item to an order

POST /v3/merchants/{mId}/orders/{orderId}

Add a new order

Read payments

The Read payments permission is required to read payments.

Sample REST API calls

Operation

Description

GET /v3/merchants/{mId}/orders/{orderId}/payments

Retrieve the payment summary for an order

GET /v3/merchants/{mId}/payments/{paymentId}

Retrieve a single payment

Write payments

The Write payments permission is required to add and update payment records.

Sample REST API call

Operation

Description

POST /v3/merchants/{mId}/orders/{orderId}/payments

Add payment data to an order

Ecommerce API permissions

πŸ“˜

NOTE

The Developer Pay API is superseded by the Ecommerce API. New Clover apps providing card-not-present payments should use the Ecommerce API instead of Developer Pay. The Ecommerce API is currently available in US and Canada. We will continue expanding availability to other regions.

See Ecommerce app permissions for more information about permissions required for using the Ecommerce API.

The Online payments permission is required to process credit card payments using the Developer Pay API. The Developer Pay API is available for merchants only in the US (see Developer Pay API for more information).

πŸ“˜

NOTE

The Write payments permission must also be enabled to process payments using the Developer Pay API.

Sample REST API call

Operation

Description

POST /v2/merchant/{mId}/pay

Processes a credit card payment

Limited app permissions for Healthcare merchants

Due to HIPAA requirements Clover restricts merchants in the following categories from installing apps that require read or write permissions for customers or inventory. Review this table to see the Merchant Category Codes (MCC) and their descriptions.

MCC Code

MCC Description

4119

Ambulance

5975

Hearing Aids

5976

Orthopedic Goods Artificial Limbs

5912

Pharmacies or Drug Stores

8011

Doctors and Physicians (Not Classified Elsewhere)

8021

Dentists and Orthodontists

8031

Osteopaths

8041

Chiropractors

8042

Optometrists and Ophthalmologists

8043

Opticians, Opticians Goods and Eyeglasses

8049

Podiatrists and Chiropodists

8050

Nursing and Personal Care Facilities

8062

Hospitals

8071

Medical and Dental Laboratories

8099

Medical Services and Health Practitioners (Not Classified Elsewhere)

Merchants will not see the Install button for such apps on Clover's App Market. If a merchant attempts to install an app that requires these permissions, they will be notified with a banner on Clover's App Market.

Scope of Clover HIPAA support

Clover uses MCCs to categorize merchants as healthcare merchants. These merchants must comply with HIPAA.

  • Clover for Healthcare is HIPAA exempt.
  • Clover for Healthcare takes advantage of a transaction-processing exemption within HIPAA and is HIPAA exempt.
  • HIPAA rules exempt financial institutions from HIPAA, to the extent that protected healthcare information is used solely for processing payments for healthcare. Clover for Healthcare is designed to limit PHI use to payment processing only.

🚧

IMPORTANT

Healthcare merchants can use Clover for Healthcare without requiring Clover to sign a HIPAA Business Associate Agreement.

Updated 20 days ago


Setting app permissions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.