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. See Generate Ecommerce API tokens (public and private keys).
API tokens for test and published apps
In the Clover production environment, expiring access-token and refresh_token1 pair is 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, generate OAuth expiring (access and refresh) token.
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 test API Tokens on the test Merchant Dashboard, as described in this topic. |
| 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 Clover OAuth flow to generate OAuth expiring (access and refresh) 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 expiring 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: - Generate Ecommerce API public and private tokens to authenticate API requests for a single merchant solution and for test scenarios. These keys are also used to integrate online payments with your ecommerce website. - Generate an OAuth expiring access_token to build an ecommerce app for multiple businesses that need to authenticate users and maintain sessions securely.- Tokenize customer cards and use the Clover Ecommerce API for 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 left navigation menu, in the bottom panel, click Test Merchants. The Test Merchants page displays the list of test merchants.
- From the Actions column, click the Launch Dashboard icon next to a merchant name. The Merchant Dashboard appears.
- From the top-right menu, click Settings > View all settings. The Settings page appears.
- In the Business Operations section, click API tokens. A Welcome to Clover API Tokens pop-up appears.
Merchant Dashboard: Welcome to Clover API Tokens pop-up
-
Review the information and click Get Started. The URL wants to Know your Location pop-up appears.
-
Click Allow to let the dashboard access your location. The API Tokens page appears.
- If you have previously generated an API token, it displays on the page. You can create as many merchant-specific test API tokens as required.
- If you have not created any API tokens, the Tokens section on the page is blank.
Merchant Dashboard: API Tokens page
- Click Create new token. The Create new token pop-up displays app permissions that map to platform API endpoints.
- 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.
Merchant Dashboard: Create new token (permissions)
- Click Create Token. The new token displays in the Tokens section.
Merchant Dashboard: API Tokens
- 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 2 days ago