=== CoinVoyage Payments ===
Requires at least: 6.5
Requires PHP: 8.1
Requires Plugins: woocommerce
Stable tag: 0.1.4
License: BSD-2-Clause

Accept crypto and eligible card payments for USD WooCommerce orders, with settlement to your crypto wallet.

== Description ==
Give customers a choice of supported crypto payment assets while receiving settlement in the asset and network you configure in CoinVoyage. CoinVoyage Payments brings PayKit to WooCommerce, with an on-page payment window and a hosted payment page as a fallback.

CoinVoyage is non-custodial: payment funds settle to your configured crypto wallet. Set your settlement preferences in the [CoinVoyage dashboard](https://dashboard.coinvoyage.io/); manage your store orders in WooCommerce.

= Built for WooCommerce checkout =

* Accept one-time payments for WooCommerce orders priced in USD.
* Offer crypto payments and eligible card options through PayKit.
* Use classic checkout or the WooCommerce Checkout block.
* Let customers close and resume the payment window, or open payment in a new tab.
* Customize the payment method title and description, and style the on-page payment window.
* Update paid orders through verified CoinVoyage payment notifications.
* Use WooCommerce High-Performance Order Storage (HPOS).

= From checkout to confirmation =

The customer selects CoinVoyage and places the order. PayKit opens on your checkout page to guide them through payment. WooCommerce marks the order paid only after receiving a matching, signed completion notification from CoinVoyage. Closing the window or returning to the store does not itself confirm payment.

= Before you start =

You need a CoinVoyage account, configured settlement, API credentials and an active webhook subscription. Your store must use USD and expose its webhook endpoint over HTTPS. Refunds require manual merchant execution; subscriptions are not supported. See Installation and FAQ for details.

[Explore CoinVoyage](https://docs.coinvoyage.io/introduction) | [Settlement guide](https://docs.coinvoyage.io/dashboard/settlement) | [Pricing](https://docs.coinvoyage.io/resources/pricing) | [Support](https://docs.coinvoyage.io/resources/support)

== Installation ==
= 1. Prepare your store and account =

Use WordPress 6.5 or later, PHP 8.1 or later, and an active WooCommerce installation. Back up your store before installing or upgrading a payment plugin.

In WooCommerce > Settings > General, set the currency to United States (US) dollar (USD). Create or select your organization in the [CoinVoyage dashboard](https://dashboard.coinvoyage.io/). Configure your settlement wallet and at least one settlement asset/network using the [settlement guide](https://docs.coinvoyage.io/dashboard/settlement).

= 2. Install the plugin =

In WordPress, open Plugins > Add New Plugin > Upload Plugin. Select coinvoyage-payments-0.1.4.zip, click Install Now, then Activate Plugin. If you use the legacy combined CoinVoyage plugin, follow the upgrade instructions below before accepting new payments.

= 3. Connect your organization =

In the CoinVoyage dashboard, open Developers > API keys and create or select your API credentials. In WordPress, open Settings > CoinVoyage Payments and save the Public API key. Use the same organization for your API credentials, settlement and webhook subscription.

Under Connection secrets, paste your API secret and click Save connection secrets. This is different from the public API key. Saved secrets stay hidden; leave a field blank to keep its current value. Never put secrets in page content or browser code.

= 4. Connect payment notifications =

Copy the webhook endpoint displayed under Settings > CoinVoyage Payments. In the same CoinVoyage organization, open Developers > Webhooks > Add webhook and use that exact endpoint. Select these events:

* Completed (ORDER_COMPLETED)
* Error (ORDER_ERROR)
* Expired (ORDER_EXPIRED)
* Refunded (ORDER_REFUNDED)
* Partial Payment (ORDER_PARTIAL_PAYMENT)

Click Create, then copy the webhook secret using the copy button in the webhook table. Return to WordPress > Settings > CoinVoyage Payments, paste it into Webhook secret, and click Save connection secrets. This secret verifies payment updates and is different from your API secret. Both secrets are required for checkout.

Keep the webhook active. Its URL must be publicly reachable over HTTPS without login prompts, redirects or firewall challenges. A configured secret alone does not prove that notifications can reach your store.

= 5. Enable and personalize checkout =

Open WooCommerce > Settings > Payments, manage CoinVoyage, enable it, and save. You can change the payment method title and description customers see.

Under Settings > CoinVoyage Payments, choose whether to enable eligible card payments, optionally enter a WalletConnect project ID, and adjust payment appearance. Appearance settings apply to the on-page window; hosted payment pages retain their own styling.

= 6. Verify before accepting customer orders =

Place a controlled, low-value order using your store's checkout. Confirm that payment opens, the completed transaction appears in the CoinVoyage dashboard, and WooCommerce records payment after receiving the signed notification. Also check closing/resuming the window and opening the hosted fallback.

This plugin connects to the production CoinVoyage API; it has no sandbox toggle. A payment test can move real funds and incur fees. Review the [production checklist](https://docs.coinvoyage.io/guides/production-checklist) before launch.

= Checkout operations =
Both classic and block checkout open PayKit in a modal. Closing leaves payment pending; use Resume payment or Open payment in a new tab. Appearance settings apply to the on-page modal. Hosted pages retain their own styling.
Only matching signed COMPLETED events mark orders paid. Ambiguous creation, mismatched amounts, late or terminal events require manual review. Do not blindly create replacement payments. Failed webhook deliveries are retried for up to four hours; longer outages require provider-dashboard review.

= Refunds and supported purchases =
Refunds are supported through the CoinVoyage dashboard or API. Funds settle to the merchant's crypto wallet, so the merchant must execute the refund manually. A provider refund event adds a review note; this plugin does not automatically transfer refund funds or create WooCommerce refund records.
Subscriptions are not supported. Non-USD checkout is on the roadmap.

= Upgrading from the combined plugin =
The legacy CoinVoyage PayKit and SwapKit plugin (0.1.2) included this gateway. CoinVoyage Payments pauses its gateway when that legacy plugin is active, preventing duplicate payment processing.
Install CoinVoyage Payments, then either upgrade the old plugin to the standalone widgets release (0.1.3 or later), or deactivate the legacy plugin. Reload the admin page to complete the transition. Do not delete plugin settings, orders or payment attempts. Checkout is briefly unavailable between deactivation and replacement activation. Configure the replacement before accepting new orders; pending webhooks can retry afterward.
Gateway ID, pending payment data, existing gateway settings and webhook URL are preserved. Payment public settings are copied once into the new settings page; the original widget settings remain untouched. Server secrets keep the same names.

= External services =
CoinVoyage APIs create payments and provide checkout data. PayKit also contacts its wallet connection and blockchain RPC services. WalletConnect may be configured with a project ID. Merchant signing and webhook secrets stay on the server. See https://docs.coinvoyage.io/ for service and integration documentation.

== Frequently Asked Questions ==

= Do I need a CoinVoyage account? =

Yes. Your organization provides the API credentials, settlement configuration and webhook subscription used by this plugin. Create or manage your account at [dashboard.coinvoyage.io](https://dashboard.coinvoyage.io/).

= Which cryptocurrencies and networks can customers use? =

Customers choose from the supported assets and payment routes available in PayKit for their order. Availability can vary by route. See the current [supported networks](https://docs.coinvoyage.io/concepts/supported-networks) documentation for network coverage.

= Can customers pay by card? =

Eligible card payments can be enabled under Settings > CoinVoyage Payments. Availability depends on the payment provider and customer eligibility. Enabling the option does not guarantee a card route for every order. Changing the setting affects new payment attempts.

= Where do I receive payments? =

Funds settle to your configured crypto wallet. Choose your settlement asset and network in the CoinVoyage dashboard. Your customer can pay with a different supported asset when a payment route is available. See the [settlement guide](https://docs.coinvoyage.io/dashboard/settlement).

= Can I price my store in EUR or another currency? =

This release supports USD checkout only. The WooCommerce order currency is separate from the cryptocurrency used to pay or receive settlement. Non-USD checkout is on the roadmap.

= Does it support subscriptions or recurring billing? =

No. This release supports one-time payments and does not provide subscription renewals or automatic recurring charges.

= How do refunds work? =

Refunds are supported through the CoinVoyage dashboard or API. Because funds settle to your crypto wallet, you must execute the refund manually. The plugin does not send funds back automatically or provide automatic WooCommerce refunds. A refund notification adds a review note; after verifying the transfer, reconcile the refund record in WooCommerce.

= Does it work with the Checkout block and HPOS? =

Yes. The plugin supports classic checkout, the WooCommerce Checkout block and HPOS. No shortcode is needed to add the payment method to checkout.

= What happens if a customer closes the payment window? =

The payment remains pending. The customer can use Resume payment or Open payment in a new tab. Closing the window does not cancel an order or mark it paid.

= Why is CoinVoyage missing from checkout? =

Check that WooCommerce and CoinVoyage Payments are active, CoinVoyage is enabled in WooCommerce payment settings, and the store currency is USD. Verify the public API key, server API secret and webhook secret. If the legacy combined plugin is active, complete the migration described under Installation so that only one gateway handles payments.

= A customer paid, but the order is still pending. What should I do? =

Compare the WooCommerce order notes with the transaction in your CoinVoyage dashboard. Check the webhook subscription, selected events, signing secret and endpoint reachability. The store waits for a matching signed completion notification; a success screen alone is not proof of a paid order. Mismatched, partial or late payments may require manual review. Check the existing transaction before creating another payment or fulfilling the order.

Failed webhook deliveries are retried for up to four hours. After a longer outage, or for events from before webhook registration, review the payment in the dashboard and contact support if you need help reconciling it.

= Are there transaction fees? =

CoinVoyage service fees apply. See the current [pricing information](https://docs.coinvoyage.io/resources/pricing) for transaction rates and volume options. Review the payment quote for applicable costs before confirming a payment.

= Can I add standalone payment widgets to other pages? =

This plugin adds a WooCommerce checkout gateway. Standalone page widgets are available through the separate CoinVoyage WordPress widgets integration.

= Where can I get help? =

Read the [CoinVoyage documentation](https://docs.coinvoyage.io/) or email help@coinvoyage.io. Include your plugin, WordPress and WooCommerce versions, relevant order/transaction identifiers, and a description of the issue. Never send API secrets, webhook secrets, wallet private keys or recovery phrases. See [support resources](https://docs.coinvoyage.io/resources/support).

== Changelog ==
= 0.1.4 =
* Add plugin details and documentation links, allow saved secrets to override server values, and show PayKit appearance defaults.

= 0.1.3 =
Separate payment gateway distribution with a PayKit-only runtime and migration from the combined plugin.
