Initiate v2/OAuth flow from the Clover App Market
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 | apisandbox.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 |
Partial v1/OAuth flow
Prior to the implementation of the Clover v2/OAuth flow, when a merchant installed or connected to an app from the Merchant Dashboard > More Tools > Clover App Market page or directly from the Clover App Market, Clover redirected the merchant through a partial OAuth flow.
The partial OAuth flow bypasses the /oauth/authorize endpoint
, goes directly to /oauth/merchants/{merchantID}
, and then redirects to the app’s main access link or site URL with an authorization code or auth_code
. This skips the initial step of the OAuth flow, as seen in the following diagram:
Complete v2/OAuth flow initiated from the Clover App Market
IMPORTANT
From August 2024, Clover requires new apps to use the v2/OAuth flow. For both new and existing apps, you can roll out the v2/OAuth flow all at once or as gradual rollouts.
Prerequisite
Merchant must install your app so that your app can initiate the v2/OAuth flow.
v2/OAuth flow
The Clover v2/OAuth lets your app have full control of the OAuth flow as follows:
- Merchant selects the installed app from the:
- Clover App Market.
- Merchant Dashboard > More Tools > Clover App Market page.
- Clover redirects the merchant to your app’s main access link or site URL with a merchantId.
- App calls the
/v2/authorize
endpoint to initiate the OAuth flow. See Generate a v2/OAuth token.
The v2/OAuth flow takes into account both high-trust and low-trust apps, as seen in the following diagram:
- High-trust apps exchange an authorization code for an
access_token
. After the redirect URL returns the merchant to the app, the app receives the authorization code from the URL and uses it to request anaccess_token
. - Low-trust apps use the authorization code flow with a proof key for code exchange (PKCE).
Set and use the Alternate Launch Path for apps
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 the merchant to the Clover App Market. The Alternate Launch Path sends the merchant directly to your app on the Clover App Market and initiates the v2/OAuth flow.
Prerequisite
Enter your app’s Alternate Launch Path on the Global Developer Dashboard in the Edit REST Configuration web app settings. This alternate subpath uses the same base domain as the site URL.
v2/OAuth flow
The v2/OAuth flow using the Alternate Launch Path is when an app is not previously installed.
- Merchant accesses the app on your website or clicks Connect for the app in the Clover App Market.
- App redirects the merchant to the location specified in the Alternate Launch Path field.
- App calls the
/v2/authorize
endpoint to initiate the OAuth flow. See Generate a v2/OAuth token.
Related topics
Updated 30 days ago