All Ecommerce API endpoints require an OAuth-generated access_token with specific permissions. The legacy v1/OAuth flow is used for apps created before August 2024 that have not yet migrated to using expiring tokens.

📘

NOTE

Expiring tokens are generated using the new v2/OAuth flow for apps created for Clover merchants in North America. If you have migrated to using expiring tokens, see Generate OAuth expiring access and refresh token.

Before you begin

See the OAuth terminology section to understand the key terms.

Prerequisites

Before you can get an OAuth API token, you need to complete the following:

1. Create a global developer account.

2. Manage test merchant accounts and information.

3. Create your app in the sandbox environment.

4. Configure settings and permissions that your app requires to access Clover merchant data. For more information, see Ecommerce app permissions.

   

Steps

1. Log in to the Global Developer Dashboard.
2. Navigate to the Merchant Dashboard for a test merchant.
3. From the left navigation menu, click More Tools, and then select your app on the Clover App Market.
4. Click Connect to install your app for the test merchant.
   From here:
   • Request merchant authorization—When an unauthorized merchant selects and installs your app from the Clover App Market, the Clover server redirects the merchant to log in to their merchant account using the following URL format:
     Unauthorized merchant redirect URL format

     `https://sandbox.dev.clover.com/oauth/authorize?client_id={APP_ID}&redirect_uri={CLIENT_REDIRECT_URL}`
     

   • Receive an authorization code—After authorization, the Clover server redirects the merchant to your app using the Site URL from App Settings > REST Configuration. The redirect URL format includes a set of parameters and an authorization code in the URL:
     OAuth callback format

     `https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&employee_id={EMPLOYEE_ID}&code={AUTHORIZATION_CODE}`
     

     

5. Send a GET request using Postman to the following URL using:

• App ID as the client_id,
• App Secret from the App Settings page as the client_secret, and
• Authorization code as the code

https://sandbox.dev.clover.com/oauth/token?client_id={appId}&client_secret={APP_SECRET}&code={AUTHORIZATION_CODE

https://sandbox.dev.clover.com/oauth/token?client_id=RKxxxxxxxxS9C&client_secret=d46dxxxx-xxxx-xxxx-xxxx-xxxxxxxx1b77&code=1ccdxxxx-xxxx-xxxx-xxxx-xxxxxxxea1b

In response, the Clover server displays an API access token.

{
   "access_token":"{API_TOKEN}"
}

{
    "access_token": "ce7exxxx-xxxx-xxxx-xxxx-xxxxxxxx4b24"
}

Use this API access_token to generate an Ecommerce API key that you need to tokenize a card. See Generate an Ecommerce API key (PAKMS key).

Production environment URL

In production, your app server needs to handle the merchant user, who is redirected from Clover to your server, once they connect to your app. To build the OAuth flow for apps on the Clover App Market, in production environments, replace https://sandbox.dev.clover.com/ with the base URL in your requests for United States (US) and Canada: https://www.clover.com/

Related topics

• Authenticate with OAuth—Canada and US
• Blog: Expiring OAuth Tokens: Securing Clover Merchant Data
• Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys