Generate OAuth expiring (access and refresh) token

Prerequisites and steps for generating an access_token and refresh_token pair to build Clover Ecommerce app integrations.

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 token, you need to complete the following:

Start your ecommerce integration with a test app on the Global Developer Dashboard. See Get started with the Global Developer Dashboard.
Set the Alternate Launch Path—Required when the app OAuth is initiated from the left navigation menu on the Merchant Dashboard or directly from the Clover App Market. See Set app link (URL) and CORS domain.

App Settings on the Developer Dashboard: Edit REST Configuration page

Steps

The Clover OAuth flow starts when the merchant selects your app directly from the Clover App Market or from the left navigation on the Merchant Dashboard (More Tools > Clover App Market). 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 or connecting to it from the Clover App Market, your app needs to redirect to the /oauth/v2/authorize endpoint.

To generate an expiring access and refresh token pair:

Log in to the Global Developer Dashboard.
Navigate to the Merchant Dashboard for your test merchant.
From the left navigation menu, click More Tools, and then select your app on the Clover App Market page.
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.
```
`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.
  
  Sample: Access and Refresh token pair

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).

For more information, see:

Request and Response example

Expiring OAuth token for high-trust app

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/v2/token' \
--header 'content-type: application/json' \
--data '{
    "client_id": "{APP_ID}",
    "client_secret": "{APP_SECRET}",
    "code": "{AUTHORIZATION_CODE}"
}'

{
    "access_token": "{ACCESS_TOKEN}",
    "access_token_expiration": 1677875430,
    "refresh_token": "{REFRESH_TOKEN}",
    "refresh_token_expiration": 1709497830
}

Expiring OAuth token for low-trust app

curl --request POST \
--url 'https://apisandbox.dev.clover.com/oauth/v2/token' \
--header 'content-type: application/json' \
--data '{
    "client_id": "{APP_ID}",
    "code": "{AUTHORIZATION_CODE}",
    "code_verifier": "{CODE_VERIFIER}"
}'

{
"access_token": "{ACCESS_TOKEN}",  
"access_token_expiration": 1677875430,  
"refresh_token": "{REFRESH_TOKEN}",  
 "refresh_token_expiration": 1709497830  
}

Migrate to v2/OAuth expiring tokens

All Ecommerce API endpoints require an OAuth-generated access_token with specific permissions. 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 from the legacy OAuth flow to expiring authentication tokens using the v2/OAuth flow. For information on the legacy OAuth flow, see Generate OAuth token with the legacy OAuth flow.