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.

Complete v2/OAuth flow initiated from the Clover App Market

🚧

IMPORTANT

From October 2023, Clover requires apps to use the v2/OAuth flow.

Prerequisite

The 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:

1. Merchant selects the installed app from the:
   • Clover App Market.
   • Merchant Dashboard > More Tools > Clover App Market page.
2. Clover redirects the merchant to your app’s main access link or site URL with a merchantId.
3. 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 an access_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 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.

1. Merchant accesses the app on your website or clicks Connect for the app in the Clover App Market.
2. App redirects the merchant to the location specified in the Alternate Launch Path field.
3. App calls the /v2/authorize endpoint to initiate the OAuth flow. See Generate a v2/OAuth token.

---

[For Reference only] Partial (legacy) 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:

---

Related topics

• Redirect merchants to your app
• Set app link (URL) and CORS domain
• Migrate legacy OAuth tokens to v2/OAuth expiring tokens
• High-trust apps—Auth code flow
• Low-trust apps—Auth code flow with PKCE