General FAQs

How can I get a merchant-generated API token without creating a public Clover app?

If you're not building a public-facing app and don’t want to go through the OAuth flow, you can use merchant-generated API tokens. These tokens allow you to authenticate API requests without requiring merchants to install an app. Use this token to authenticate API calls for that specific merchant account. This method is ideal for internal tools or integrations where you control both the application and the merchant environment.

Do I need a different access token for each Clover REST API?

No, access tokens in Clover are merchant-specific, not API-specific. A single token grants access to all Clover REST APIs for the associated merchant account, provided your app has been granted the required permissions (scopes) for those specific endpoints. For more information, see Create merchant-specific API token.

Can I generate OAuth codes server-side without a user interface?

No, you cannot generate the initial code server-side without a user interface because the merchant must manually approve the permissions your app is requesting. You must redirect the merchant to the Clover OAuth authorization URL to grant access.

Do I need to generate a new OAuth code for every transaction?

No. Once the merchant installs your app and authorizes it, you can reuse the access token until it expires. Clover apps use expiring tokens, which include a refresh_token to get a new access_token without re-prompting the merchant. OAuth tokens are not tied to individual customer cards.

Can I use the Ecommerce API token directly from the server without OAuth

The Ecommerce API requires a valid OAuth token for authorization. Every request to https://scl.clover.com/v1/... (Charges, Orders, Customers) must include the OAuth access_token in the Authorization: Bearer header. Without it, the server will return a 401 Unauthorized error.

Can I implement Clover Pay without redirecting users to the Clover OAuth login page for username and password?

The Clover OAuth 2.0 flow requires merchant authentication through the Clover login page. This is a mandatory step to ensure that the merchant explicitly grants permission to your app. The redirect to the login page is part of the standard OAuth authorization process and cannot be bypassed.

However, if your integration is intended for only one merchant, you can use a merchant-generated token. It allows you to access Clover APIs for that specific merchant without initiating the full OAuth flow. For broader integrations involving multiple merchants, the OAuth flow with login redirection is required. See Clover OAuth flow overview.

How does OAuth work for Clover users with multiple Merchant IDs (MIDs), and how can I process payments for different merchant locations without user interaction?

When a user with multiple MIDs under one account initiates OAuth, they are prompted to select a specific merchant location to authorize. Each selection generates a unique, merchant-specific access token. While you cannot use the OAuth request to bypass the selection screen entirely, if a merchant launches your app directly from their Clover Dashboard, Clover will automatically append the specific merchant_id to your redirect URL to establish context.

Each merchant must have its own OAuth token or API token. You don’t need a new token for every payment, but you do need a separate token per merchant. If you're not building a public-facing app, the recommended approach is:

• Use merchant-generated API tokens for a simpler, app-less integration. Merchants can generate these from their Clover Dashboard.
• Alternatively, use OAuth tokens, but each merchant must authorize your app once. You can then reuse the refresh token to generate new access tokens as needed.
• Use the PAKMS Key for Ecommerce tokenization. It is static for each App ID and Merchant ID pair. You only need to retrieve it once and store it alongside the merchant's other credentials.

You won’t see a way to link merchants to your app in the Dashboard unless it’s published. For internal use, manage tokens per merchant and ensure each account is properly configured for the payment types you support.

Why does Clover OAuth API use a different timestamp format than other APIs?

Clover OAuth API returns token expiration times in Unix timestamp format (seconds), which is typically 10 digits. Other Clover APIs, like /v1/customers, use Unix timestamps in milliseconds — typically 13 digits. This difference can affect JSON parsers or time converters, so be sure to adjust your logic accordingly when handling timestamps.

How do I get the authorization code to use the Clover REST API in my website or payment system?

To obtain an authorization code, redirect the merchant to the Clover authorize endpoint /oauth/v2/authorize with your client_id and redirect_uri. Once the merchant logs in and approves your app, Clover redirects back to your URI with a code parameter that you can then exchange for an API token.

For details, see the Clover OAuth flow overview.

How do I integrate Clover REST API with my ASP.NET Core app using a global developer account?

To integrate the Clover REST API with an ASP.NET Core app using a Global Developer Account, follow the v2/OAuth flow to obtain expiring tokens:

• Authorize: Redirect the merchant to /oauth/v2/authorize?client_id={APP_ID}&redirect_uri={REDIRECT_URI}&response_type=code
• Exchange: Receive the code at your redirect URI and perform a server-side POST to /oauth/v2/token with your client_id, client_secret, and code.
• Access: Use the access_token in the Authorization: Bearer header for REST API calls.

For details, see Authenticate with the v2/OAuth flow.

Common errors

Why is my first token request failing in the new OAuth 2.0 flow?

If you see a 401 Unauthorized that is Failed to validate authentication code, check these verified points:

• Correct endpoint: Ensure you are using https://www.clover.com/oauth/v2/token for production. Use https://sandbox.dev.clover.com/oauth/v2/token for sandbox.
• Request format: Parameters (client_id, client_secret, code) must be sent in the POST body (JSON or x-www-form-urlencoded), not as URL query parameters.
• Flow consistency: The code must be obtained from the v2 authorize endpoint /oauth/v2/authorize.
• Installation: The app must be currently installed on the merchant's account. If they uninstalled it, the code is immediately invalidated.
• Token management: OAuth access_tokens expire in 30 minutes. You must use the provided refresh_token to generate new access tokens.

Why am I getting a 415 Unsupported Media Type error when requesting an access and refresh token from Clover OAuth 2.0 endpoint?

The 415 Unsupported Media Type error means the Content-Type header in your request is incorrect. Clover OAuth 2.0 token endpoint expects the request body to be in JSON format. Update your request headers in Postman or your code to include: Content-Type: application/json.

Why am I getting a 429 Too Many Requests error after migrating to expiring OAuth tokens in Clover?

The _429 Too Many Request_s error indicates that your app is exceeding the Clover API rate limits. The limits apply per merchant, per app, and per endpoint. This issue often arises after migrating to short-lived OAuth tokens due to changes in how requests are authenticated and tracked.Clover enforces rate limits to protect system stability.

You can request a higher rate limit by contacting Clover Developer Relations: Email your request to: [email protected]. Include details such as your app ID, merchant volume, and use case.

Why isn’t my webhook triggering when I create, update, or delete inventory items?

This is typically caused by missing permissions or an out-of-sync installation.

• Reinstall required: If you added Read Inventory permissions after the merchant installed your app, the webhook will not initiate. The merchant must uninstall and reinstall the app to authorize the new permissions.
• Verify subscriptions: Check your Developer Dashboard under App Settings > Webhooks. Ensure you are subscribed to the Inventory category and that your Verification URL is marked as Verified.
• Endpoint requirements: Your server must respond with an HTTP 200 OK within several seconds, or Clover may stop sending notifications to your endpoint.

Why am I getting the error Site URL not configured for developer app when trying to generate an API token using Clover OAuth?

This error occurs when your app is missing the Site URL required for OAuth token generation. Common causes and fixes:

• Verify App Type: If the REST Configuration section is missing from your Developer Dashboard, your app is not configured as a REST Client. You must enable this in the App Settings to reveal the Site URL field.
• URL matching: The redirect_uri you send in your OAuth request must exactly match the Site URL (or one of the authorized redirect URLs) saved in the Developer Dashboard.
• Avoid Webhook confusion: The Site URL is used for the OAuth handshake; the Webhook URL is strictly for receiving event notifications. They serve different purposes and are not interchangeable.