VibeFox Adyen for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Adyen account: you need your Adyen merchant account name, an API key and an HMAC key for each environment you use (test and live), and for live payments the live URL prefix. The API key belongs to an API credential with the Checkout webservice and Merchant PAL webservice roles. The HMAC key is generated for the Standard webhook (see Configuration). The test Customer Area is ca-test.adyen.com, the live one ca-live.adyen.com. Test and live keys are separate.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_adyen_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Adyen > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter your merchant account, the test API key and the test HMAC key, and later the live API key, live HMAC key and live URL prefix.

6. In the Adyen Customer Area (test and live) add a Standard webhook with the URL shown in the plugin settings (see Configuration).

7. Turn on Enable/Disable. Test a payment with Test mode on, then untick it.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Adyen. While the settings of the current mode are incomplete, the page shows Adyen is hidden at checkout until the test settings are complete (or live settings) and lists what is missing: Merchant account, the API key, the HMAC key and, in live mode, Live URL prefix. When you save, an HMAC key that is not hexadecimal and a live URL prefix with other characters than letters, digits and dashes are rejected with an error, and the previous value is kept.

General

Enable/Disable: Enable Adyen payment gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Adyen.

Description: the text shown under the payment method at checkout. Default: Pay securely via Adyen.

Adyen account

API keys are created in the Adyen Customer Area under Developers > API credentials. Fill in both sets of keys; the Test mode switch selects which one is used.

Test mode: Use the Adyen test environment (no real money). When on, payment links and refunds go to checkout-test.adyen.com with the test API key. Default: on. Untick it to take real payments.

Merchant account: your Adyen merchant account name (not the company account), for example MyShopECOM. It is usually the same in the test and live Customer Area.

Test credentials

Used while Test mode is enabled.

Test API key: from the test Customer Area: Developers > API credentials > your credential > API key.

Test HMAC key: from the test Customer Area: Developers > Webhooks > your Standard webhook > HMAC key (hexadecimal). Required: webhooks without a valid signature are rejected.

Live credentials

Used when Test mode is disabled.

Live API key: from the live Customer Area: Developers > API credentials > your credential > API key.

Live HMAC key: from the live Customer Area: Developers > Webhooks > your Standard webhook > HMAC key (hexadecimal).

Live URL prefix: from the live Customer Area: Developers > API URLs, for example 1797a841fbb37ca7-AdyenDemo from https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. You can paste the whole URL; the prefix is taken from it when you save.

Webhook

Orders are marked as paid only by Adyen webhooks. In the Customer Area (test and live) go to Developers > Webhooks and add a Standard webhook with the URL shown in this section of the settings. It looks like https://your-site/wc-api/adyg_adyen_webhook/. Choose the method JSON, enable Generate HMAC key and copy the key into Test HMAC key or Live HMAC key. The environment of each notification selects the HMAC key. Webhooks without a valid signature are rejected, and Adyen retries them later. Without the webhook, orders stay Pending payment.

The plugin handles these events:

AUTHORISATION: the payment was authorised (the order is paid after the amount check) or refused (a waiting order becomes Failed).

CAPTURE: the payment was captured; a note is added.

CAPTURE_FAILED: the capture failed; a paid order is put on hold.

CANCELLATION: the payment of this order was cancelled in Adyen; the order is cancelled.

REFUND: a refund was confirmed or failed; a note is added.

REFUND_FAILED: a refund failed; a note warns that the money was not returned.

Other events are added to the order notes. Notifications that are not for an order of this store, for example the test button in the Customer Area, are accepted and ignored.

Advanced

Order status after payment: the order status set after a successful payment, in one status change.

Processing: the WooCommerce default (default). Virtual downloadable orders are completed automatically.

Completed: every paid order becomes Completed.

On Hold: every paid order waits for your manual review.

Debug log: Log API calls and webhook events to WooCommerce > Status > Logs, source wcp_adyen_gateway. Errors are always logged. Logs never contain API or HMAC keys or shopper personal data. Default: off.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Adyen) and places the order. The plugin creates an Adyen payment link for the order total in the order currency and sends the customer to the Adyen payment page. There the customer pays with any method enabled in your Adyen account. The customer's billing e-mail, name and country and the store language are passed to Adyen, and the payment shows as Order # and the order number.

After paying, the customer returns to the order received page of your store. The return itself does not mark the order as paid: the order is marked paid only after Adyen confirms it with the signed AUTHORISATION webhook and the amount and currency match the order.

If the payment is refused, the order becomes Failed and the customer can try again. When the customer starts a new payment for the same order, for example from the Pay for order page, the previous payment link is expired, so it cannot be paid as well.

If the payment link cannot be created, the customer sees Payment could not be initiated. Please try again or choose another payment method. The reason is added to the order notes. If the settings are incomplete, the customer sees Payment gateway is not configured properly. Please contact the store administrator.

For currencies without decimals, such as JPY, KRW, IDR or VND, set WooCommerce > Settings > General > Number of decimals to 0. Otherwise the total is rounded to a whole unit.

The payment method works on the classic checkout and on the Checkout block. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no subscriptions or recurring payments, no saved cards, no on-site card fields (Drop-in or Components), no capture or cancel buttons in WooCommerce and no basic authentication for webhooks.

Orders and refunds

Order statuses

Pending payment: the payment link was created and Adyen has not confirmed the payment yet. The order note shows the payment link, amount and environment.

Processing, Completed or On Hold: the payment was authorised. The status follows Order status after payment. The order note shows the amount, the PSP reference and the payment method. The transaction ID is the Adyen PSP reference.

On hold after payment: Adyen confirmed a different amount or currency than the order total. The order note shows both, and the order is not marked as paid. A paid order is also put on hold when a capture fails, because the money was not collected. Check the payment in the Customer Area.

Failed: the payment was refused. Paid, on-hold and cancelled orders are not changed by a refused payment.

Cancelled: the payment of this order was cancelled in Adyen.

If a second successful payment arrives for an order that is already paid, for example from an old payment link, the order is not changed again. A note asks you to check the Customer Area for a duplicate charge and refund it there if needed.

Refunds

Open the order, click Refund, enter the amount and click Refund via Adyen. Full and partial refunds are supported. The refund is sent to the environment and merchant account the payment was made with, so that environment's API key must be set. Adyen processes refunds asynchronously: the request is noted on the order, and the final result is added as an order note by the REFUND or REFUND_FAILED webhook. If Adyen does not accept the request, WooCommerce shows the error and no refund is recorded. With manual capture in Adyen, only captured payments can be refunded.

Refunds made in the Adyen Customer Area arrive by webhook and are added to the order notes. They are not recorded as WooCommerce refunds automatically.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Adyen. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Adyen is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Adyen does not appear at checkout: check that the license is active, Enable/Disable is on and the settings of the current mode are complete: Merchant account, the API key and the HMAC key of that mode, and in live mode Live URL prefix. The settings page lists what is missing.

The payment went through, but the order stays Pending payment: the webhook is not working. In the Customer Area of the environment you use (test or live) check that the Standard webhook exists, that its URL is exactly the one shown in the settings and that the method is JSON. Check that the HMAC key of that webhook is in the matching field (Test HMAC key or Live HMAC key). With an invalid or missing HMAC key the plugin answers HTTP 401 and Adyen retries the delivery later, so the order is updated automatically once the key is fixed. The log shows Webhook rejected: invalid HMAC signature or that the HMAC key is not configured.

Webhook answers busy, retry later: the order was being processed by another delivery at the same moment. Adyen retries the webhook automatically.

The HMAC key error on save: the field must contain the hexadecimal HMAC key from the Customer Area. The previous value was kept.

The customer sees Payment could not be initiated: open the order notes or turn on Debug log and look at WooCommerce > Status > Logs, source wcp_adyen_gateway. Check the API key, the merchant account and, in live mode, the live URL prefix.

Order is On hold after payment: read the order note. The amount or currency confirmed by Adyen did not match the order, or a capture failed. It can also be your Order status after payment setting.

Refund fails: the order must have an Adyen PSP reference, which arrives with the AUTHORISATION webhook. The credentials of the environment the payment was made in must be set. With manual capture, only captured payments can be refunded.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the Adyen data stored on orders (PSP references, payment links, processed events) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Adyen is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Adyen.