Common Clover OAuth Errors in WooCommerce — Debugging Guide

Clover uses standard OAuth 2.0 for merchant authorization, which means the error messages you see are the same generic OAuth messages you'd see connecting to any service. They're also cryptic. This guide translates the eight most common ones into 'here's what's actually wrong and how to fix it' — in the order we encounter them on support tickets.

1. 'redirect_uri mismatch'

The most common OAuth error, by far. Clover sent you back to a redirect URL, but the URL your plugin is listening on doesn't match what's registered in your Clover Developer app.

Fix: in the Clover Developer Dashboard, open your app → Settings → OAuth. Paste the redirect URI from your plugin settings page exactly — including trailing slash, https vs http, and subdomain (www vs bare). Save. Retry the OAuth connect flow.

2. 'invalid_client' or 'invalid client credentials'

Your App ID or App Secret in the plugin settings doesn't match the values in your Clover Developer app.

Fix: re-copy both values from the Developer Dashboard's app overview. Paste them into the plugin settings. Watch for trailing whitespace — that's the #1 subtle cause.

3. 'Invalid PAKMS key'

PAKMS (Payment App Key Management System) is a separate key from your App ID/Secret, specifically for the payment gateway. It lives under Ecommerce → API Tokens in the Developer Dashboard.

Fix: confirm you copied from the right place. PAKMS keys are environment-specific: sandbox PAKMS keys don't work in production and vice versa. If you switched environments, generate a fresh PAKMS key for the active one.

4. 'Merchant not found' or 'unauthorized merchant'

The Clover user who completed OAuth doesn't have access to the merchant account they tried to connect, or the app isn't approved for that merchant's region.

Fix: sign in to Clover as an admin user for the target merchant. Confirm the Developer app is enabled for the merchant's region (NA, EU, LATAM). Retry OAuth.

5. 'scope not permitted'

Your app is requesting permissions (scopes) that aren't granted. Clover apps declare required scopes in the Developer Dashboard — if the plugin updates and asks for more scopes than your app has registered, OAuth fails.

Fix: in your Developer app's permissions, enable the scopes the plugin documents as required. For CloverWoo these are read/write for inventory, orders, customers, payments, and webhooks.

6. 'HTTPS required'

Clover only completes OAuth to HTTPS callback URLs. If your WordPress site is running over HTTP (or has a mixed-content setup) the callback fails.

Fix: install a valid TLS certificate on your domain. Update WordPress Site Address settings to https://. Force HTTPS site-wide. Update the redirect URI in the Clover app to the https:// version. Retry.

7. 'state parameter invalid'

OAuth state parameters are one-time tokens to prevent CSRF. If your server discarded the state between starting and completing OAuth (because of a session reset, server restart, or proxy caching), completion fails.

Fix: ensure your session storage is reliable (not ephemeral). If you're behind an aggressive caching proxy, exempt the OAuth callback URL from caching. Restart the OAuth flow from the plugin's Connect button.

8. 'Clover region mismatch'

Clover operates separate environments (NA, EU, LATAM, Sandbox). OAuth must happen against the region where the merchant lives. Starting OAuth against the wrong region silently fails or returns an empty merchant list.

Fix: in plugin settings, select the correct environment before clicking Connect. For testing, use Sandbox and a Sandbox merchant. For production, match the merchant's actual region.

OAuth setup checklist (5 minutes)

1. In Clover Developer Dashboard, create an app (or open existing).
2. Copy App ID, App Secret, and PAKMS key.
3. In the app's Settings → OAuth, paste the redirect URI from your plugin.
4. Ensure the required permission scopes are enabled.
5. In the plugin settings, select the correct environment (NA / EU / LATAM / Sandbox).
6. Paste App ID, App Secret, and PAKMS key. Save.
7. Click 'Connect to Clover'. Authorize on Clover's page. Confirm 'Connected' status on return.