Set 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:
- On the Developer Dashboard, click App Settings on the side-nav.
- On the App Settings page, click Requested Permissions.
- 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.
- 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:
- Android apps: For your Android app, generate an API token using Clover Android SDK.
- Web apps: For your web app, generate an API token using OAuth 2.0.
- Testing your apps: Generate an API token using the Merchant Dashboard.
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
New Clover apps providing card-not-present payments should use the Ecommerce API. 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.
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 19 days ago