--- title: Integration Architecture Guide audience: public summary: What a WeeConnectPay access token represents, how Clover merchant/app/employee entities relate, and how to design integrations that survive real-world disruptions. --- # WeeConnectPay API - Integration Architecture Guide This guide explains what your access token represents, how Clover entities relate to each other, and how to design integrations that handle real-world disruptions gracefully. It is the conceptual companion to the [OAuth Integration Guide](OAUTH_INTEGRATION_GUIDE.md), which covers authentication mechanics. > **Audience:** Third-party developers building payment modules (PrestaShop, WooCommerce, custom platforms) that process Clover payments through the WeeConnectPay API. ## Environments | Environment | API Base URL | |-------------|--------------| | **Sandbox** | `https://apidev.weeconnectpay.com` | | **Staging** | `https://apidev.weeconnectpay.com` | | **Production** | `https://api.weeconnectpay.com` | > **Sandbox vs Staging:** The sandbox environment is for merchants and integrators who want to test the integration — access is granted by employee invite to a pre-configured sandbox merchant. The staging environment is for developers actively building integrations and offers a stable environment unaffected by other testers. Both share the same API base URL. For day-to-day development, use **staging**; for demonstrating or evaluating the product, use **sandbox**. > > See the [OAuth Integration Guide](OAUTH_INTEGRATION_GUIDE.md) for credential setup per environment. --- ## What Your Access Token Represents When you authenticate with the WeeConnectPay API, you receive a **WeeConnectPay-issued JWT** — not a Clover token. WeeConnectPay holds Clover API credentials internally and acts on your behalf when you make API calls. Your token maps to a specific combination of: - **Clover Merchant** — the business accepting payments - **Clover Employee** — the person who authorized the connection - **Clover App** — WeeConnectPay's registered application on Clover - **Integration** — your specific connection to that merchant ``` ┌─────────────────┐ ┌─────────────────┐ │ │ Bearer token │ │ │ Your │ (WeeConnectPay JWT) │ WeeConnectPay │ │ Integration │ ───────────────────────────> │ API │ │ │ │ │ │ │ │ Resolves your │ │ │ │ context: │ │ │ │ - Merchant │ │ │ │ - Employee │ │ │ │ - App │ │ │ │ - PAKMS Key │ │ │ │ │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ┌───────────┐ │ │ │ │ │ Clover │ │ │ │ API response │ │ API │ │ │ │ <─────────────────────────── │ └───────────┘ │ └─────────────────┘ └─────────────────┘ ``` You never interact with Clover directly. WeeConnectPay resolves your token into the correct Clover credentials, makes the API call to Clover, and returns the result. ### Introspecting Your Token Use `GET /v1/get-caller-identity` to see what your token resolves to: ```bash curl -X GET https://apidev.weeconnectpay.com/v1/get-caller-identity \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` **Response:** ```json { "merchant": { "uuid": "SK36FZYP2ZKJ1", "name": "Demo Coffee Shop" }, "employee": { "uuid": "H5RAY3B32QGBW", "name": "John Doe" }, "app": { "uuid": "ZAVE6HARYPJ6P", "name": "WeeConnectPay" }, "public_access_key": { "key": "4484b370a284b6b7de7f3b2626e61524" }, "integration": { "uuid": "761280e0-2307-4789-a1cd-d7ad12aab0ff" } } ``` If this endpoint returns `401`, your token is no longer valid. See [How Clover Connections Can Break](#how-clover-connections-can-break) for diagnosis steps. --- ## The Clover Entity Model Understanding how Clover entities nest helps you diagnose issues when things break. | Entity | What It Is | Example | |--------|-----------|---------| | **Merchant** | A business registered on Clover. The top-level container. | "Demo Coffee Shop" | | **Employee** | A person within the merchant's organization. The employee who authorized the Clover connection. | "John Doe" (owner) | | **App** | A third-party application registered with Clover. WeeConnectPay is the app. | "WeeConnectPay" | | **Integration** | Your specific connection to a merchant, created when the merchant generates OAuth credentials in the WeeConnectPay dashboard. | Your PrestaShop module's connection | | **PAKMS Key** | A public key used to initialize the Clover SDK on the frontend for card tokenization. Scoped to the merchant + app pair. | `4484b370a284...` | ``` Merchant (Demo Coffee Shop) ├── Employee (John Doe — owner, authorized the connection) ├── Employee (Jane Smith — manager) │ ├── App (WeeConnectPay) │ ├── PAKMS Key (for card tokenization) │ │ │ ├── Integration A (your PrestaShop module) │ └── Integration B (your WooCommerce plugin) │ └── App (Some Other App) ``` Key insight: **one merchant can have multiple integrations** through the same WeeConnectPay app. Each integration gets its own OAuth client credentials, but they share the same underlying Clover merchant, employee, and PAKMS key. --- ## How Clover Connections Can Break This is the most important section for building resilient integrations. Clover connections can break for reasons entirely outside your control — a merchant uninstalls an app, an employee is removed, or an account is closed. | Scenario | Cause | What You See | Recovery | |----------|-------|-------------|----------| | App uninstalled | Merchant removes WeeConnectPay from their Clover dashboard | `401 Unauthenticated` on all API calls | Merchant must reinstall WeeConnectPay on Clover and generate new credentials | | Employee removed | The authorizing employee is deactivated or deleted on Clover | `401 Unauthenticated` on all API calls | Merchant must re-authorize with an active employee | | Merchant account closed | Clover account shut down entirely | `401 Unauthenticated` on all API calls | No recovery — the merchant no longer exists on Clover | | OAuth client deleted | Merchant deletes their API credentials in the WeeConnectPay dashboard | `invalid_client` when requesting a new token | Merchant must generate new credentials in the dashboard | | Token expired naturally | Reached the 1-year TTL | `401 Unauthenticated` on API calls | Re-authenticate using the same `client_id` and `client_secret` | > **Important:** Your integration **cannot** distinguish between a naturally expired token and a Clover-side disconnection — both return `401 Unauthenticated`. The only way to tell the difference is to attempt re-authentication: if requesting a new token with valid credentials succeeds, it was a simple expiry. If it also fails, the Clover connection is broken and the merchant must take action. --- ## Token Lifecycle Every access token follows a predictable lifecycle: ``` ┌──────────────────────┐ │ │ Authenticate │ Created │ with client │ (token issued) │ credentials │ │ │ └──────────┬───────────┘ │ │ ▼ ▼ ┌──────────────────────┐ │ │ │ Active │ ◄── Normal operation │ (up to 1 year) │ (API calls succeed) │ │ └──────────┬───────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ Expired │ │ Revoked │ │ Irrecoverable │ │ (TTL reached) │ │ (client │ │ (Clover-side │ │ │ │ deleted) │ │ disconnection) │ └─────────────────┘ └─────────────┘ └──────────────────┘ Re-auth with same Generate new Merchant must credentials credentials act on Clover ``` | State | Cause | Error Response | Recovery Action | |-------|-------|---------------|-----------------| | **Active** | Token is within its 1-year TTL | N/A — calls succeed | None needed | | **Expired** | Token has exceeded its 1-year TTL | `{"message": "Unauthenticated."}` | Request a new token with the same `client_id` / `client_secret` | | **Revoked** | Merchant deleted the OAuth client in the WeeConnectPay dashboard | `{"error": "invalid_client"}` on token request | Merchant generates new credentials | | **Irrecoverable** | Clover-side disconnection (app uninstalled, employee removed, account closed) | `{"message": "Unauthenticated."}` and re-auth also fails | Merchant must fix the issue on the Clover side | --- ## Design Recommendations ### 1. Handle 401 Gracefully Never let a `401` response crash your checkout flow or leave a customer with a blank page. Show a clear, merchant-facing message that guides them to resolve the issue. ``` ┌──────────────────────────────────────────────────────────────┐ │ ⚠ Payment Connection Issue │ │ │ │ The connection to the payment processor is currently │ │ unavailable. This usually means the merchant needs to │ │ reconnect their Clover account. │ │ │ │ Merchant: Log in to your WeeConnectPay dashboard to │ │ check your connection status and re-generate credentials │ │ if needed. │ └──────────────────────────────────────────────────────────────┘ ``` ### 2. Cache Tokens, Handle Invalidation Tokens are valid for 1 year — don't request a new one on every API call. Cache the token server-side and only refresh when you receive a `401`. ``` Token Request Strategy: 1. Check for cached token ├── Found → Use it └── Not found → Request new token → Cache it 2. Make API call with cached token ├── Success → Done └── 401 → Clear cache → Request new token → Retry once ├── Retry succeeds → Cache new token → Done └── Retry fails → Token is irrecoverable → Alert merchant ``` ### 3. Implement Retry-Then-Alert When a call fails with `401`, retry exactly once with a fresh token. If the retry also fails, stop retrying and alert the merchant. Endless retry loops waste resources and mask real problems. ```javascript async function callApiWithRetry(endpoint, data, retried = false) { try { return await callApi(endpoint, data); } catch (error) { if (error.status === 401 && !retried) { clearCachedToken(); const newToken = await requestNewToken(); cacheToken(newToken); return callApiWithRetry(endpoint, data, true); } if (error.status === 401 && retried) { // Both attempts failed — Clover connection is likely broken alertMerchant('Payment connection lost. Please reconnect in WeeConnectPay dashboard.'); } throw error; } } ``` ### 4. Store the Clover Charge ID Always persist the `clover_charge_id` from charge responses in your order records. This is the primary key for reconciliation between your system, WeeConnectPay, and Clover. Without it, you cannot: - Match a payment to a refund - Look up a transaction in the Clover merchant dashboard - Resolve disputes with the payment processor ### 5. Use `external_reference_id` for Traceability Pass your platform's order or invoice number in the `external_reference_id` field when creating charges. This value appears in Clover settlement reports and makes it easy for merchants to match payments to orders. ```json { "external_reference_id": "PS-12345", "description": "PrestaShop Order #12345" } ``` > **Note:** The `external_reference_id` is truncated at 12 characters. Keep your identifiers short — use a prefix + numeric ID (e.g., `PS-12345`, `WC-67890`). ### 6. Health Check with `get-caller-identity` Use `GET /v1/get-caller-identity` as a lightweight health check. If it returns `200`, your token is valid and the Clover connection is intact. This is useful for: - **Configuration pages** — verify credentials are working when a merchant enters them - **Scheduled health checks** — detect broken connections before a customer tries to pay - **Debugging** — confirm which merchant, employee, and integration your token resolves to ### 7. Respect Rate Limits The WeeConnectPay API enforces **60 requests per minute** per token. When you receive a `429 Too Many Requests` response, back off using exponential delays: | Attempt | Wait Time | |---------|-----------| | 1st retry | 1 second | | 2nd retry | 2 seconds | | 3rd retry | 4 seconds | | 4th retry | 8 seconds | | Give up | Alert merchant or queue for later | Do not retry charge requests that return `429` without careful consideration — you risk double-charging a customer. Instead, check whether the original charge succeeded before retrying. ### 8. Diagnosing a 401 When you receive a `401`, use this decision tree to determine the cause: ``` Received 401 Unauthenticated │ ├── Attempt to request a new token with client_id + client_secret │ │ │ ├── Success (new token received) │ │ └── Original token had expired naturally │ │ → Cache the new token and retry the API call │ │ │ ├── Failure: "invalid_client" │ │ └── OAuth client was deleted in the WeeConnectPay dashboard │ │ → Merchant must generate new credentials │ │ │ └── Failure: other error / network issue │ └── Possible transient issue │ → Retry after a brief delay, then alert merchant │ └── New token received but API calls still return 401 └── Clover-side disconnection (app uninstalled, employee removed, etc.) → Merchant must check their Clover dashboard ``` --- ## Glossary | Term | Definition | |------|-----------| | **PAKMS Key** | Public Access Key Management Service key. A public key scoped to a merchant + app pair, used to initialize the Clover SDK on the frontend for secure card tokenization. Retrieved via `GET /v1/get-caller-identity`. | | **Tokenized Card** | An opaque token (e.g., `clv_1ABCDefGHI23jKL4m`) returned by the Clover SDK's `createToken()` method. Represents a customer's card without exposing the actual card number. Single-use. | | **Integration** | A connection between your platform and a specific Clover merchant through WeeConnectPay. Each integration has its own OAuth client credentials (`client_id` + `client_secret`). | | **Client Credentials** | An OAuth2 `client_id` and `client_secret` pair generated by a merchant in the WeeConnectPay dashboard. Used to authenticate your server with the WeeConnectPay API. | | **External Reference ID** | A merchant-defined identifier (max 12 characters) passed with charge requests. Appears in Clover settlement reports for reconciliation. | --- ## Support If you encounter issues with your integration: 1. Use `GET /v1/get-caller-identity` to verify your token is valid and check which merchant it resolves to 2. Review the [401 diagnosis decision tree](#8-diagnosing-a-401) to determine the root cause 3. Verify your `client_id` and `client_secret` are correct for the target environment (staging vs. production) 4. See the [OAuth Integration Guide](OAUTH_INTEGRATION_GUIDE.md) for authentication mechanics and code examples 5. See the [PrestaShop Integration Guide](PRESTASHOP_INTEGRATION_GUIDE.md) for a complete PrestaShop integration example 6. See the [Zoho Catalyst Integration Guide](ZOHO_CATALYST_INTEGRATION_GUIDE.md) for a complete Zoho integration example 7. For additional support, contact the WeeConnectPay team