VibeFox Adyen for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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. No client key is needed, because the payment page is hosted by Adyen.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Adyen Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. 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.

5. In the Adyen Customer Area (test and live) add a Standard webhook with the URL shown in the Webhook section of the module (see Configuration).

6. Turn on Enable/Disable and click Save. Test a payment with Test mode on, then turn it off.

On install the module creates the order status Adyen payment on hold. PrestaShop offers a new payment module for the currencies, countries and customer groups that are active at that moment. Check and change them in Payment > Preferences; countries you add later must be ticked there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Each section has its own Save button, which saves the whole page. 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. While test mode is on, the page shows Test mode is on: payment links and refunds go to the Adyen test environment, no real money. When you save, an HMAC key that is not hexadecimal and a live URL prefix with other characters than letters, digits and dashes are not saved: a warning names the field, and the previous value is kept.

Adyen

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Adyen. Required.

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: uses 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. Turn it off to take real payments. While it is on, customers see Test mode: no real payment is taken. under the payment method.

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.

Saved API keys and HMAC keys are never shown again. The field stays empty and its hint ends with Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a key and click Save to remove it. An empty field keeps the saved value.

Webhook

Orders are created 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 Webhook URL in this section. With friendly URLs it looks like https://your-shop/module/wcp_adyen_gateway/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it, because Adyen does not follow redirects. 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, and a notification is applied only to a payment link created in the same environment and merchant account. A test notification never confirms a live payment. Webhooks without a valid signature are rejected with HTTP 401, and Adyen retries them later. Without the webhook, no order is created.

The module handles these events:

AUTHORISATION: the payment was authorised (the order is created after the amount check) or refused (the payment attempt is marked failed, the customer can pay again).

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 a cart of this shop, for example the test button in the Customer Area, are accepted and ignored. The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Order status after payment: the order status set by a successful AUTHORISATION webhook.

Payment accepted (Processing): the standard PrestaShop status for paid orders (default).

Delivered (Completed): every paid order becomes Delivered.

Adyen payment on hold (On Hold): every paid order waits for your manual review. The payment is still recorded on the order.

Amount or currency mismatches and failed captures always go to Adyen payment on hold.

Debug log: writes API calls and webhook events to logs/adyg_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, also when the switch is off. Logs never contain API or HMAC keys or shopper personal data. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the module settings, the Adyen payment records (PSP references, webhook events, refunds) and the logs. The order status Adyen payment on hold and the orders stay. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Adyen) and sees the note You will be redirected to Adyen to complete the payment securely. After confirming, the module creates an Adyen payment link for the cart total in the cart 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 e-mail, name and billing country and the shop language are passed to Adyen, and the payment shows as Cart # and the cart number. No order exists yet at this point.

After paying, the customer returns to your shop. The return itself does not create or pay an order: the order is marked paid only after Adyen confirms it with the signed AUTHORISATION webhook and the amount and currency match the cart. If the webhook has already arrived, the customer sees the standard order confirmation page with Your payment with Adyen has been received. (or Your payment with Adyen has been received and is being reviewed by the store. for an order on hold). If Adyen cancelled the payment before that, the page shows Your Adyen payment was not completed. Please contact us about this order. If the webhook has not arrived yet, a Payment confirmation page shows Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. with the buttons Check again and Back to checkout, for a customer who did not complete the payment.

If the payment is refused, no order is created and the customer can try again. When the customer starts a new payment for the same cart, the previous payment link is expired, so it cannot be paid as well. If the cart already has an order, the customer goes to its confirmation instead of a new payment.

If the payment link cannot be created, the customer stays at checkout with Payment could not be initiated. Please try again or choose another payment method. The reason is written to the log. If the settings are incomplete, the message is Payment gateway is not configured properly. Please contact the store administrator.

Developers can change the payment link request with the hook actionAdygPaymentLinkRequest.

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

Orders and refunds

Order statuses

No order yet: the customer was sent to Adyen and has not paid, the payment was refused, or Adyen has not confirmed the payment yet. Only the cart exists.

Payment accepted, Delivered or Adyen payment on hold: the payment was authorised. The status follows Order status after payment. The payment is recorded with the Adyen PSP reference as the transaction ID, and a note shows the amount, the PSP reference and the payment method.

Adyen payment on hold after payment: Adyen confirmed a different amount or currency than the cart total (for example, the cart was changed after the payment started), a capture failed, or the payment arrived after the order had been cancelled. The note explains it. Check the payment in the Customer Area, then fulfil the order or refund the payment.

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

Refunded: the payment was fully refunded through the module.

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. A note asks you to check the Customer Area for a duplicate charge and refund it there if needed.

Adyen payment block

The order page shows an Adyen payment block with the PSP reference, the payment link, the merchant account and environment, the payment status, the amount paid and refunded, a Test mode badge for test payments, the refund history and Adyen notes: the notes the module adds to the order (payment authorised, amount mismatch, duplicate payment, capture, cancellation, refund results), newest first. These notes are private messages of the order; PrestaShop 8.2 and 9 do not show them elsewhere on the order page.

Refunds

In the Adyen payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Adyen. Confirm the question Refund this amount through Adyen? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders. Refunds are made in the amount and currency Adyen authorised, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent to the environment and merchant account the payment was made with, so that environment's API key must be set. If Adyen does not accept the request, the block shows the error and no refund is recorded.

Adyen processes refunds asynchronously: the request is added to the refund history and the notes with the status received, and the final result arrives by the REFUND or REFUND_FAILED webhook. A failed refund no longer counts as refunded. When the refunds sent reach the amount paid, the order is set to Refunded. A partial refund does not change the status. With manual capture in Adyen, only captured payments can be refunded.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Adyen. Refunds made in the Adyen Customer Area arrive by webhook and are added to the notes. The order status and credit slips are not changed automatically.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Adyen Gateway is the first block on Modules > Module Manager > VibeFox Adyen Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-adyen and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: 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 Webhook URL 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 module answers HTTP 401 and Adyen retries the delivery later, so the order is created automatically once the key is fixed. The log shows Webhook rejected: invalid HMAC signature or that the HMAC key is not configured.

Webhook answers [rejected] HMAC key not configured: the HMAC key of the notification's environment is empty. Paste it into the settings.

Webhook answers [rejected] busy, retry later: the cart was being processed by another delivery at the same moment, or the order could not be created (for example, the module is disabled). Adyen retries the webhook automatically. The reason is in the log.

The webhook URL shows [rejected] POST required in the browser: this is normal. The URL accepts only notifications from Adyen.

The HMAC key warning 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: look at the Log field on the module page (errors are always logged). Check the API key, the merchant account and, in live mode, the live URL prefix.

Order is Adyen payment on hold after payment: read the note on the order. The amount or currency confirmed by Adyen did not match the cart, a capture failed, or the payment came after a cancellation. 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; otherwise the block shows that the credentials are not configured. With manual capture, only captured payments can be refunded.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Adyen Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings, the Adyen payment records (PSP references, webhook events, refunds) and the logs are removed. If it is off, all of them are kept for a later re-install, so orders paid before can still be refunded. The order status Adyen payment on hold always stays. Existing orders keep their payment notes and transaction IDs.

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