SETUP GUIDE

CoinVoyage for WooCommerce

Accept crypto and eligible card payments for USD orders with CoinVoyage Payments.

Requirements

Your store needs WordPress 6.5+, PHP 8.1+, WooCommerce, USD as its currency and a public HTTPS webhook URL. Use API credentials, settlement settings and a webhook from the same CoinVoyage organization. Secure admin storage requires PHP Sodium and configured WordPress security keys.

Get your CoinVoyage API key

Follow the API key setup guide to create your public API key.

PayKit offers crypto and eligible card payments. Available payment methods depend on your account and order.

Install the plugin

Download the ZIP. In WordPress, go to Plugins → Add New → Upload Plugin, choose the ZIP, then select Install Now and Activate.

Download CoinVoyage Payments

CoinVoyage Payments is the dedicated checkout plugin. If upgrading from the combined 0.1.2 plugin, upgrade it to the standalone widgets release or deactivate it before using the new gateway. Existing orders and settings are preserved.

Connect your CoinVoyage account

Open Settings → CoinVoyage Payments. Enter your Public API key and save your settings.

In the CoinVoyage dashboard, configure your settlement wallet and at least one settlement asset and network. Follow the settlement guide.

Under Connection secrets in WordPress, paste your API secret and click Save connection secrets. Saved values stay hidden. Leave a field blank to keep it.

Connect payment updates

Copy the webhook URL shown in Settings → CoinVoyage Payments.
Open CoinVoyage Developers, find Webhooks and click Add webhook.
Paste the URL and select Completed, Error, Expired, Refunded and Partial Payment.
Click Create. Copy the webhook secret using the copy button in the table.
Return to WordPress, paste it into Webhook secret, then click Save connection secrets.

The webhook secret is different from your API secret. Keep the webhook enabled and its HTTPS address publicly reachable. Saved status does not verify delivery.

Already using server configuration?

COINVOYAGE_API_SECRET and COINVOYAGE_WEBHOOK_SECRET in your hosting environment or private wp-config.php are used when no saved secret exists. Save a new value here to override a detected server secret. Removing a saved secret restores the server value. Leave a field blank to keep the current secret. Unreadable saved secrets must be replaced or removed. Changing WordPress security keys requires re-entering encrypted secrets.

Enable CoinVoyage checkout

Go to WooCommerce → Settings → Payments and enable CoinVoyage. Set your store currency to USD.

Both classic and block checkout open a secure payment dialog on your store. Customers can resume after closing it, or open the hosted payment page in a new tab.

Customize payment appearance

Open Settings → CoinVoyage Payments and adjust PayKit colors, radius or advanced theme settings. These apply to the on-page payment window; hosted payment pages keep their own styling.

Test your setup

All checkout payments use production. Verify your setup before accepting customer orders. Confirm that the payment dialog opens and that the WooCommerce order is marked paid only after verified completion.

Signed webhooks update orders even when customers do not return to your store. There is no payment-status polling. Failed deliveries are retried for up to four hours; review unresolved payments after a longer outage.

What if an order needs review?

Check the order notes and the CoinVoyage payment record before taking action. Ambiguous or mismatched payments remain unpaid for manual review. Do not delete payment attempt metadata or blindly recreate a payment.

Local integration checks pass; live provider payment and wallet verification are still pending.

Payment options

These controls require integration version 0.1.6 or later. The downloads on this page are version 0.1.7. Update your installed plugin before using these settings.

Open checkout on Pay with card

Open Settings → CoinVoyage Payments → Payment modal. Set Payment method to Pay with card. You can also choose Wallet, Deposit address or Default to keep the normal starting screen.

Card payments must be enabled and available for your account and order. If unavailable, PayKit shows payment method selection. Choosing a method selects the first screen when the modal opens. Classic and block checkout open the modal automatically after the customer places an order. Enable Card payments in the plugin settings.

Close on success closes the modal after payment; Reset on success clears the widget's payment state. Leave Default selected to keep SDK defaults. These preferences apply to the on-page modal; hosted fallback pages use their own settings. Checkout still returns to the order page after completion. A new purchase still needs a fresh server-created order; resetting a widget does not create one.

Configure PayKit options and debug mode

Open Settings → CoinVoyage Payments → PayKit provider and enter Provider options JSON. For example:

Provider options JSON

{"language":"de-DE","hideTooltips":true,"overlayBlur":4}

Use Debug mode for SDK diagnostics; leave it off for normal use.

Option	Value
`language`	A supported locale, such as en-US, de-DE or fr-FR.
`hideTooltips, hideQuestionMarkCTA, hideRecentBadge`	true or false to hide each UI element.
`walletConnectCTA`	"link", "modal" or "both".
`disclaimer`	Plain text, or null to clear it. HTML is displayed as text.
`overlayBlur`	A finite number of zero or greater.
`optimisticConfirmation`	true or false. Browser completion still requires server verification.
`bufferPolyfill`	true or false. Leave unset unless you need to control the Buffer polyfill.
`experimentalFeatures.cardPayments`	true or false. An explicit card-payments setting takes precedence.

Omit options to keep SDK defaults. Unknown fields and invalid values are rejected. hideNoWalletCTA is accepted by PayKit but currently has no visible effect. The plugin's Card payments setting takes precedence over experimentalFeatures.cardPayments. Existing orders keep their saved card preference.