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

Prerequisite

From October 2023, Clover requires apps to use the v2/OAuth flow. The merchant must install or connect to 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

Prerequisite

Add a link (URL) path for your app on the Edit REST Configuration page for web apps. This path uses the same base domain as the site URL. The alternate launch path is required when the app OAuth is initiated from the left navigation menu on the Merchant Dashboard or directly from the Clover App Market.

v2/OAuth flow

The v2/OAuth flow using the Alternate Launch Path is when an app is not previously installed.

1. Merchant 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.

[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