=== Wolf Pay for WooCommerce ===
Contributors: wolfpay
Tags: woocommerce, payment gateway, crypto, usdc, usdt
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept USDC and USDT stablecoin payments in WooCommerce with Wolf Pay's hosted checkout and signed webhooks.

== Description ==

Wolf Pay lets your customers pay with USD stablecoins (USDC or USDT) from any wallet or exchange. At checkout the customer is sent to a mobile-friendly Wolf Pay page with the amount, the deposit address, a QR code and a live countdown. When the payment settles, Wolf Pay sends a signed webhook and the order is marked paid automatically.

**Features**

* USDC on Base, Ethereum, Arbitrum, Polygon and Solana; USDT on TRON, Ethereum and Solana (live mode). Test mode also offers USDC on BNB Chain and USDT on Polygon, Arbitrum and BNB Chain.
* Hosted checkout: no wallet code or addresses on your site.
* Orders complete automatically from signed webhooks (HMAC-SHA256, 5-minute replay window).
* Defense in depth: before an order is marked paid, the plugin asks the Wolf Pay API for the payment and checks the order id, amount, coin and mode. A leaked webhook secret alone can't mark orders paid.
* Underpaid payments put the order on hold with the amounts; overpaid payments complete the order with a note.
* Refunds from the WooCommerce order screen go back to the wallet the customer paid from.
* Retries are safe: payments and refunds are created with an Idempotency-Key, so a double click never creates two payments.
* Test mode with wp_test_ keys: the Wolf Pay checkout shows buttons to simulate paying in full, too little, too much or letting the payment expire.
* Works with the classic checkout and the Cart & Checkout blocks. Compatible with High-Performance Order Storage (HPOS).

**Requirements**

* WooCommerce 7.0 or later.
* Store currency set to US dollar (USD). Stablecoins are pegged to the dollar, so the gateway is hidden for other currencies. The amount charged is the order total rounded to 2 decimals, 1 USD = 1 USDC/USDT.
* A Wolf Pay account and secret API key.

== External services ==

This plugin connects to the Wolf Pay API (https://wolf-pay-five.vercel.app/api/v1 by default) to create payments, read their status and create refunds. It sends the order amount, the chosen coin and network, the order number, a short description ("Order #123 from Your Store"), the customer's billing email, the order-received URL, the WooCommerce order id and your site URL. The customer is redirected to the Wolf Pay hosted checkout to pay. Wolf Pay also sends webhooks to your site. Data is only sent when a customer chooses Wolf Pay at checkout or when you refund an order.

== Installation ==

1. Upload the `wolf-pay-for-woocommerce` folder to `/wp-content/plugins/`, or install the zip from Plugins → Add New → Upload Plugin, and activate it.
2. Make sure WooCommerce → Settings → General → Currency is **United States (US) dollar**.
3. In the Wolf Pay dashboard go to **Developers**, create a secret key and copy it. Use a `wp_test_` key first.
4. In WordPress go to **WooCommerce → Settings → Payments → Wolf Pay (USDC / USDT)**. Enable it and paste the key into **Secret API key**.
5. Choose the **Coin** and **Network** customers will pay with.
6. Set up the webhook:
    1. Copy the **webhook URL** shown on the settings page. It looks like `https://yourstore.com/wc-api/wolf_pay/` (or `https://yourstore.com/?wc-api=wolf_pay` without pretty permalinks).
    2. In the Wolf Pay dashboard go to **Developers → Webhooks**, add an endpoint with that URL and save.
    3. Wolf Pay shows the signing secret (`whsec_…`) once. Paste it into **Webhook signing secret** in WooCommerce and save.
    4. Use the dashboard's **Send test** button: the delivery should show HTTP 200.
7. Place a test order, pay it with the simulate buttons on the Wolf Pay checkout and check that the order moves to Processing.
8. When you are ready, replace the test key with a `wp_live_` key. Webhook endpoints belong to a mode, so add a live endpoint in Wolf Pay too and paste its signing secret.

The webhook URL must be `https://` on a public domain name. Wolf Pay does not deliver to IP addresses, custom ports or localhost; for local development use a tunnel such as ngrok.

== Frequently Asked Questions ==

= Why is Wolf Pay not shown at checkout? =

The gateway is only offered when it is enabled, the store currency is USD, a valid `wp_test_` or `wp_live_` key is saved and the selected coin/network pair is available in that key's mode. An admin notice tells you when the currency is the problem.

= How does an order get marked paid? =

Wolf Pay sends a `payment.paid` (or `payment.overpaid`) webhook. The plugin verifies the `Wolf-Signature` header, fetches the payment from the Wolf Pay API, checks that it was created for this order with the same amount, coin and mode, and then calls WooCommerce's payment complete (the order moves to Processing, or Completed for virtual/downloadable orders). If the customer returns to your site before the webhook arrives, the thank-you page also asks the API for the latest status.

= What happens if the customer pays too little or too much? =

Too little (`payment.underpaid`): the order goes on hold with a note showing the amount received and the amount short. Don't ship; contact the customer. Too much (`payment.overpaid`): the order is completed and a note shows the extra amount, which you can refund.

= What happens if the customer never pays? =

When the Wolf Pay payment expires (default 60 minutes, configurable from 15 to 1440), the order is marked Failed if it is still pending. The customer can pay a failed order again from their account; a new Wolf Pay payment is created. WooCommerce's "hold stock" cleanup won't cancel the order while the Wolf Pay payment window is still open.

= How do refunds work? =

Use the normal **Refund** button on the order screen. The plugin calls Wolf Pay, which sends the refund from your Wolf Pay balance back to the wallet the customer paid from. Refunds must be at least 1.00 and are limited to what the payment received and your available balance; Wolf Pay's fee is not returned. Refund progress (completed, failed, …) is added to the order notes from webhooks. Refunds made in the Wolf Pay dashboard are noted on the order but are not recorded as WooCommerce refunds.

= Is test mode safe? =

Yes. With a `wp_test_` key no real money moves. The settings page and the checkout show that the store is in test mode.

= Which webhook events are used? =

`payment.confirming`, `payment.paid`, `payment.overpaid`, `payment.underpaid`, `payment.expired`, `payment.canceled`, and `refund.created`, `refund.completed`, `refund.partially_completed`, `refund.failed`, `refund.canceled`. Other events (such as `payout.*` and `webhook.test`) are acknowledged and ignored.

= Where are the logs? =

WooCommerce → Status → Logs, source `wolf-pay`. Errors are always logged; enable **Debug log** for API calls and webhooks. Secret keys are never logged.

= What is removed when I delete the plugin? =

The plugin settings (including the API key and webhook secret). Order notes and Wolf Pay order meta are kept as part of your payment records.

== Changelog ==

= 0.1.0 =
* First release: hosted checkout for USDC and USDT, signed webhooks with API re-check, refunds, test mode, HPOS and Checkout block support.

== Upgrade Notice ==

= 0.1.0 =
First release.
