=== CatCode Payments with Viva.com for WooCommerce ===
Contributors: catcodestudio
Tags: viva, smart checkout, payment gateway, apple pay, greece
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

Viva.com Smart Checkout that does not lose paid orders: payments confirmed by the Viva API, verified webhooks, a 15-minute check, block checkout.

== Description ==

A WooCommerce payment gateway for **Viva.com Smart Checkout** built around one rule: when the buyer has paid, the order must say so — even if the buyer closed the browser, even if a webhook never arrived.

The buyer pays on the Viva Smart Checkout page with any method active in your Viva account: Visa, Mastercard and other cards, Apple Pay, Google Pay, PayPal, Klarna, IRIS, BLIK, Przelewy24, iDEAL, EPS, MB WAY and more.

**How a payment reaches the order**

* **On the buyer's return.** Viva sends the buyer back with a transaction ID; the plugin asks the Viva API for that transaction (Retrieve Transaction) and marks the order paid right there — it does not wait for a webhook.
* **By webhook, verified.** Transaction Payment Created, Transaction Failed, Transaction Reversal Created and Order Updated are handled, and each one is only a hint: the transaction is fetched from the Viva API before anything changes. The webhook URL answers Viva's verification with your webhook key automatically.
* **By a background check every 15 minutes.** Unpaid Viva orders of the last three days are checked with Retrieve Order; a paid payment order is applied even when the buyer never came back and no webhook arrived.
* **Before WooCommerce cancels an unpaid order.** When the "Hold stock" time runs out, WooCommerce cancels pending orders. For a Viva order the plugin asks Viva first: a paid order is settled instead of cancelled, and an order whose buyer is still on the payment page waits.

**Checks before an order is marked paid**

* The transaction must belong to a payment order this order created (each attempt gets its own Viva payment order; a late payment of an older attempt is still matched).
* The amount and the currency must match what was asked and the current order total — otherwise the order goes On hold with a note instead of being shipped.
* A database lock and a fresh read of the order make sure the return, the webhook and the background check never apply one payment twice.

**More**

* Unpaid orders are cancelled when their Viva payment order expires or the buyer presses Cancel (can be switched off), so orders do not hang in "Pending payment".
* Payment page in the buyer's language — WPML and Polylang aware — and the buyer comes back to the thank-you page in that language.
* Name, e-mail, phone and country are sent to Smart Checkout, so the buyer is not asked again and sees the local methods of the country.
* "Create a payment source for this shop" button, a "Check the keys" button and a webhook URL self-test.
* "Check with Viva" button on the order screen and a bulk action in the orders list.
* Classic and block checkout, the order-pay page, HPOS.
* Demo and live environments, brand colour, preselected method, statement descriptor, payment time limit.
* EUR, GBP, RON, PLN, CZK, HUF, SEK and DKK; the method hides itself for other currencies.
* The Client Secret and the API Key are stored encrypted.


Viva.com is a trademark of its owner; this plugin is made by CatCode and is not the official Viva.com plugin.

== Installation ==

1. Upload the plugin and activate it.
2. WooCommerce → Settings → Payments → **Viva.com Smart Checkout (CatCode)**.
3. Choose the environment (demo or live) and paste, from the Viva banking app → Settings → API Access of that environment: the Smart Checkout Client ID and Client Secret, the Merchant ID and the API Key.
4. Press "Create a payment source for this shop" (or create it by hand with the Success and Failure URLs shown on the settings screen) and save.
5. In Settings → API Access → Webhooks of the Viva banking app, add the webhook URL shown on the settings screen, press Verify and save it for Transaction Payment Created, Transaction Failed, Transaction Reversal Created and Order Updated.
6. Press "Check the keys", make a test payment in the demo environment, then switch to live.

== Frequently Asked Questions ==

= Do I need a Viva.com account? =
Yes. A free demo account (demo.vivapayments.com) is enough to test; live payments need a live account.

= Why two sets of keys? =
The Smart Checkout Client ID and Secret create payment orders and read transactions (OAuth2). The Merchant ID and API Key are needed for the webhook key, the payment-order checks, the payment source and refunds (Basic Auth). Both are in Settings → API Access.

= Does it work without webhooks? =
Yes. Payments are confirmed on the buyer's return and by the 15-minute check. Webhooks make the update instant, also for payment methods that confirm later.

= I used another Viva plugin before. =
Each plugin needs its own payment source (the Success and Failure URLs point to it) and webhook URL. Keep the old plugin until its open orders are settled, but disable it as a payment method.

= Why is an order "On hold"? =
Either the payment is authorised and waits for capture, a payment method has not given its final answer yet, or the amount paid does not match the order — the order note says which.

= Which currencies? =
EUR, GBP, RON, PLN, CZK, HUF, SEK and DKK. Payments in a currency other than your Viva account's own need Viva's multicurrency to be enabled for the account.

== External services ==

The plugin connects to the Viva.com payment platform, which processes the payment:

* `accounts.vivapayments.com` / `demo-accounts.vivapayments.com` — an access token is requested with your Smart Checkout Client ID and Secret.
* `api.vivapayments.com` / `demo-api.vivapayments.com` — when an order is paid, a payment order is created with the amount, currency, order number, a short description of the items and the buyer's name, e-mail, phone, country and language; transactions are read to confirm payments.
* `www.vivapayments.com` / `demo.vivapayments.com` — the buyer is sent to the Smart Checkout page; the plugin reads payment orders and their transactions, gets the webhook key, creates a payment source when you press the button, and sends refunds and captures you make.

Viva.com terms: https://www.viva.com/en-eu/terms-portal — privacy notice: https://www.viva.com/en-eu/privacy-notice

== Changelog ==

= 1.0.0 =
* First release: Viva.com Smart Checkout with payments confirmed through the Viva API on return, verified webhooks, a 15-minute background check and a guard before the stock-hold cancel; amount, currency and payment-order checks; payment lock; cancellation of unpaid orders; payment page and thank-you page in the buyer's language; payment source creation, key check and webhook self-test; "Check with Viva" on the order screen; block checkout; HPOS.
