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. Add a Yera Connect public key and secret key.
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.
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. Settlement wallet setup stays inside the Yera Connect dashboard.

Requirements

Before installing the plugin, confirm:

1. WordPress is installed.
2. WooCommerce is installed and active.
3. The merchant account is approved in Yera Connect.
4. The merchant has a verified default wallet in the Yera Connect dashboard.
5. The merchant has a public key and secret key for WooCommerce.
6. The dashboard wallet is verified for the supported settlement setup.

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

Download the latest ZIP from the dashboard:

Dashboard -> WooCommerce Setup -> Download plugin

The live download route is:

https://yeraconnect.io/downloads/yera-connect-for-woocommerce

Install it in WordPress:

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

Upload the ZIP, activate the plugin, then open:

WordPress Admin -> WooCommerce -> Settings -> Payments -> Yera Connect Pay

Add API keys

In the plugin settings, add:

1. Yera Connect public key
2. Yera Connect secret key
3. Webhook secret

Use test keys while running sandbox checkout tests.

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

API base URL

The API base URL is fixed inside the WooCommerce gateway settings:

https://yeraconnect.io

Merchants should not change this value during normal setup.

Webhook URL

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

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

Yera Connect uses this endpoint to send normalized payment events back to WooCommerce.

The URL is shown as a read-only field in the WooCommerce gateway settings. The plugin sends it to Yera Connect when a checkout session is created.

Webhook secret

Paste the Yera Connect webhook secret into the WooCommerce gateway settings.

The plugin uses this shared secret to verify signed webhook requests from Yera Connect. If a secret is configured, unsigned or invalid webhook requests are rejected.

When an event is received, the plugin:

1. Finds the matching WooCommerce order.
2. Adds an order note.
3. Updates the WooCommerce order status.
4. 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
4. Manual fallback country

Keep detection on auto for normal merchant stores. Manual mode is only for stores that must force one fallback country.

Dashboard wallet

The merchant wallet is managed in the dashboard. The WooCommerce plugin does not request a wallet address.

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, WordPress webhook URL, webhook secret reference, 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.

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. Enable test mode in the plugin.
2. Confirm the public and secret keys are saved.
3. Confirm the API base URL points to Yera Connect.
4. Add the webhook secret.
5. Confirm customer country detection is set to auto.
6. Confirm the merchant has a verified dashboard wallet.
7. Add a WooCommerce product to cart.
8. Choose Yera Connect as the payment method.
9. Place the order.
10. Confirm the customer is redirected to Yera Checkout.
11. Complete or simulate the sandbox payment.
12. 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. API keys are missing.
2. The store is disconnected.
3. The checkout session cannot be created.
4. The API response is invalid.
5. 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. Public key and secret key are saved.
2. Test mode matches the key type.
3. API base URL is correct.
4. Merchant account is approved.
5. Default dashboard wallet is verified.
6. Webhook secret is saved.

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. Webhook secret matches the Yera Connect dashboard secret.
4. Debug mode shows the webhook event.
5. The WooCommerce order has a saved Yera checkout session ID.

Wrong currency appears

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

Wallet error appears

Open the Yera Connect dashboard and verify the merchant wallet. The plugin does not manage wallet addresses.

Production checklist

Before going live:

1. Disable mock mode.
2. Disable test mode.
3. Add live public and secret keys.
4. Confirm the live API base URL.
5. Confirm the dashboard wallet is verified.
6. Confirm the webhook secret is saved.
7. Run a low-value live checkout.
8. Confirm WooCommerce order status updates.
9. Confirm debug logs do not expose secret keys.

Production test order

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

1. Disable mock mode and test mode in WooCommerce.
2. Confirm live public and secret keys are saved.
3. Confirm the merchant has live access and a verified dashboard wallet.
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 -> PayGate Callbacks 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. PayGate callback event ID
5. Webhook delivery ID