Overview

If your app is a mobile, single-page, or native desktop application, it can not safely store the Client Secret (app_secret) and is known as a low-trust app. Low-trust apps use the response type token (implicit) auth code flow.

Clover requires that low-trust apps use the auth code flow with Proof Key for Code Exchange (PKCE) as shown in the OAuth code flow diagram. PKCE uses the code verifier and the code challenge to remove the need to pass the Client Secret.

You need to migrate your low-trust app to use the auth code flow with PKCE.

OAuth code flow with PKCE for low-trust apps

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.

Generate an access and refresh token pair using PKCE

Before you begin

See the OAuth terminology section to understand the key terms.

Prerequisites

For merchants in North America, you can use the global developer platform.

1. Create a global developer account.
2. Manage test merchant accounts and information.
3. Create your app in the sandbox environment.
4. Configure settings and permissions that your app requires to access Clover merchant data.
5. Required for the v2/OAuth flow—Set the Alternate Launch Path to redirect merchants to install and launch your app from the Clover App Market. See Set app link (URL) and CORS domain.

For merchants in Europe and Latin America—Argentina, you can use the developer platform and follow the steps to Get started with the developer platform.

Step 1: Generate code_verifier and code_challenge

In your app:

1. Generate a code verifier—Create a random string between 43 and 128 characters that is stored as part of the OAuth session.
2. Generate a code challenge—Use the code_verifierto generate thecode_challenge. For example, with the SHA-256 encryption, the code_challenge = SHA256(code_verifier).

Step 2: Request merchant authorization

The merchant needs to log in to the Clover Merchant Dashboard and install the developer's app from the Clover App Market. By installing the app, the merchant authorizes it to access the merchant's information that the app requires.

When an unauthorized merchant installs your app from the Clover App Market, they are redirected to log in to their Clover merchant account and then back to your app.

1. From your app, send a GET request to the /oauth/v2/authorize endpoint.
2. Include the query parameters: client_id, client_redirect_URL, and code_challenge.

https://apisandbox.dev.clover.com/oauth/v2/authorize?client_id={APP_ID}&redirect_uri={CLIENT_REDIRECT_URL}&code_challenge=${code_challenge}

Step 3: Receive an authorization code

Once a merchant is authorized, the Clover server redirects merchants to your app with an authorization code.

https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}

With the authorization code, the Clover server confirms that the merchant authorizes your request for merchant data. Use this code to further negotiate with the Clover server for an expiring OAuth token. Every time a merchant is redirected to your app, you can confirm whether the merchant has logged in to their Clover merchant account by checking for an authorization code in the redirect URL.

Step 4: Request and receive an access_token and refresh_token pair

To exchange the authorization code for an expiring OAuth token:

1. From your app, send a POST request to the /oauth/v2/token endpoint.
2. Include the query parameters: client_id, auth_code, and code_verifier.

When the Clover server responds to the request, retrieve the expiring OAuth token from your app server. The response body indicates when the access and refresh tokens expire, and the expiration dates are represented as Unix timestamps.

Request and Response example—Expiring OAuth token

{
  "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  
}

Related topics

• Clover v2/OAuth flow overview
• Generate OAuth expiring (access and refresh) token
• Blog: Expiring OAuth Tokens: Securing Clover Merchant Data