Before you begin

All Ecommerce API endpoints require an OAuth-generated access_token with specific permissions. In this context, note the following:

• Existing (legacy) applications—Apps created before October 2023 use the legacy OAuth flow to generate an auth_token. For your apps to complete the Clover OAuth flow, you need to migrate to expiring authentication tokens using the v2/OAuth flow. See Migrate legacy OAuth API tokens to v2/OAuth expiring tokens.
• New applications—Apps created after October 2023 use the v2/OAuth flow to generate expiring authentication tokens, which include an access_token and refresh_token pair. For both new and existing apps, you can roll out the v2/OAuth flow all at once or as gradual rollouts.

Use this topic for instructions to generate an expiring (access and refresh) token with the v2/OAuth flow. 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. Start your ecommerce integration with a test app on the Global Developer Dashboard. See Get started with the Global Developer Dashboard.
2. Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to install and launch your app from the Clover App Market.

Steps

The Clover v2/OAuth flow starts when the merchant selects your app directly from the Clover App Market or on the Merchant Dashboard > More Tools > Clover App Market page. Clover redirects the merchant to your app with the merchantId included in the Redirect URI as a query parameter. From there, your app must call the /oauth/v2/authorize endpoint to initiate the v2/OAuth flow and get an access_token and refresh_token pair.

If a merchant accesses the app from your website instead of installing and connecting with it from the Clover App Market, your app needs to redirect the merchant to the Clover App Market page to install the app from there. The Alternate Launch Path is used in this case.

To generate an expiring access and refresh token pair:

1. Log in to the Global Developer Dashboard.

2. Navigate to the Merchant Dashboard for your test merchant.

3. From the left navigation menu, click More Tools, and then select your app on the Clover App Market page.

4. Click Connect to install your app for the test merchant.
   From here:

   1. For merchant authorization, Clover redirects the merchant to the location specified in the Alternate Launch Path field, and the app calls /oauth/v2/authorize with the authorization code as a query param to initiate OAuth.

      OAuth callback format

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

   2. For token exchange, your app makes a POST request with theclient_id, client_secret, and authorization_code to /oauth/v2/token. The response provides an access_token and refresh_token pair that displays on the OAuth Process Results page of your app.

      

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

Request and Response information

For detailed request and response information, see:

• Generate access and refresh tokens for high-trust apps
• Generate access and refresh token pair using PKCE for low-trust apps

Generate a new OAuth expiring (access and refresh) token

In the v2/OAuth flow, an expiring authentication token is generated. It consists of an access_token and refresh_token pair. The access_token is short-lived, while the refresh_token lasts longer but also expires eventually.

To maintain authorization, your app must generate a new token pair before the current one expires. To do so, send a POST request to the /oauth/v2/refresh endpoint with the existing refresh_token and client_id to generate a new access_token and refresh_token pair. Your app needs to handle the refreshing of access tokens to allow merchants continuous access to the app.

For information, see Use refresh token to generate new expiring token.

Related topics

• Blog: Expiring OAuth Tokens: Securing Clover Merchant Data
• Blog: Fiddling Through Digital Keys: Clover Auth Tokens and Ecommerce Keys