Set app permissions
Set data permission for your app
When you build an app, configure the settings and permissions that it requires to access merchant data. When a merchant installs your app, they approve the permissions your app requests. 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 make sure 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, the merchant must uninstall and reinstall the app for the new permissions to take effect. This is also applicable to test merchants.
- 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
| Watch | Learn |
|---|---|
|
|
In this video, learn:
View and download: Data minimization through app permissions slides |
Understand permissions mapping
The 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 the Developer Dashboard.
- From the left navigation menu, click Your Apps > App name > App Settings. The App name—App Settings page appears. Here, you can view and configure the 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 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 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 5 months ago