=== Vaultion Payments ===
Contributors: troysteele
Tags: payments, woocommerce, cryptocurrency, escrow
Requires at least: 6.9
Requires PHP: 8.1
Tested up to: 7.1
Stable tag: 1.4.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

Accept crypto in WooCommerce with just your wallet address. Hosted checkout, optional USDC escrow on Base. No account or API key.

== Description ==

Vaultion Payments adds a crypto checkout to WooCommerce (classic checkout and Checkout Blocks). Activate it, paste the wallet address you want to be paid to, and checkout is live. There is no account to create, no API key and no approval step. The plugin is free software; the hosted Vaultion service takes its transaction fee on chain from each payment.

Customers choose a coin first, then a network. One EVM address (0x…) receives on Base, Ethereum and Arbitrum (ETH/USDC) and Polygon (POL/native USDC). Optional Bitcoin, Litecoin, Solana (SOL/USDC/USDT) and TRON (TRX/USDT) addresses add those networks. A network appears at checkout only when the hosted service has it active and you have saved an address for it; the settings page lists the networks your buyers will see. XRP and Monero are not supported by this version.

Bitcoin and Litecoin work differently from the other coins: the buyer sends to a Vaultion deposit address, Vaultion holds the funds while they are in transit, and after confirmation it forwards the merchant amount to the merchant's receiving address within minutes. This route is not non-custodial. The buyer total includes a disclosed network-fee allowance for that forwarding. A Bitcoin or Litecoin payment that arrives short still completes the order: you receive what arrived less the service fee and that allowance, and an order note states the amounts.

ETH on Base and Ethereum can also be paid with "Send to address", which works the same way: the buyer sends ETH from any wallet or exchange to a Vaultion deposit address for that order, and Vaultion forwards the merchant amount through the same payment contract after confirmation. This route is also not non-custodial, and its buyer total includes a disclosed network-fee allowance. Connect wallet payments on those networks stay non-custodial.

Merchants can offer direct payment, let buyers choose, or require USDC escrow on Base. Escrow requires at least 50 USDC and an EVM address, which becomes the seller. Additional networks support direct payments only.

Your merchant workspace is the Vaultion page under WooCommerce > Settings > Payments: an overview, payment links (a fixed-price checkout link for a service, deposit or invoice, backed by a WooCommerce order), every crypto payment with its transaction, your coins and wallets, escrow settings by network, and settings. It is built from this site's own orders and saved addresses; there is no separate sign-in.

The plugin checks the payment status of its own recent Vaultion orders with the service every few minutes (WP-Cron), and again when a buyer returns to the order page. Returning to the store or supplying a transaction hash alone never marks an order paid. Existing orders keep their original terms and receiving addresses when settings change.

A pay button anywhere on the site: [vaultion_pay name="Website deposit" amount="20.00"] creates a WooCommerce order for that fixed USD amount and opens the hosted checkout, like a workspace payment link.

Merchants with an existing Vaultion merchant account can still connect it with an API key under Settings > Vaultion connection. A connected store uses the account's settings, signed callbacks and the fixed-price [vaultion_pay] shortcode for payment items stored in the account; the hosted merchant dashboard provides email-code sign-in, payment items, receiving-wallet settings and escrow policy.

Escrow funding leaves WooCommerce orders on hold. Only a verified full merchant allocation can mark the order paid. Disputed, refunded, split, late and duplicate payments need review. A finalized escrow credit still needs withdrawal through the escrow interface. The plugin does not initiate refunds, release escrow, rule disputes or withdraw funds.

Escrow checkout quotes last up to 60 minutes, capped by the order session expiry, with up to one additional minute for transaction inclusion. Funding after that deadline is labelled late and stays on hold for manual review. The on-chain escrow is still active: its seven-day buyer review period runs from funding, and the seller can claim after that period under the contract rules. A store hold does not pause the contract. Contact both parties promptly, inspect the escrow deadline and agree fulfilment or a separately authorized refund; do not ask the buyer to pay again.

Vaultion-assisted human arbitration is not decentralized: you are trusting Vaultion's reviewers. The guardian can pause a ruling but never redirect funds. Review the existing escrow terms before funding. Direct payments have no escrow protection.

Service operator: Vaultion Group Inc., registered in Seychelles.
Support and privacy requests: service@vaultion.org.

* [Merchant service](https://checkout.vaultion.org/account/login)
* [Payments service terms](https://vaultion.org/payments/terms)
* [Payments privacy](https://vaultion.org/payments/privacy)
* [Escrow terms](https://vaultion.org/terms)

== Installation ==

1. Install and activate Vaultion Payments. WooCommerce is required; the store currency must be USD.
2. Open Vaultion > Coins & wallets (or WooCommerce > Settings > Payments > Vaultion, or follow the "Add your wallet address" notice) and paste at least one receiving address. Save: the page confirms which networks your buyers will see, or names an address it could not accept. Checkout is on by default.
3. Review the suggested disclosure in Settings > Privacy > Policy Guide and publish your store's own policy. Place a small test order before relying on it.

Only use addresses you control. Payments to a mistyped address cannot be recovered by Vaultion.

Connected merchant accounts (optional): open Settings > Vaultion connection as an administrator and verify the assigned API key and optional signed-callback secret. The production service is fixed to https://checkout.vaultion.org. Keep credentials on the server, never in page content or browser JavaScript. Server constants VAULTION_PAYMENTS_API_KEY and VAULTION_PAYMENTS_WEBHOOK_SECRET take precedence over saved options. Saved credentials are non-autoloaded and are not displayed. Separate verify-and-activate forms support prepared replacement API keys and callback secrets for the same merchant. Existing orders and callback overlap are preserved.

The integration has been tested with WordPress 7.1, WooCommerce 11.1.0 and PHP 8.3.33, including HPOS and Checkout Blocks. This is not exhaustive coverage of every version combination.

= Existing test installations =

Explicit VAULTION_STAGING_ORIGIN and legacy VAULTION_TEST_* configuration remain restricted to controlled staging or local WordPress environments. Base Sepolia test credentials cannot silently become mainnet credentials. Orders and credentials remain bound to their original service and network.

Existing vaultion-local-testnet installations use the separate same-folder compatibility ZIP supplied by the operator. Do not activate the old test plugin alongside the public plugin. Review any migration of an existing store rather than switching its origin or deleting its orders.

== External services and data ==

This plugin needs the hosted Vaultion service (https://checkout.vaultion.org) to create checkout sessions, quote token amounts, verify blockchain receipts, reconcile orders and, for connected accounts, deliver signed status notifications. Nothing is sent until an administrator saves a receiving address or connects an account. No connection credentials are bundled and no third-party executable code is downloaded into WordPress.

When checkout is requested, the WordPress server sends product/order references, a description, order-derived USD pricing and payment preferences to Vaultion. Without a connected account, every order also sends this site's web address and site name and the receiving addresses saved in the payment settings; saving those settings sends the same data to check them. Every few minutes, and when a buyer returns to the order page, the site asks the service for the status of its recent Vaultion orders by their session reference. WooCommerce sends the order number and total, not billing names, customer emails, postal addresses or cart line items. Merchant-written product descriptions should not contain unnecessary personal information. The browser is redirected to the hosted checkout, which processes public wallet addresses, amounts, attempt and transaction references. Payment-linked escrow also records agreement, fee and settlement references.

Cloudflare supplies hosted Workers, D1 storage, request protection, operational logs and merchant sign-in email. Wallet and RPC providers process blockchain requests. Blockchain records are public and permanent. Escrow agreement metadata and evidence can be published to IPFS through Pinata and reviewed through the escrow process; do not publish confidential material. Kraken public Trades supplies USD prices for the enabled ETH, USDC, USDT, SOL, POL and TRX assets without receiving account, order or wallet identifiers in price requests. Stale prices are refused and no fixed stablecoin dollar peg is assumed. Bitcoin, Litecoin and "Send to address" ETH quotes use the Coinbase Exchange public ticker. Bitcoin and Litecoin deposits are observed and forwarded through Bitcoin- and Litecoin-compatible node and indexer providers; neither receives account, order or customer identifiers.

The separate escrow form asks for party names, contact emails and agreement details. These are entered in that form, not read from WooCommerce billing. The existing escrow notification service stores subscriptions and delivery state in Cloudflare KV and delivers through Resend. Updates start from the first email; every email carries an unsubscribe link.

Direct-payment fees are 0.75%, deducted from the merchant amount by default or added for the buyer when configured. Escrow uses its existing fee instead: the buyer pays 4% below 500 USDC, 3% from 500 to below 5,000 USDC, or 2% from 5,000 USDC, separately before funding. Network gas is additional. Exact amounts and expiry are shown before wallet authorization. The plugin cannot reverse a separately paid escrow creation fee if creation is abandoned.

WordPress stores connection options and Vaultion session, network, amount, transaction and status metadata with orders. Checkout saves recovery hints in local storage. Payment-linked escrow also stores fee/creation transaction hints on vaultion.org. Merchant sign-in uses ten-minute challenge and eight-hour session cookies. Plugin removal does not erase orders, connection settings or hosted records. Hosted payment/account records have no general automatic deletion schedule; verified access, correction and deletion requests go to service@vaultion.org. Blockchain and replicated IPFS records cannot be erased by Vaultion. See the linked payments privacy notice for retention and service-provider details.

== Frequently Asked Questions ==

= Do I need a Vaultion account? =

No. Paste your receiving address and checkout works. The service fee is taken on chain from each payment and payments are verified on chain, so there is nothing to sign up for. Your workspace (payment links, payments, coins and wallets, escrow settings) is under WooCommerce > Settings > Payments > Vaultion, built from your own orders; the hosted dashboard is only for merchants who connect an account.

= Is this a wallet or exchange? =

No. Buyers authorize transactions in their own wallets. Vaultion does not collect wallet private keys or recovery phrases. Direct payments split the merchant and service amounts in one transaction; escrow funds are held by the existing escrow contract. Bitcoin, Litecoin and "Send to address" ETH payments are the exception: Vaultion receives those payments at a deposit address and forwards the merchant amount after confirmation.

= What happens if checkout closes? =

Return to the existing checkout or order before paying again. The service rechecks submitted evidence and current status, and the store keeps checking its recent orders. Connected accounts also get signed callbacks, which trigger the same status check; neither a callback payload alone nor a redirect completes an order.

= Can a staging order become a real payment? =

No. The plugin checks the service origin and network recorded with the order. A mainnet connection refuses to reconcile an old test order as a real payment.

== Changelog ==

= 1.4.4 =
The merchant workspace lives where every payment method keeps its settings: WooCommerce > Settings > Payments > Vaultion. The separate Vaultion menu in the WordPress sidebar is gone; the pages and their data are unchanged.

= 1.4.3 =
The workspace looks like the product: Vaultion header with navigation, icons on every card, network and coin logos, real on/off switches for networks, escrow policy as option cards, transaction and network columns in Payments. The WooCommerce payment settings screen links to the workspace.

= 1.4.2 =
"Return to store" on the hosted checkout once a payment is confirmed: the buyer lands on the order page, which checks the order at once. A pay button anywhere on the site without an account: [vaultion_pay name="Website deposit" amount="20.00"] creates the order and opens the hosted checkout. The Payments workspace fills in the network of orders paid before 1.4.0. Needs the hosted service update released with this version for the return link.

= 1.4.1 =
Customize checkout (Vaultion > Settings): business name, logo, theme colour, light/dark/auto appearance and who pays the direct-payment fee, applied to new checkouts. Coins & wallets can switch a network off without removing its address. A customized design or a switched-off network needs the hosted service update released with this version; default settings work either way.

= 1.4.0 =
Merchant workspace inside WordPress (Vaultion menu): overview, payment links, payments with transaction links, coins and wallets, escrow settings by network, settings. Payment links create a WooCommerce order and a hosted checkout for a fixed USD amount. Paid orders record the network they settled on.

= 1.3.1 =
The checkout option shows the logos of the coins your saved addresses accept and the Vaultion logo, in classic and block checkout, and its description names those coins. The logo follows your theme's text colour, so it reads on light and dark checkouts.

= 1.3.0 =
No account needed: activate the plugin, paste a receiving address in the WooCommerce payment settings and checkout is live. Saving the settings checks each address with the service and lists the networks buyers will see. Orders are checked every few minutes and when the buyer returns. Stores connected with an API key keep working unchanged.

= 1.2.2 =
Bitcoin and Litecoin order notes: a short payment still completes the order and the note states what arrived and what you receive; a second note records the payout transaction that reaches your wallet. Corrects the price source for "Send to address" ETH (Coinbase Exchange).

= 1.2.1 =
Recognize direct-payment receipts on Ethereum mainnet (ETH and USDC) when the hosted service has activated that network. Describe the "Send to address" ETH route, which Vaultion receives and forwards like Bitcoin and Litecoin.

= 1.2.0 =
Recognize confirmed Bitcoin and Litecoin deposit payments, which Vaultion receives and forwards to the merchant. The order is marked paid from the confirmed deposit settlement, using the same authenticated status check as other coins.

= 1.1.1 =
Declare compatibility with WooCommerce High-Performance Order Storage and Cart & Checkout Blocks, and declare the tested WooCommerce versions. No payment behaviour changes.

= 1.1.0 =
Recognize independently verified direct-payment receipts on enabled Arbitrum, Polygon, Solana and TRON networks. Preserve Base escrow and controlled test-environment recovery. Hosted network activation and merchant receiving-wallet setup remain separate requirements.

= 1.0.0 =
Add Base mainnet ETH/USDC checkout, optional USDC escrow, explicit network-bound order recovery, production connection settings and service/privacy disclosures. Preserve controlled staging connection and same-folder upgrade support.

== Upgrade Notice ==

= 1.3.1 =
The checkout option now shows your coins' logos and the Vaultion logo.

= 1.3.0 =
Accept crypto with just your wallet address, no account or API key. Connected stores are unaffected.

= 1.2.2 =
Adds Bitcoin and Litecoin order notes for short payments and for the payout transaction to your wallet.

= 1.2.1 =
Adds Ethereum mainnet order recognition. Ethereum appears at checkout only after the hosted service activates it and the merchant saves a receiving wallet.

= 1.2.0 =
Adds Bitcoin and Litecoin order recognition. Those coins appear at checkout only after the hosted service activates them and the merchant saves a receiving address.

= 1.1.1 =
WooCommerce now recognizes the plugin as compatible with High-Performance Order Storage and Checkout Blocks. No settings change.

= 1.1.0 =
Additional networks require hosted-service activation. Existing orders keep their original payment options. Escrow remains USDC on Base.

= 1.0.0 =
First public package. Existing test stores must use the operator-provided compatibility ZIP and retain their staging configuration; do not activate both plugin folders.
