VibeFox Adyen for Adobe Commerce — 도움말

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-adyen-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/AdyenPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_AdyenPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Adyen Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter your merchant account, the test API key and the test HMAC key. In the Adyen test Customer Area add a Standard webhook with the URL shown on the settings page (see Webhook). Set Enable to Yes, click Save Config and place a test order. When you are ready, enter the live API key, live HMAC key and live URL prefix, add the webhook in the live Customer Area, set Test mode to No and click Save Config.

The module adds the Adyen payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Adyen payment attempts, the webhook events it has processed and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Adyen Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

When a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (1 to 128 characters)., Select a valid order status., Sort order must be a whole number. or Order totals must be numbers, 0 or greater. An HMAC key that is not hexadecimal with an even length, or a live URL prefix with other characters than letters, digits and dashes, does not stop the save: Magento saves the rest of the page, keeps the previous value of that field and shows The HMAC key must be hexadecimal with an even length. The previous value was kept. or Live URL prefix may contain only letters, digits and dashes. The previous value was kept.

Below the sections the page shows the webhook URL and the log. While Enable is Yes and the settings of the current mode are incomplete, it also shows Adyen is hidden at checkout until the test settings are complete. (or live settings) with the list of what is missing: Merchant account, the API key, the HMAC key and, in live mode, Live URL prefix. While test mode is on, it shows Test mode is on. Payment links and refunds use the Adyen test environment.

General

Enable: shows or hides Adyen at checkout. It is shown only when the settings of the current mode are complete. Default: No.

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

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely via Adyen.

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

Amount or currency mismatches and failed captures always put the order On Hold.

Credentials

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 Yes, payment links and refunds go to the Adyen test environment with the test API key. Default: Yes. Set it to No 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 API key: from the test Customer Area: Developers > API credentials > your credential > API key. Used while Test mode is Yes.

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 API key: from the live Customer Area: Developers > API credentials > your credential > API key. Used when Test mode is No.

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

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

Magento stores the API keys and HMAC keys encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. To delete a saved key, clear the field and click Save Config. Spaces inside an HMAC key are removed when you save.

Webhook

Orders are invoiced only by Adyen webhooks. In the Customer Area (test and live) go to Developers > Webhooks and add a Standard webhook with the URL shown on the settings page under Standard webhook URL (JSON, HMAC required):. It looks like https://your-store/wcpadyengateway/webhook/index/. Copy the URL exactly as the settings show it. Choose the method JSON, generate the HMAC key and copy it into Test HMAC key or Live HMAC key.

The environment of each notification selects the HMAC key. The key is read with the settings of the store view where the order was placed; notifications that do not belong to an order of this store use the settings of the default store view. A notification is applied only to a payment link created in the same environment and merchant account, so a test notification never confirms a live payment. Each item of a webhook is checked before anything is processed; a webhook with an invalid signature is rejected with HTTP 401, and Adyen retries it later. Without the webhook, no order is invoiced.

The module handles these events:

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. A repeated notification is not processed twice.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Adyen for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Adyen only for billing addresses in these countries.

Minimum Order Total: offer Adyen only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Adyen only up to this order total, in the base currency. Empty means no maximum.

Advanced

Debug log: writes API calls and webhook events to var/log/adyg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged; other levels only while Debug log is enabled. No keys or shopper data are logged. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the settings and the log (see Uninstall). The license key is always removed. Orders, payment attempts, events and refund history are always retained. Default: No. The value of the default store view is used.

Sort order: the position among the payment methods at checkout. A whole number.

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

Checkout

At the payment step the customer chooses the payment method (by default Adyen) and sees the description and the note You will be redirected to Adyen to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates an Adyen payment link for the order total in the order currency and sends the customer to the Adyen payment page, where the customer pays with any method enabled in your Adyen account. The customer's e-mail, name and billing country and the store language are passed to Adyen, and the payment shows the description Order # with the order number.

After paying, the customer returns to your store. The return itself never pays an order: the order is invoiced only after Adyen confirms it with the signed AUTHORISATION webhook and the amount and currency match the order. Then Magento creates the invoice with the Adyen PSP reference as the transaction ID, the order gets the status from Order status after payment and the order e-mail is sent.

If the webhook has already arrived, the customer sees the standard order success page with Your payment with Adyen has been received. If it has not arrived yet, a Payment confirmation page shows Your Adyen payment is awaiting confirmation. and the order number, with the buttons Check again and Back to checkout. Back to checkout is for a customer who did not complete the payment: the order is cancelled (the stock goes back), the open payment link is expired, the cart is restored and the customer sees Adyen payment was cancelled. Your cart has been restored. If the payment has arrived in the meantime, the customer goes to the success page instead. For an order on hold the page shows Your Adyen payment is being reviewed by the store. A customer who comes back in another browser sees the same page without Back to checkout, or the home page with the message once the payment is received.

If the order was cancelled before a payment arrived, the customer sees Your Adyen payment was not completed. Please contact us about this order.; in the browser that placed the order the cart is restored. If the payment is refused, the order stays in Pending Payment with a note, and the customer can go back to checkout and pay again or choose another payment method. 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 a payment from another order, no new payment is started and the customer sees Your quote already has a payment. Please contact the store about the existing order.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer is back in the cart with The Adyen payment could not be started. Please try again or choose another payment method. or the reason, for example Adyen is not configured for this payment. or Adyen did not return a valid payment link. Errors are written to the log.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). When an Adyen order is cancelled, by this cron or in the Admin, its open payment links are expired. If Adyen still reports a payment for a cancelled order, the order is not invoiced: it stays Canceled and a note asks you to check the stock and fulfil the order or refund the payment in the Adyen Customer Area.

Developers can change the payment link request with the Magento event adyg_payment_link_request (transport data and the order).

The module works with the standard Magento checkout. It has no subscriptions or recurring payments, no saved cards, no on-site card fields (Drop-in or Components), no separate capture or void buttons in Magento and no basic authentication for webhooks. Adyen is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Adyen, but Adyen has not confirmed the payment yet, or the payment was refused. There is no invoice.

Processing, Complete or On Hold: the payment was authorised. The status follows Order status after payment. The invoice is created with the Adyen PSP reference as the transaction ID, and a note shows the PSP reference and the payment method.

On Hold after a mismatch: Adyen confirmed a different amount or currency than the order total. No invoice is created, and the note shows the amount received and the amount expected. Check the payment in the Customer Area, then fulfil the order or refund the payment there. A failed capture or a failed refund also puts the order On Hold.

Canceled: the customer went back to checkout, the payment could not be started, the order was cancelled in Magento, or the payment was cancelled in Adyen.

Closed: the order was fully refunded with credit memos.

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

Adyen payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Adyen payment link, Adyen PSP reference, Adyen environment, Adyen merchant account, Adyen payment method, Adyen payment currency and Adyen authorised amount. It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Adyen. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Adyen.

The refund is made in the order currency, up to the amount Adyen authorised minus the amounts already refunded. It 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 refund, Magento shows the error, for example Adyen refund failed. Please check the gateway before retrying. or Invalid Adyen refund amount. At most … can be refunded., and the credit memo is not created. After Adyen accepts the request, Magento records the refund with the Adyen refund PSP reference as the transaction ID. A full refund closes the order.

Adyen processes refunds asynchronously: the final result arrives by the REFUND or REFUND_FAILED webhook and is added to the notes. A failed refund does not remove the credit memo already created; the order is put On Hold, and you have to check the refund in the Adyen Customer Area. Refunds made in the Adyen Customer Area arrive by webhook and are added to the notes. The order and credit memos are not changed automatically. Create a credit memo with Refund Offline if needed. An order without an invoice (for example On Hold after a mismatch, or a payment that arrived after cancellation) cannot be refunded in Magento; refund it in the Adyen Customer Area.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Adyen Gateway is the first row of the VibeFox Adyen Gateway group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-adyen and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Adyen does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

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 on the settings page 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) for the website of the store. With an invalid or missing HMAC key the module answers HTTP 401 and Adyen retries the delivery later, so the order is invoiced automatically once the key is fixed.

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] invalid HMAC signature: the HMAC key in the settings does not match the key of the webhook in the Customer Area, or it belongs to the other environment.

Webhook answers [rejected] busy, retry later or [rejected] retry later: the cart was being processed by another request at the same moment, or an error occurred while the order was being updated. Adyen retries the webhook automatically. The reason is in the log.

Webhook answers [rejected] invalid payload: the request is not a Standard webhook in JSON. Check the method of the webhook in the Customer Area.

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

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Adyen retries the delivery, and the order is invoiced when a retry reaches the store.

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 is back in the cart with The Adyen payment could not be started: look at the Log field on the settings page (errors are always logged). Check the API key, the merchant account and, in live mode, the live URL prefix. The order of that attempt is cancelled.

A payment was made but the order is On Hold or Canceled: read the order notes. The amount or currency confirmed by Adyen did not match the order, a capture or refund failed, the payment arrived after the order had been cancelled (for example by the Pending Payment Order Lifetime cron), or it is your Order status after payment setting.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice cannot be refunded online; refund it in the Adyen Customer Area.

Refund fails with Adyen credentials for the payment environment are not configured: the payment was made in test or live mode, and the API key of that mode is not set. Enter it and try again. With manual capture in Adyen, only captured payments can be refunded.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_AdyenPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_AdyenPayment to remove the data, then bin/magento module:disable Vibefox_AdyenPayment, delete the folder app/code/Vibefox/AdyenPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The Adyen payment attempts, webhook events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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