Generate a merchant-specific test API token
API tokens overview
Clover uses the industry-standard OAuth 2.0 protocol for authentication. Generating an API token is a fundamental part of the OAuth flow to enable secure, controlled, and auditable access to APIs.
Use API tokens to:
- Authenticate requests to Clover REST APIs.
- Secure the communication between an app integration and your merchant account.
- Allow an app to access and create merchant data, such as payments, orders, and inventory.
- Integrate online payments with your e-commerce website. To generate an Ecommerce API token, see Clover Help.
API tokens for test and published apps
In the Clover production environment, expiring access and refresh tokens are used to secure merchant data. In the sandbox environment, you can access the test Merchant Dashboard and create a merchant-specific API token to test your app.
IMPORTANT
Use the test API tokens generated in your test Merchant Dashboard only for testing the API in the sandbox environment. Do not use the test merchant API tokens in the production environment. For the production environment, use access and refresh tokens following the region-specific OAuth flow.
A brief overview of tokens and OAuth flow in the sandbox and production environment is as follows:
| S.no. | Tokens based on environment | Description |
|---|---|---|
| 1. | API tokens to test apps in sandbox | To test your app in the sandbox environment, generate API test tokens on the test Merchant Dashboard. |
| 2. | API tokens to test apps in production | To test your app in the production environment, use one of the following: - For Web apps: Use the relevant OAuth flow based on regions to generate an auth_token. - For Android apps: Use the Android SDK to generate an API token and query web services. |
| 3. | API tokens for published apps | The OAuth flow typically begins when a merchant selects and installs your app from the Clover App Market. The app then goes through the OAuth process to obtain an access token, which is used to make authenticated API calls. To create the OAuth flow for published apps, replace https://sandbox.dev.clover.com/ with the correct regional base URL in your requests, such as: - North America: https://clover.com/ - Europe: https://eu.clover.com/ - Latin America: https://la.clover.com/ |
| 4. | API tokens for ecommerce apps and integrations | To simulate different ecommerce integration type settings and scenarios, including the steps to authenticate and authorize: - Create public and private merchant-specific API tokens for configuring Clover payment integrations to take online payments on an ecommerce site. - Generate OAuth token to complete the Ecommerce API authorization flow. See Authenticate with OAuth—Canada and US. - Tokenize customer cards and use the Clover Ecommerce API for payment flows. See Ecommerce API: Accept payment flows. |
Generate a merchant-specific test API token in sandbox
With your test API token, you can make a REST API call and access Clover merchant data. You can create as many merchant-specific test API tokens as required.
Prerequisites
Steps
- Log in to the Developer Dashboard.
- From the Developer Account drop-down list, select a merchant name under Businesses. The test Merchant Dashboard appears.
- From the left navigation menu, click Account & Setup. The Account & Setup page appears.
- In the Business Operations section, click API Tokens.
Test Merchant Dashboard: Account & Setup page
The API Tokens page appears.
Test Merchant Dashboard: API Tokens
- Click Create New Token. The Create new token pop-up displays app permissions that map to platform API endpoints. See API Reference > Platform API section.
Create new token pop-up
- Enter a token name.
- Select checkboxes to set permissions based on the test merchant information you want to manage. API tokens are scoped to grant specific permissions to make sure that apps only have access to the resources they need.
- Click Create Token. The new token displays in the Tokens section. Use this token as the Bearer token to make calls to the Clover Platform API endpoints.
- Expand the Permissions section to view or edit the permissions associated with the API token.
Test apps in sandbox
When making a REST API call, you must include an Authorization header set with a Bearer token, and the test merchant-specific API token as the credential.
- Create an app and note the App ID and App Secret.
- Connect your app with your test merchant to receive the authorization code in the URL of your installed test app.
- Note the following information to negotiate with the Clover server for an API token that you can use to make REST API calls:
| ID | Description |
|---|---|
| App ID (Client ID) | App ID or Client ID that uniquely identifies an app on Clover App Market. |
| App Secret (Client Secret) | App Secret or Client Secret is a secret key that Clover assigns to your app. Note: Both the App ID and App Secret are automatically assigned when you create an app. You can view the App ID and App Secret on the App name - App Settings page. These values are required for you to make authorized and authenticated requests to Clover merchant data. |
| Merchant ID | Merchant identifier or merchantId that uniquely identifies Clover merchants, including test merchants, on the Clover platform. See Locate the test merchant identifier (merchantId). |
| Authorization Code | An authorized merchant who has signed into Clover is redirected to your app along with an authorization code. The authorization code is a temporary code that the Clover server provides after the merchant is authenticated. This code is exchanged for an access token during the OAuth flow. |
| API Token | Your app uses the Authorization Code, Client ID, and Client Secret to negotiate with the Clover server for an API token. With the API token, your app can make REST API calls and access merchant data. See Use Clover REST API. |
Updated 4 months ago