Generate OAuth expiring (access and refresh) token
Prerequisites and steps for generating an access_token
and refresh_token
pair using the v2/OAuth flow
All Ecommerce API endpoints require an OAuth-generated access_token
with specific permissions. The v2/OAuth flow is used for new apps created for Clover merchants in North America—United States and Canada. This flow generates expiring tokens, which include an access_token
and refresh_token
pair.
NOTE
If your app is using the legacy v1/OAuth flow and has not yet migrated to generate expiring tokens, see Generate OAuth API token with the legacy v1/OAuth flow.
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:
-
Create your app in the sandbox environment.
-
Configure settings and permissions that your app requires to access Clover merchant data. For more information, see Ecommerce app permissions.
-
Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to this link after they install and launch your app from the Merchant Dashboard.
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 URL as a query parameter. From there, your app must call the /oauth/v2/authorize
endpoint to initiate the OAuth flow and get an access 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.
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:-
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}`
-
For token exchange, your app makes a POST request with—
client_id
,client_secret
, andauthorization_code
—to/oauth/v2/token
. In response, an access and refresh token pair is retrieved.
-
Once the authorization flow is complete, the page for your app displays the access and refresh token pair. 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).
Sandbox and production environment URLs
Clover sandbox and production environments use different URLs. The following table lists which URL to use for OAuth requests in each environment.
Request path | Sandbox URL | Production URL (North America) |
---|---|---|
/oauth/v2/authorize | sandbox.dev.clover.com | www.clover.com |
/oauth/v2/token | apisandbox.dev.clover.com | api.clover.com |
/oauth/v2/refresh | apisandbox.dev.clover.com | api.clover.com |
/oauth/token/migrate_v2 | apisandbox.dev.clover.com | api.clover.com |
Related topics
Updated 12 days ago