WooCommerce integration guide

This guide explains how to connect a WooCommerce store to Yera Connect using the Yera Connect for WooCommerce plugin.

What the plugin does

The plugin lets a merchant:

1. Install Yera Connect inside WordPress.
2. Connect the store with three values: Merchant ID, Yera API Key, and Security Code.
3. Create Yera Checkout sessions from WooCommerce orders.
4. Redirect customers to the Yera hosted checkout page.
5. Receive payment status updates back in WooCommerce automatically.
6. Show clear WooCommerce checkout errors if the store is not connected correctly.

The plugin does not ask the merchant to enter a wallet address, and it never asks for webhook setup. Webhooks are registered automatically when the store connects.

Requirements

Before installing the plugin, confirm:

1. WordPress is installed.
2. WooCommerce is installed and active.
3. The merchant has a Yera Connect account.
4. The merchant has an active settlement destination under Wallets & Settlements for the key's environment and selected network.
5. The merchant can open Dashboard -> Developers -> API Credentials.

Live payments also require the merchant account to be approved. Sandbox testing works before approval.

If WooCommerce is not active, the plugin shows this WordPress admin notice:

Yera Connect for WooCommerce requires WooCommerce to be installed and activated.

Download the plugin

Install it in WordPress:

WordPress Admin -> Plugins -> Add New -> Upload Plugin

Upload the ZIP, activate the plugin, then open the Yera Connect menu in the WordPress admin sidebar.

Connect your store

Open Dashboard -> Developers -> API Credentials in Yera Connect and copy:

1. Merchant ID
2. Yera Live API Key
3. Security Code

Paste all three into the plugin's Yera Credentials card and press Save & Connect. New connections accept Live credentials only. Historical Test connections and tokens cannot be reused.

Keep the API key server-side only. It must never be exposed on the storefront, in theme templates, or in browser JavaScript.

Use Test Connection at any time to re-check the connection with the saved credentials.

Fixed plugin host

The plugin uses the Yera Connect app host internally:

https://app.yeraconnect.io

This value is not shown as a merchant setting in the current plugin. Merchants should not configure an API base URL manually during normal setup.

Webhooks are automatic

The plugin exposes this webhook endpoint inside the merchant WordPress site:

https://merchant-store.com/wp-json/yera-connect/v1/webhook

When the store connects, Yera Connect registers this endpoint automatically and the plugin stores the signing secret it needs to verify incoming updates. There is nothing to configure: the URL is shown read-only, and no secret needs to be copied.

When an event is received, the plugin:

1. Verifies the signature and rejects invalid requests.
2. Finds the matching WooCommerce order.
3. Adds an order note.
4. Updates the WooCommerce order status.
5. Logs the event if debug mode is enabled.

Currency logic

The plugin sends the WooCommerce order currency to Yera Connect.

If the store order is in USD, the checkout session is created in USD. If the store order is in EUR, the checkout session is created in EUR.

The final checkout request follows the actual WooCommerce order currency.

Country detection

The plugin detects the checkout country in this order:

1. WooCommerce billing country
2. WooCommerce shipping country
3. WooCommerce store base country

Country detection is automatic in the current plugin. There is no customer country detection field or fallback country field for merchants to configure.

Settlement readiness

The WooCommerce plugin does not request a wallet address. Yera resolves the active destination under Wallets & Settlements for the API key's environment and checkout network. Checkout fails closed when that exact destination is unavailable.

Checkout flow

The normal WooCommerce payment flow is:

1. Customer creates a WooCommerce order.
2. Customer chooses Yera Connect at checkout.
3. Plugin sends order amount, currency, detected country, order ID, customer email, and metadata to Yera Connect.
4. Yera Connect creates a hosted checkout session.
5. Plugin redirects the customer to Yera Checkout.
6. Customer completes payment.
7. Yera Connect receives provider/payment updates.
8. Yera Connect sends the normalized status to WooCommerce.
9. WooCommerce order status updates automatically.

Status mapping

The plugin maps Yera statuses into WooCommerce order states.

Orders are never marked paid while a payment is still confirming. Physical orders usually stay Processing after payment so the merchant can fulfill the order. Digital or downloadable orders can be completed automatically when configured.

Mock mode

Mock mode is only for visual content testing before live API setup is ready.

When mock mode is enabled, the plugin loads sample:

1. Site-wide banner
2. Product page widget
3. Cart message
4. Checkout message

Mock mode is clearly labeled and should not be used for live checkout testing.

Sandbox test checkout

To run a sandbox test:

1. Connect the store with your Merchant ID, Sandbox API Key, and Security Code.
2. Confirm the connection status shows Connected.
3. Confirm an active Test settlement destination exists for the selected asset and network.
4. Add a WooCommerce product to cart.
5. Choose Yera Connect as the payment method.
6. Place the order.
7. Confirm the customer is redirected to Yera Checkout.
8. Complete or simulate the sandbox payment.
9. Confirm WooCommerce receives the status update.

Storefront notifications

If the plugin is not connected correctly, customers should not reach a broken checkout.

The plugin shows a WooCommerce notice when:

1. The store is not connected.
2. The checkout session cannot be created.
3. The API response is invalid.
4. WooCommerce is inactive.

Merchants can enable debug mode to see connection attempts, sync attempts, API errors, webhook events, and checkout errors inside WordPress Admin.

Troubleshooting

Checkout does not redirect

Check:

1. The Merchant ID, Yera API Key, and Security Code are saved and the status shows Connected.
2. You are using the right key for the right mode (Sandbox key for testing, Live key for real payments).
3. The merchant account is approved when using a Live key.
4. An active settlement destination exists for the key's environment and selected network.

Order status does not update

Check:

1. The WordPress webhook URL is reachable over HTTPS.
2. Security plugins are not blocking REST API requests.
3. "Last webhook received" in the plugin settings updates after a test payment.
4. Debug mode shows the webhook event.
5. The WooCommerce order has a saved Yera checkout session ID.

If the webhook connection was lost, press Reconnect webhook in the plugin settings.

Wrong currency appears

Confirm the WooCommerce order currency. Yera Connect uses the order currency sent by the plugin.

Wallet error appears

Confirm that an active settlement destination exists under Wallets & Settlements for the key's environment and selected network. The plugin does not manage wallet addresses.

Production checklist

Before going live:

1. Disable mock mode.
2. Connect with your Live API Key (keys starting with yera_live_).
3. Confirm the merchant account is approved for live payments.
4. Confirm an active Live settlement destination exists for the selected network.
5. Run a low-value live checkout.
6. Confirm WooCommerce order status updates.
7. Confirm debug logs do not expose API keys.

Production test order

Run the first live order as a controlled low-value payment.

1. Disable mock mode in the plugin.
2. Confirm the store is connected with the Live API Key.
3. Confirm the merchant has live access and an active Live settlement destination for the selected network.
4. Confirm the WordPress webhook URL is reachable over HTTPS.
5. Place a low-value order with a monitored customer email.
6. Complete the live payment.
7. Confirm Admin -> Webhook Logs shows a processed callback with pending=false, matching address, matching ticker, txid values, and sufficient amount.
8. Confirm Admin -> Sessions -> Session detail shows the payment status timeline ending in completed.
9. Confirm WooCommerce received the callback, added an order note, and moved the order to the expected paid status.
10. Confirm the merchant email notification arrived.
11. Confirm merchant webhook delivery succeeded if the merchant uses a custom webhook endpoint.

Keep these references for launch support:

1. WooCommerce order ID
2. Yera session ID
3. Yera transaction ID
4. Provider callback event ID
5. Webhook delivery ID