Set app permissions
Set data permission for your app
When you build an app, configure the settings and permissions that your app requires to access merchant data. When a merchant installs your app, they approve the permissions your app is requesting. Some permission sets control access to data containing Personal Identifiable Information (PII), which is protected by national or international law and regulations.
To get your app approved for installation on Clover devices, you must justify why you requested specific permissions. For any selected permission, provide a clear, in-line justification for how your app is using the permission. The Developer Relations (DevRel) team uses this information during the app approval process to ensure that only relevant permissions are requested and used by your app.
Before you begin
Based on your app, you require a specific set of data permissions from merchants. Points to note before you set or update app permissions:
- Request only the permissions your app needs from the merchant.
- If you change app permissions after a merchant downloads your app, for the new permissions to take effect, the merchant must uninstall and reinstall the app. This is applicable for test merchants also.
- For Android app permission settings to take effect:
- Clover must approve your app's Android Package Kit (APK).
- Merchant needs to uninstall and install your app on their Clover device.
- Clover generates a new APK token after the merchant installs the approved app.
- See information on Healthcare merchants and Clover support for HIPAA.
Watch video: Data minimization through app permissions
| Let's learn | Download slides |
|---|---|
| In this video, learn: - What is the importance of setting permissions in the app creation process? - What is Personal Identifiable Information (PII)? - How does PII relate to data minimization? - How you can remove unnecessary permissions? | View or download: Data minimization through app permissions slides. |
Understand permissions mapping
Clover REST API works with 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. For example, if your app retrieves data from the
GET /v3/merchants/{mId}/employeesendpoint, your app must have the Read employees permission granted by the merchant. - Actions that create, update, or delete merchant data require the Write permission. For example, if your app modifies information about a merchant’s employees using
POST /v3/merchants/{mId}/employees/{empId}, the Write employees permission is required.
Customer permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read customers Required to read customer information. | GET /v3/merchants/{mId}/customers | Retrieves all customers' information. |
GET /v3/merchants/{mId}/customers/{customerId} | Retrieves information for a customer. | |
| Write customers Required to add and update customer information. | POST /v3/merchants/{mId}/customers/{customerId} | Updates information of a customer. |
DELETE /v3/merchants/{mId}/customers/{customerId} | Deletes a customer record. |
Employee permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read employees Required to read employee information, for example: to view who created an order. | GET /v3/merchants/{mId}/employees | Retrieves all employees' information. |
GET /v3/merchants/{mId}/employees/{empId}/shifts | Retrieves all shift information of an employee. | |
| Write employees Required to add and update employees. | POST /v3/merchants/{mId}/employees/{empId}/shifts | Creates a shift for an employee. |
DELETE /v3/merchants/{mId}/employees/{empId} | Deletes an employee record. |
Inventory permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read inventory Required to read inventory. | GET /v3/merchants/{mId}/inventory/items | Retrieves all items in a merchant's inventory. |
GET /v3/merchants/{mId}/inventory/categories | Retrieves all categories and the number of items in each category. | |
GET /v3/merchants/{mId}/inventory/discounts | Retrieves all custom discounts. | |
GET /v3/merchants/{mId}/inventory/modifiers/groups | Retrieves all modifier groups. | |
| Write inventory Required to add and update inventory. | POST /v3/merchants/{mId}/items | Adds a list item to an inventory. |
POST /v3/merchants/{mId}/inventory/items/{itemId} | Updates a list item. | |
DELETE /v3/merchants/{mId}/categories/{categoryId} | Deletes a category. |
Merchant permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read merchant Required to read merchant properties, for example: to view basic information for a merchant. | GET /v3/merchants/{mId}/tip_suggestions | Retrieves all tip suggestions for a merchant. |
GET /v3/merchants/{mId}/address | Retrieves a merchant address. | |
| Write merchant Required to update merchant properties. | DELETE /v3/merchants/{mId}/order_types/{orderTypeId} | Deletes an order type. |
POST /v3/merchants/{mId}/properties | Updates a merchant's properties. |
Order permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read order Required to read order information. | GET /v3/merchants/{mId}/orders | Retrieves all orders. |
GET /v3/merchants/{mId}/orders/{orderId}?expand=customers | Retrieves customers for an order. | |
| Write order Required to add and update an order. | POST /v3/merchants/{mId}/orders/{orderId}/line_items | Adds a new line item to an order. |
POST /v3/merchants/{mId}/orders/{orderId} | Adds a new order. |
Payments permissions
| Permissions | Sample REST API calls: Operation | Description |
|---|---|---|
| Read payments Required to read payment information. | GET /v3/merchants/{mId}/orders/{orderId}/payments | Retrieves the payment summary for an order. |
GET /v3/merchants/{mId}/payments/{paymentId} | Retrieves a single payment. | |
| Write payments Required to add and update payment records. | POST /v3/merchants/{mId}/orders/{orderId}/payments | Adds payment data to an order. |
Ecommerce API permissions
| Permissions | Sample Ecommerce API calls: Operation | Description |
|---|---|---|
| Use for Clover apps providing card-not-present payments in the United States (US) and Canada. See Ecommerce app permissions for more information about permissions required for using the Ecommerce API. | POST /v2/merchant/{mId}/pay | Processes a credit card payment. |
View or set up app permissions
- Log in to your sandbox Developer Dashboard.
- From the left navigation menu, click Your Apps > App name > App Settings. The App name - App Settings page appears. You can view and configure settings and permissions that your app requires to access merchant data.
- Click Requested Permissions. The Edit Requested Permission page 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 display on the App Settings page.
Use app API token to request for merchant data
Based on the app permissions you set, use your app's API token to request for merchant data:
- Android apps—Query web services and generate a token using Clover Android SDK.
- Web apps—Use OAuth 2.0 to generate an API token.
- Test apps—Generate an API token on the Test Merchant Dashboard.
Healthcare merchants and Clover support for HIPAA
Limited app permissions for healthcare merchants
Due to Health Insurance Portability and Accountability Act (HIPAA) requirements, Clover restricts healthcare merchants in the specific categories from installing apps that require Read or Write permissions for customers or inventory. When merchants from any of these categories try to install apps from the Clover App Market requiring these permissions, a banner notification displays. The Install button is also not available for these apps.
Restricted merchant category codes (MCCs) for HIPPA compliance:
| MCC | 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) |
Scope of Clover HIPAA support
Clover uses merchant category codes (MCCs) to categorize merchants as healthcare merchants. These merchants must comply with HIPAA. Healthcare merchants can use Clover for Healthcare without requiring Clover to sign a HIPAA Business Associate Agreement.
- Clover for healthcare takes advantage of a transaction-processing exemption within HIPAA and is HIPAA exempt.
- Clover for healthcare is designed to limit protected healthcare information (PHI) use to payment processing only. HIPAA rules exempt financial institutions from HIPAA, to the extent that PHI is used solely for processing payments for healthcare.
Updated 4 days ago