=== CatCode Clover Payments for WooCommerce ===
Contributors: catcodestudio
Tags: clover, payment gateway, credit card, woocommerce payments, refunds
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Card payments with your Clover account: Clover's secure card fields in your checkout, classic and block checkout, retries that never charge twice.

== Description ==

A WooCommerce payment gateway for **Clover** merchants in the United States and Canada, built around one rule: a lost connection or a double click must never mean a double charge, and a card problem must never look like a broken shop.

* **Clover's card fields inside your checkout** — the card number, expiry date, CVV and ZIP code are typed into iframes served by Clover. In the browser Clover turns them into a single-use token, and the shop only ever receives that token. Card data does not touch your server.
* **Classic and block checkout**, the order-pay page, HPOS.
* **Retries that never charge twice** — every attempt has a stable idempotency key made from the order, the card token and the amount. A double click or a repeated request is one charge for Clover. The attempt is written to the order before the request leaves, so a request that died half way is known to the next one.
* **An honest answer when the connection breaks** — if Clover's answer is lost, the buyer is told so, the order is not marked paid or failed, and pressing the button again repeats the same request instead of creating a new charge.
* **"Re-check the Clover payment"** in the order actions — looks for the order among the latest Clover charges and settles it. It only reads, it never charges.
* **Refunds from the order screen** — full or partial, counted, so Clover is never asked for more than the payment still holds. The plugin keeps tax out of the charge request on purpose: Clover does not allow partial refunds of charges that carry a tax amount.
* **Plain messages for buyers** — "Your bank declined this card" instead of a raw gateway error. The technical reason goes to the order notes and the log.
* **Card-testing brake** — after a number of declined attempts from one address or on one order, new attempts wait for 15 minutes, so bots testing stolen cards do not cost you fees and fraud points.
* **Keys that explain themselves** — "Check connection" tells apart a wrong key, a sandbox key in live mode and a live key in sandbox mode, and refuses a private key pasted into the public field, where it would reach every buyer's browser.
* The amount Clover took is compared with the order total: a mismatch puts the order on hold with a note instead of shipping it.
* Street address field for accounts with address verification rules, optional Clover receipt, "Processing" or "Completed" after payment, debug log without keys or tokens.
* The private key is stored encrypted.
// @pro-begin
* Translation included: Canadian French.
// @pro-end

// @pro-begin
= Pro =

The Pro version is sold on [catcode.com.ua](https://catcode.com.ua/modules/catcode-clover-payments-for-woocommerce/), with a 7-day trial that never starts by itself:

* **Apple Pay and Google Pay** buttons in the card form, and the Apple Pay domain file served by the plugin.
* **Authorize and capture** — hold the money at checkout, capture from the order actions or when the order moves to Processing or Completed; cancelling the order voids the hold.
* **Clover Hosted Checkout** — send buyers to a payment page on clover.com. Every webhook is checked against its signature, and then the payment itself is read back from the Clover API: only that answer marks the order paid.
* **Payment watchdog** — every 15 minutes settles the orders of the last 48 hours whose payment result was lost, and tells you when a Hosted Checkout buyer came back but no webhook arrived.
* **Payment journal** — every Clover payment with charge, card, amount, capture state, refunds, sandbox or live.

The licence runs for 1-5 years and includes updates and support for that term. One key covers two sites: your shop and a test copy.
// @pro-end

Clover is a trademark of its owner. This plugin is an independent integration made by CatCode; it is not the official Clover plugin and is not affiliated with or endorsed by Clover or Fiserv.

== Installation ==

1. Upload the plugin and activate it.
2. In the Clover Merchant Dashboard open Settings → View all settings → Ecommerce → Ecommerce API Tokens and create a token of the type "Hosted iFrame + API/SDK". Copy the public and the private key. For tests, use a test merchant from the Clover Global Developer Dashboard.
3. WooCommerce → Settings → Payments → **Clover (CatCode)**: choose Live or Sandbox, paste the merchant ID and both keys, and press "Check connection".
4. Enable the method and make a test payment.

== Frequently Asked Questions ==

= Do I need a Clover account? =
Yes: a Clover merchant account with online payments enabled, in a region where Clover Ecommerce works (the United States and Canada). For tests, a free developer account comes with a test merchant.

= Does card data touch my server? =
No. The fields are Clover's iframes and the plugin receives a single-use token. Your server and your database never see a card number.

= How do I test? =
Set the environment to Sandbox, use the keys of a test merchant and pay with a Clover test card, for example 4242 4242 4242 4242 with any future date and any three-digit CVV. 4005 5717 0222 2222 is declined. Both are listed in the Clover documentation under Test card numbers.

= I used the official Clover plugin before. =
Deactivate it before enabling this one, so the checkout does not show two card forms. Refund orders paid through the old plugin from the old plugin or from the Clover dashboard.

= The card fields do not appear. =
The fields come from checkout.clover.com. Exclude Clover's script from minifying and delaying plugins, and if your site sends a strict Content-Security-Policy, allow https://*.clover.com for scripts, frames and connections. Content blockers in the buyer's browser can block it too: the form says so.

= Every card is refused with an address error. =
Your Clover account has address verification rules. Turn on "Street address field" in the plugin settings.

= Does it do 3D Secure? =
Not in this version: Clover's 3D Secure is a separate paid service for merchants, and the plugin does not start it.

= Why is the method missing at checkout? =
The keys are incomplete, or the shop currency has no cents (for example JPY). Clover accepts currencies other than USD and CAD only for Visa and Mastercard, on accounts with Multi Currency Pricing.

== External services ==

This plugin connects to Clover, the payment service the shop owner chooses:

* Clover card fields (checkout.clover.com/sdk.js, in sandbox mode checkout.sandbox.dev.clover.com/sdk.js) — loaded on the checkout and order-pay pages. The buyer types the card details into Clover's iframes and they go straight to Clover; the shop's public key and merchant ID are passed to the script. Clover may show reCAPTCHA in the form.
* Clover Ecommerce API (scl.clover.com, in sandbox mode scl-sandbox.dev.clover.com) — when a buyer pays: the single-use card token, order total and currency, a description with the order number and the shop name, the order number as a reference, the order ID, the WordPress, WooCommerce and plugin versions, the buyer's IP address (Clover uses it for fraud checks), and the buyer's e-mail address when the Clover receipt is on. On a refund: the charge, amount and order number. "Re-check" reads the list of recent charges.
* Clover platform API (api.clover.com, in sandbox mode apisandbox.dev.clover.com) — on "Check connection" and when saving new keys: reads the merchant's name and online payment settings.
// @pro-begin
* Clover Hosted Checkout (api.clover.com) — when the Hosted Checkout page is on: order number and total, the buyer's name, e-mail and phone. Clover then posts payment webhooks to this site, and the plugin reads each reported payment from the Clover API.
* Google Pay and Apple Pay, when you turn them on: the buttons are served by Clover. Google Pay API terms: https://payments.developers.google.com/terms/sellertos — Apple Pay terms: https://www.apple.com/legal/applepayments/direct-payments
* CatCode licence server (catcode.com.ua) — when the owner activates a key or starts the trial, and periodically while a key is stored: the key and the site address (plus the e-mail typed for a trial). Updates are checked there with the same key.
// @pro-end

Clover terms: https://www.clover.com/terms — Clover privacy policy: https://www.clover.com/privacy-policy

== Changelog ==

= 1.0.0 =
* First release: Clover card fields in the classic and block checkout and on the order-pay page, charges with stable idempotency keys, safe repeat after a lost answer, Re-check order action, full and partial refunds, plain decline messages, card-testing brake, amount check, connection check that names wrong and swapped keys, HPOS.
// @pro-begin
* Pro: Apple Pay and Google Pay, authorize and capture, Clover Hosted Checkout with signed webhooks checked against the API, payment watchdog, payment journal, updates from catcode.com.ua.
// @pro-end
