=== VPOS.am Gateway ===
Contributors: gulian-digital
Tags: woocommerce, payment gateway, armenia, amd, hpos
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

WooCommerce payments in Armenia via VPOS.am hosted checkout: AMD online payments with signed webhooks, Checkout Blocks, HPOS and reconciliation.

== Description ==

VPOS.am Gateway is a WooCommerce payment gateway for Armenian online payments. It connects a WordPress store to the VPOS.am payment runtime and keeps bank/acquirer credentials out of WordPress.

The plugin creates a VPOS.am payment session from WooCommerce checkout, redirects the buyer to hosted checkout, receives signed payment status webhooks and reconciles missed callbacks through the VPOS.am payments API. Browser return URLs are treated only as navigation; WooCommerce order status changes only after a signed final status and amount/currency verification.

VPOS.am is designed for merchants who want one integration layer for enabled Armenian payment providers instead of maintaining a separate WooCommerce plugin for each bank or wallet route.

Key capabilities:

* Classic WooCommerce checkout gateway.
* WooCommerce Checkout Blocks payment method registration.
* WooCommerce HPOS compatibility declaration.
* Provider-aware checkout title for the selected VPOS.am route.
* Checkout language setting for Armenian, Russian and English where the VPOS/provider route supports it.
* Light/dark VPOS.am checkout icon for classic checkout and Checkout Blocks.
* Currency and provider-route guard that hides the gateway when the current order is not supported.
* Read-only `/v1/capabilities` diagnostics that can further gate checkout and PayLinks when VPOS marks a route not ready.
* Signed `payment.status_changed` webhook receiver.
* Amount and currency guard before order status updates.
* Pending payment reconciliation through WP-Cron.
* Manual WooCommerce order action to refresh VPOS payment status from the server-side VPOS API with amount/currency verification.
* WooCommerce order-screen payment audit panel with payment id, provider route, status source and last status update.
* Read-only WooCommerce order operation history and admin-only audit JSON export with compact VPOS references for support disputes.
* Packaged `docs/support-playbook.md` with webhook, HPOS, PayLinks/QR, cron/reconciliation and common-error support snippets.
* Admin order action to create an idempotent VPOS.am payment link without changing order status.
* Standalone WooCommerce admin PayLinks page for VPOS.am payment links outside checkout.
* Local QR preview for VPOS.am payment URLs as a presentation layer, not a payment status.
* Shortcode and dynamic block for embedding an existing VPOS.am payment link.
* Fiscal status and receipt metadata display when VPOS.am returns receipt id, number, URL or PDF fields.
* Admin action to refresh VPOS fiscal status without changing WooCommerce payment/order status.
* Optional guarded fiscal retry requests from WooCommerce order actions. Receipt issuing remains in VPOS.am.
* Optional guarded refund requests from WooCommerce admin. Refunds complete only when VPOS.am returns a succeeded refund operation.
* Optional guarded capture/void requests from WooCommerce order actions for authorized VPOS payments. Payment proof still requires webhook or reconciliation.
* Admin-only VPOS Contracts page for guarded tokenization intent and subscription contract requests without collecting card data.
* Admin diagnostics with copy buttons for API URL, provider route and webhook callback URL.
* Test/live status indicator and quick setup checklist for safer merchant onboarding.
* Sandbox-ready setup by using VPOS.am test API URL and test merchant credentials.
* Refund status handling when VPOS.am reports refunded or partially refunded payments.
* WooCommerce logs for gateway events without logging merchant tokens or webhook secrets.
* English source strings with Russian and Armenian translation files.

== Installation ==

1. Upload the `vpos-am-gateway` folder to `/wp-content/plugins/`, or install the ZIP through the WordPress plugin installer.
2. Activate `VPOS.am Gateway`.
3. Open WooCommerce payment settings and enable `VPOS.am`.
4. Set the VPOS API URL, merchant API token, provider route, allowed currencies and webhook signing secret.
5. Configure the VPOS merchant webhook URL as `https://merchant.example/?wc-api=vpos_am_gateway`.
6. Run a sandbox order and confirm the order is paid only after a signed final status from VPOS.am.

== Configuration checklist ==

Before going live:

* Use HTTPS on the production domain.
* Confirm the VPOS API URL, merchant token and provider route with VPOS.am support.
* Confirm the WooCommerce currency is enabled for the selected provider route.
* Configure the same webhook signing secret in WooCommerce and in the VPOS.am console.
* Confirm that WP-Cron or a real server cron can run reconciliation.
* Test successful, failed and cancelled payment flows.
* Verify that amount/currency mismatches do not mark orders as paid.
* Keep guarded fiscal retry requests disabled until VPOS.am confirms the provider fiscal/eHDM contract and sandbox tests.
* Keep guarded refund requests disabled until VPOS.am confirms the provider refund contract and sandbox tests.
* Keep guarded capture/void requests disabled until VPOS.am confirms provider authorization, capture and void contracts with sandbox tests.
* Keep guarded tokenization and subscription requests disabled until VPOS.am confirms provider token lifecycle, consent, 3DS and renewal tests.
* Keep bank/acquirer credentials in VPOS.am or the provider onboarding process, not in WordPress.
* Keep receipt issuing, tax mode and eHDM settings in VPOS.am console/API; WordPress only displays returned fiscal metadata.

== External Services ==

This plugin connects to VPOS.am only when a WooCommerce customer chooses the VPOS.am payment method, a store manager creates a VPOS.am payment link for an order, a store manager creates a standalone payment link from the VPOS PayLinks admin page, a store manager enables guarded fiscal retries and requests a fiscal retry order action, a store manager enables guarded refunds and requests a WooCommerce admin refund, a store manager enables guarded capture/void requests and requests a capture or void order action, a store manager enables guarded tokenization/subscription requests from the VPOS Contracts admin page, a signed VPOS.am webhook is received, or WP-Cron reconciles a pending VPOS.am order.

Data sent to VPOS.am may include order amount, currency, provider route, checkout language hint, WooCommerce order ID, order description, customer contact fields needed for payment processing, success/fail URLs and the merchant webhook URL. Card data is entered on the hosted VPOS/provider checkout page and is not collected by this plugin.

Service URL: `https://vpos.am`

Public API documentation: `https://api.vpos.am/docs`

Privacy and production access requirements are provided by VPOS.am during merchant onboarding.

== Frequently Asked Questions ==

= Does the plugin store bank or card credentials? =

No. The plugin stores only the VPOS merchant token, webhook secret and order payment metadata. Card handling remains inside the hosted VPOS/provider checkout flow.

= How does the plugin confirm payment? =

The plugin changes WooCommerce order status only after a signed VPOS status webhook or a reconciled VPOS API lookup. Store managers can also run a manual order-level refresh that uses the same server-side VPOS API lookup and amount/currency guard. The order-screen payment status panel is audit visibility only. Browser return URLs are not treated as payment confirmation.

= What should support collect for a dispute or failed payment? =

Use the order-screen `Export VPOS audit JSON` button, the WooCommerce diagnostics screenshot and WooCommerce logs for source `vpos-am-gateway`. The package also includes `docs/support-playbook.md` with webhook, HPOS, PayLinks/QR, cron/reconciliation and common-error snippets. Do not send merchant API tokens, webhook secrets, provider credentials or card data to support.

= Is WooCommerce Blocks checkout supported? =

Yes. The plugin registers a WooCommerce Blocks payment method script in addition to the classic gateway.

= Is WooCommerce HPOS supported? =

Yes. The plugin declares compatibility with WooCommerce High-Performance Order Storage.

= Does the plugin support multiple Armenian banks or wallets? =

The WooCommerce plugin sends the order to VPOS.am. The available provider route depends on the merchant's VPOS.am account and provider onboarding. This avoids storing separate bank/acquirer credentials inside WordPress.

= Does this plugin add payment links or QR payments inside WordPress? =

Yes. The order admin action can create a VPOS.am payment link for an existing WooCommerce order and stores the link ID/payment URL in order meta. WooCommerce also has a standalone VPOS PayLinks admin page, plus a shortcode and dynamic block for embedding an existing VPOS.am payment URL. QR is not a separate payment status: if a merchant renders the URL as QR, the order/payment must still wait for signed webhook or reconciliation.

= Does the plugin enable provider-specific payment features automatically? =

No. The diagnostics can read `/v1/capabilities` and cache whether the selected route is ready for checkout sessions, PayLinks and QR presentation. It does not enable refunds, capture, void, tokenization, subscriptions or fiscal issuing unless VPOS.am exposes and tests those backend contracts.

= Can WooCommerce admin issue VPOS.am refunds? =

Only as an opt-in guarded request. The setting is disabled by default. When enabled, WooCommerce sends an idempotent refund request to VPOS.am and records the returned operation metadata, but WooCommerce completes the refund only if VPOS.am returns a succeeded operation. Disabled, not-configured or pending provider responses do not change payment status.

= Can WooCommerce admin capture or void an authorized payment? =

Only as an opt-in guarded request. The setting is disabled by default. When enabled, WooCommerce sends an idempotent capture or void request to VPOS.am for a payment that is still authorized and records the returned operation metadata. The order is not marked paid or cancelled by this action; final payment status must still come from signed webhook or reconciliation.

= Does this plugin issue fiscal/eHDM receipts? =

No. WordPress displays fiscal status and receipt links returned by VPOS.am, and store managers can refresh that fiscal metadata from the VPOS payment status API. Receipt issuing, tax mode and eHDM provider settings remain in VPOS.am console/API until a backend fiscalization contract is enabled and tested.

= Can WooCommerce admin retry fiscal/eHDM receipt issuing? =

Only as an opt-in guarded request. The setting is disabled by default. When enabled, WooCommerce sends an idempotent fiscal retry request to VPOS.am and records the returned operation metadata, but WordPress does not issue receipts and does not change payment/order status.

= Does this plugin support saved cards or subscriptions? =

Not as live checkout features. The VPOS Contracts admin page can send opt-in guarded tokenization intent and subscription contract requests for backend testing, but WordPress never collects card data, does not create saved WooCommerce payment methods and does not create WooCommerce Subscriptions renewal schedules.

= What should be tested before production use? =

Use a clean WordPress/WooCommerce store, enable sandbox credentials, create an order, complete a successful payment, test a failed payment, refresh fiscal metadata when returned by VPOS.am, and verify that amount/currency mismatches do not mark an order as paid.

== Screenshots ==

1. VPOS.am payment settings, diagnostics, order payment audit panel and PayLinks admin workflow in WooCommerce admin: API URL, provider route, webhook callback, reconciliation checks, payment status source, operation history, audit JSON export, fiscal metadata display, generated payment URL and QR preview.
2. VPOS.am payment method in WooCommerce checkout with icon, provider-aware title and hosted-checkout redirect copy.

== Changelog ==

= 0.1.0 =

* Initial marketplace submission candidate with checkout redirect, signed webhooks, reconciliation, manual server-side payment refresh, order payment audit panel with operation history and audit JSON export, support playbook snippets, diagnostics, WooCommerce Blocks/HPOS compatibility, idempotent order payment-link action, PayLinks admin page, QR preview, fiscal metadata display/refresh, optional guarded fiscal retry/refund/capture/void/tokenization/subscription requests, shortcode/block embed and RU/HY translations.

== Upgrade Notice ==

= 0.1.0 =

Initial release candidate. Test in a clean WooCommerce store before enabling live payments.

