---
title: "Adyen Payment"
description: "The Adyen Payment plugin connects your J2Commerce store to the Adyen payment platform."
url: "https://docs.j2commerce.com/v6/payment-methods/payment_adyen"
markdown_url: "https://docs.j2commerce.com/v6/payment-methods/payment_adyen.md"
last_updated: "2026-11-11T13:53:56+00:00"
version: "J2Commerce 6"
breadcrumbs:
  - title: "Home"
    url: "https://docs.j2commerce.com/"
  - title: "J2Commerce 6"
    url: "https://docs.j2commerce.com/v6"
  - title: "Payment Methods"
    url: "https://docs.j2commerce.com/v6/payment-methods"
  - title: "Adyen Payment"
    url: "https://docs.j2commerce.com/v6/payment-methods/payment_adyen"
---

# Adyen Payment

The Adyen Payment plugin connects your J2Commerce store to the **Adyen** payment platform. Adyen is used by thousands of businesses worldwide and accepts credit cards, debit cards, digital wallets (Google Pay, Apple Pay), buy-now-pay-later options (Klarna), and many regional payment methods — all from a single integration.

The checkout experience is powered by **Adyen's Drop-in** component, which loads secure card fields directly on your checkout page. Your customers never leave your site, and card data is handled entirely by Adyen, which means your store qualifies for the simplest level of PCI security compliance (SAQ-A).

The plugin also supports:

- **3D Secure 2 (3DS2)** — the bank-required verification step (sometimes called "Verified by Visa" or "Mastercard Identity Check") is handled automatically
- **Saved cards** — returning customers can check out faster with a saved card on file
- **Subscription renewals** — saved cards can be charged automatically when you use the J2Commerce Subscriptions add-on
- **Manual capture** — authorize first, capture funds only when you are ready to ship
- **Capture, refund, and cancel** actions directly from the J2Commerce order screen

## Requirements

- Joomla 6.x
- J2Commerce 6.x
- PHP 8.3 or later
- An Adyen merchant account (test or live)
- Your store must be accessible over HTTPS

## Get Your Adyen Credentials

![Adyen Customer Area API credential page: Authentication section with Client key tab, a Generate client key button, and Add allowed origins entries (values hidden)](https://docs.j2commerce.com/images/docs/shared/ayden-credentials-3.webp)

Before configuring the plugin, you need a few pieces of information from your Adyen **Customer Area** (the Adyen management portal).

### Test credentials

1. Log in to your Adyen test account at [ca-test.adyen.com](https://ca-test.adyen.com).
2. Go to **Developers** -> **API credentials** and copy your **API key** — this is the server-side secret that lets J2Commerce communicate with Adyen.
3. Copy your **Client key** — this is the browser-safe key that loads the card form on your checkout page.
4. Your **Merchant account** name appears in the top navigation bar of the Customer Area (for example, `MyStoreECOM`).

### Setting up webhooks (required for order updates)

Adyen confirms payment results by sending a notification to your store — called a **webhook**. You must register your store's webhook URL in the Customer Area so Adyen knows where to send those updates.

1. In the Adyen Customer Area, go to **Developers** -> **Webhooks**.
2. Click **Add webhook** -> **Standard webhook**.
3. Set the URL to:

   ```
   https://your-site.com/index.php?option=com_ajax&group=j2commerce&plugin=payment_adyen&format=raw&task=webhook
   ```

   Replace `your-site.com` with your actual domain.
4. Under **Security** -> **HMAC Key**, generate a new HMAC key and copy it. The **HMAC key** (which stands for Hash-based Message Authentication Code) is a shared secret that lets J2Commerce verify that each webhook notification genuinely came from Adyen — not from a third party.
5. Save the webhook and copy the HMAC key value before closing.

### Live credentials

![Adyen Customer Area API credentials list with Create New Credential and Allowed IP Ranges buttons, showing Web Service and Reporting credentials (values hidden)](https://docs.j2commerce.com/images/docs/shared/ayden-credentials-1.webp)

When you are ready to go live, you will also need:

- **Live API key** and **Live client key** — found in **Developers** -> **API credentials** in your live Customer Area account.
- **Live URL prefix** and **Live company name** — found in **Account** -> **API URLs** in the Customer Area. Together these form the host address for your live API requests.

Keep the Customer Area open while you configure the plugin in Joomla.

## Purchase and Download

This plugin is a separate add-on available from the [Adyen Payment](https://www.j2commerce.com/extensions/payment-plugins/adyen-payment). It is not included with the core J2Commerce 6 component.

1. Go to the [J2Commerce website](https://www.j2commerce.com/extensions) and locate **Adyen Payment**.
2. Add it to your cart and complete checkout.
3. Go to **My Downloads** under your account profile and find the plugin.
4. Click **Available Versions** -> **View Files** -> **Download Now** to download the ZIP file.

## Install the Plugin

In the Joomla Administrator, go to **System** -> **Install** -> **Extensions**.

Upload the `payment_adyen.zip` file or use the Install from URL option.

![Install extensions](https://docs.j2commerce.com/images/docs/v4/assets/app%20install1%20%281%29%20%281%29.webp)

## Enable the Plugin

Once installed, you need to enable the plugin. There are two ways to reach it.

**Option A:** Go to the **J2Commerce** icon at the top right corner -> **Setup** -> **Payment Methods**

**Option B:** Go to **Components** on the left sidebar -> **J2Commerce** -> **Dashboard** -> **Setup** -> **Payment Methods**

![Payment Methods list opened via the J2Commerce menu: the J2Commerce button, Setup and Payment Methods highlighted, with 2Checkout listed first](https://docs.j2commerce.com/images/docs/shared/adyen-payment-method.webp)

Search for **Adyen Payment**, click the **X** next to it, and it turns into a green checkmark. The plugin is now enabled and ready for setup.

![Payment Methods list with the enabled Status check outlined on the Adyen Payment row, below 2Checkout, both showing version 6.0.0](https://docs.j2commerce.com/images/docs/shared/adyen-enable.webp)

## Configure the Plugin

Click the **Adyen Payment** title to open its settings.

> **Tip:** Click the **Toggle Inline Help** button at the top of any plugin settings screen to show a description below each field.

![Adyen plugin settings with the Toggle Inline Help button highlighted and the help text Name to display to customers during checkout outlined under Display Name](https://docs.j2commerce.com/images/docs/shared/adyen-toggle.webp)

### Appearance

![Plugins: Adyen Payment, Plugin tab highlighted: Status Enabled, Display Name Pay by Card, Display Image showing the Adyen logo, Access Public](https://docs.j2commerce.com/images/docs/shared/adyen-config1.webp)

**Display Name:** The label shown to customers on the checkout page (for example, "Pay by Card"). Change this to whatever makes sense for your store.

**Display Image:** An optional logo or card-brand image to show next to the payment method name at checkout.

### Integration Mode

![Adyen plugin settings outlined: Integration Mode Sessions Flow (Drop-in) and Capture Mode Automatic Capture (recommended)](https://docs.j2commerce.com/images/docs/shared/adyen-config2.webp)

**Integration Mode:** Controls how the payment is processed behind the scenes.

- **Sessions Flow (Drop-in)** — Adyen handles the entire payment lifecycle, including 3DS2 challenges, inside its Drop-in component. This is the recommended option — it requires the least setup and keeps your store at SAQ-A PCI compliance.
- **Advanced Flow (manual /payments)** — The plugin takes manual control of the API calls. Choose this only if you have a specific technical requirement; for most stores, Sessions Flow is the right choice.

### Capture Mode

**Capture Mode:** Controls when funds are actually collected from the customer's card.

- **Automatic Capture (recommended)** — funds are collected immediately when the payment is authorized. This suits most stores.
- **Manual Capture** — the payment is authorized (the amount is reserved on the card) but funds are not collected until you click **Capture Payment** from the order screen. This is useful when you want to confirm stock availability or review an order before charging the customer.

### Test Mode

**Test Mode:** When turned on, all transactions go to Adyen's test environment — no real money moves.

Enable this during setup and initial testing. When Test Mode is active, a warning banner appears on the J2Commerce dashboard as a reminder. Turn it off only when you are ready to accept real payments.

### Live Credentials

These fields appear when **Test Mode** is turned **off**.

![Adyen live credentials outlined with Test Mode set to Never: API Key, Client Key, Merchant Account (values hidden), Live URL Prefix and Live Company Name](https://docs.j2commerce.com/images/docs/shared/adyen-config3-1.webp)

**API Key:** Your Adyen live API key — a server-side secret, never shared with browsers

**Client Key:** Your Adyen live client key — browser-safe, used by the Drop-in card form

**Merchant Account:** Your Adyen merchant account name (for example, `MyStoreECOM`)

**Live URL Prefix:** The URL prefix from your Adyen Customer Area (for example, `1797ab8e0c-adyen`)

**Live Company Name:** Your Adyen company name from the Customer Area — combined with the prefix to build the live API host

**Webhook HMAC Key:** The HMAC key you generated in the Adyen webhook setup — used to verify incoming notifications

### Sandbox Credentials

![Adyen sandbox credentials outlined with Test Mode Yes: Webhook Notification URL with Copy button, Sandbox API and Client Keys (hidden), HMAC Key, Fallback Country United States](https://docs.j2commerce.com/images/docs/shared/adyen-config3.webp)

These fields appear when **Test Mode** is turned **on**. They work identically to the live fields but connect to the Adyen test environment.

**Sandbox API Key:** Your Adyen test API key

**Sandbox Client Key:** Your Adyen test client key

**Sandbox Merchant Account:** Your Adyen test merchant account name

**Sandbox Webhook HMAC Key:** The HMAC key for your test webhook endpoint

### Fallback Country Code

**Fallback Country Code:** The two-letter country code (for example, `US`, `GB`, `DE`) used to filter available payment methods when the customer's billing country cannot be determined from the order. Adyen uses the country to decide which payment methods are shown. This defaults to the United States (US).

### Saved Cards

![Adyen settings outlined: Allow Saved Cards Yes, Card Save Mode Ask for Consent, Visa, Mastercard, Amex and Discover accepted, Template Style Bootstrap5](https://docs.j2commerce.com/images/docs/shared/adyen-config4.webp)

**Allow Saved Cards:** When turned on, logged-in customers can save their card at checkout for faster purchases in the future. Saved cards can also be used for automatic subscription renewals.

**Card Save Mode (Sessions):** Controls how card saving is offered when Integration Mode is set to Sessions Flow and Allow Saved Cards is enabled.

- **Ask for Consent (recommended)** — a checkbox appears at checkout; the customer decides whether to save their card.
- **Always Save** — the card is saved automatically without asking.
- **Never Save** — saving is disabled even though Allow Saved Cards is on.

### Accepted Card Types

**Accepted Card Types:** Choose which card brand icons are displayed above the payment form. Available options: Visa, Mastercard, American Express, Discover, Maestro, Klarna, Google Pay, Apple Pay, PayPal.

This controls icon display only — Adyen determines which payment methods are actually available based on your merchant account configuration.

### Order Statuses

![Adyen order status settings outlined: Order Status Confirmed, Failed Payment Status Failed, Change Status on Refund Yes with Cancelled, Change Status on Cancel Yes with Refunded](https://docs.j2commerce.com/images/docs/shared/adyen-config5.webp)

These settings control which J2Commerce order status is applied when specific payment events occur.

**Order Status (Payment Success):** Status applied when Adyen confirms a successful payment via webhook

**Failed Payment Status:** Status applied when Adyen reports a failed or declined payment

**Authorized Status:** Status applied when payment is authorized but not yet captured — only shown when Capture Mode is Manual Capture

**Change Status on Refund:** When turned on, it automatically updates the order status after a refund is processed

**Refund Order Status:** The status to apply after a refund — only shown when Change Status on Refund is enabled

**Change Status on Cancel:** When turned on, it automatically updates the order status after a payment is canceled

**Cancel Order Status:** The status to apply after a cancellation — only shown when Change Status on Cancel is enabled

> **Tip:** If the status you want is not listed in a dropdown, create a new one first by going to **J2Commerce** -> **Setup** -> **Order Statuses**.

![J2Commerce Order Statuses list with the J2Commerce menu open at the right, highlighting Setup and its Order Statuses item](https://docs.j2commerce.com/images/docs/shared/shipstation-order-status2-1.webp)

### Surcharge

![Adyen surcharge settings outlined: empty Surcharge Name, Surcharge Percent and Surcharge Fixed fields, and Surcharge Tax Class set to TN Tax](https://docs.j2commerce.com/images/docs/shared/adyen-config6.webp)

Add an optional handling fee when a customer chooses Adyen.

**Surcharge Name:** The label shown to the customer (for example, "Card processing fee")

**Surcharge Percent:** A percentage of the order total added as a fee (for example, `1.5` for 1.5%)

**Surcharge Fixed:** A fixed amount added regardless of order size

**Surcharge Tax Class:** A tax profile to apply to the surcharge — leave blank if no tax applies

Leave both Surcharge Percent and Surcharge Fixed empty to charge no surcharge.

### GeoZone and Order Value Restrictions

![Adyen restriction settings outlined: Geo Zone Restriction set to Tennessee, with empty Minimum Subtotal and Maximum Subtotal fields](https://docs.j2commerce.com/images/docs/shared/adyen-config7.webp)

**Geozone Restriction:** Limit Adyen to customers in a specific geozone — leave blank to allow all locations

**Minimum Order Subtotal:** Hide Adyen as a payment option when the cart subtotal is below this amount

**Maximum Order Subtotal:** Hide Adyen when the cart subtotal is above this amount

### Custom HTML Snippets

![Adyen custom text settings outlined: Thank You Article picker and empty On Selection, Before Payment, After Payment, On Error and Order Cancelled Message text areas](https://docs.j2commerce.com/images/docs/shared/adyen-config8.webp)

These optional fields let you inject custom text or HTML at different points in the payment flow.

**Thank-You Article:** Optional Joomla article shown on the order confirmation page after successful payment

**On Selection Text:** Displayed when the customer selects Adyen as their payment method

**Before Payment Text:** Displayed just above the card form, before the customer enters card details

**After Payment Text:** Displayed on the confirmation page after a successful payment

**On Error Text:** Displayed when a payment attempt fails

**Order Canceled Message:** Displayed when the customer cancels or navigates away

### Dashboard Icon

![Adyen plugin settings outlined: Show Dashboard Icon and Debug Mode toggles both set to Never](https://docs.j2commerce.com/images/docs/shared/adyen-config9.webp)

**Show Dashboard Icon:** Add a quick-access shortcut for this plugin to the J2Commerce dashboard.

**Dashboard Icon Label:** The label for the shortcut icon. Defaults to "Adyen Payment" if left blank.

### Debug Mode

**Debug Mode:** Records detailed API request and response data in the Joomla log.

Only enable this when diagnosing a specific problem. Disable it on live sites — debug logs can contain sensitive payment details.

## How Checkout Works for Customers

1. The customer adds items to their cart and proceeds to checkout.
2. On the payment step, the Adyen Drop-in card form loads directly on the page — the card number, expiry date, and CVV fields appear inside secure iframes hosted by Adyen.
3. If the customer is logged in and has saved cards on file (and **Allow Saved Cards** is enabled), they see a list of saved cards and can select one or choose to use a new card.
4. If card saving is allowed, a checkbox lets the customer save the new card for future orders.
5. The customer selects their payment method and enters their details.
6. If the customer's bank requires a 3DS2 verification step (the extra security check sometimes called "Verified by Visa" or "Mastercard Identity Check"), an additional screen appears inside the payment form — the customer completes it and is returned to checkout.
7. On success, the customer sees the order confirmation page.

Frontend Checkout View

![Storefront checkout Payment Method list with Pay by Card (Adyen) selected and outlined at the bottom, above the Continue button](https://docs.j2commerce.com/images/docs/shared/adyen-frontend.webp)

## Webhooks

Adyen sends real-time notifications to your store when payment events occur — such as a payment being authorized, captured, refused, canceled, or refunded. The plugin verifies each notification using HMAC-SHA256 (the **Webhook HMAC Key** you configured) so only genuine Adyen events update your orders.

Your webhook URL to register in the Adyen Customer Area is:

```
https://your-site.com/index.php?option=com_ajax&group=j2commerce&plugin=payment_adyen&format=raw&task=webhook
```

Replace `your-site.com` with your actual domain. **The site must be publicly reachable over HTTPS** — webhooks cannot reach a site running on localhost.

Key webhook events the plugin handles:

| Adyen Event | What Happens in J2Commerce |
| --- | --- |
| AUTHORIZATION (success) | Order status updates to Authorized Status (Manual Capture mode) or Payment Status (Automatic Capture) |
| CAPTURE | Order status updates to Payment Status |
| AUTHORIZATION (failure) | Order status updates to Failed Payment Status |
| REFUND | Refund recorded; order status updated if Change Status on Refund is enabled |
| CANCELLATION | Cancellation recorded; order status updated if Change Status on Cancel is enabled |

## Managing Payments from the Order Screen

After an order is paid, you can take follow-up actions directly from the J2Commerce order detail page.

Go to **J2Commerce** -> **Sales** -> **Orders** -> click the order number to open it. The Adyen action buttons appear in the payment section.

### Capture a Payment (Manual Capture mode only)

![Order Details payment section for Adyen Payment with the Capture Payment button outlined beside Cancel Payment and View Details, above Standard Shipping](https://docs.j2commerce.com/images/docs/shared/adyen-payment-order-page-manual-capture.webp)

If you set **Capture Mode** to **Manual Capture**, payments are authorized but not collected. When you are ready to charge the customer:

1. Open the order in **J2Commerce -> Sales ->** **Orders**.
2. Click **Capture Payment** and confirm the prompt.
3. The funds are collected from the customer's card. The order status updates when Adyen confirms the capture via webhook.

### Cancel a Payment

![Order Details payment section for Adyen Payment with the Cancel Payment button outlined beside Capture Payment and View Details, above Standard Shipping](https://docs.j2commerce.com/images/docs/shared/adyen-payment-order-page-manual-cancel.webp)

A cancellation releases an authorized payment before it has been captured. Once a payment has been captured, use **Issue Refund** instead.

1. Open the order.
2. Click **Cancel Payment** and confirm the prompt.
3. The authorization is released — the customer is not charged and any hold on their card is removed.

> **Info:** If the **Cancel Payment** button is not visible, the payment has already been captured. Use **Issue Refund** in that case.

### Issue a Refund

![Order Details payment section for Adyen Payment with the Issue Refund button outlined, above a Free Shipping row](https://docs.j2commerce.com/images/docs/shared/adyen-refund.webp)

You can refund a captured payment in full or in part.

1. Open the order.
2. Click **Issue Refund**.
3. Choose **Full refund** to return the entire amount, or enter a smaller amount for a partial refund (up to the maximum refundable amount shown).
4. Click **Process Refund** to confirm.

The refund is submitted to Adyen. Adyen processes refunds asynchronously — the customer's card is credited within a few business days. If **Change Status on Refund** is enabled, the order status updates automatically when Adyen confirms the refund.

## Testing Payments

Always test in sandbox mode before going live.

> **Tip:** To get the **Test credit card number**, go to [Test card numbers | Adyen Docs](https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers). Each number is different based on what country you are from.

1. Enable **Test Mode** in the plugin settings and enter your Adyen sandbox credentials (sandbox API key, sandbox client key, sandbox merchant account, and sandbox HMAC key).
2. Place a test order on your storefront.
3. At the payment step, enter a test card number. Adyen provides test card numbers in the Customer Area under **Developers** -> **Test cards** on the Adyen website.
4. Complete checkout and confirm the order appears in **J2Commerce** -> **Sales** -> **Orders** with the correct status.
5. Test a refund from the order screen to confirm it processes without errors.
6. Check the Joomla log under **System** **->** **Logs** for any errors — enable **Debug Mode** temporarily if needed.
7. When everything is working, turn off **Test Mode** and replace the sandbox credentials with your live credentials.

> **Warning:** Remember to turn off **Test Mode** before accepting real orders. A warning banner on the J2Commerce dashboard will remind you if Test Mode is still active.

## Troubleshooting

### The payment form does not load at checkout

**Cause:** The client key is missing or incorrect, or the plugin is not enabled.

**Solution:**

1. Go to **J2Commerce** -> **Setup** -> **Payment Methods** and verify Adyen shows a green enabled indicator.
2. Open the plugin settings and confirm the **Client Key** field (or **Sandbox Client Key** if Test Mode is on) is filled in.
3. Make sure the client key matches the correct environment — test and live client keys are different.
4. Clear the Joomla cache: **System** -> **Clear Cache** -> **Delete All**.

### Orders are stuck in a pending status after payment

**Cause:** Adyen webhooks are not being received, or the HMAC key is incorrect.

**Solution:**

1. Confirm your webhook URL is registered in the Adyen Customer Area under **Developers** -> **Webhooks** and that the URL points to your store.
2. Open the plugin settings and verify the **Webhook HMAC Key** (or **Sandbox Webhook HMAC Key**) matches the value in the Adyen Customer Area exactly.
3. Make sure your store's URL is publicly reachable over HTTPS. Adyen cannot deliver webhooks to a site on localhost or a private network.
4. Enable **Debug Mode** in the plugin settings, attempt a test payment, then check **System** -> **Logs** for any webhook-related errors.

### The Capture / Refund / Cancel buttons do not appear on the order

**Cause:** The order was not paid through Adyen, or no transaction data was recorded.

**Solution:**

1. Confirm the order's payment method is Adyen (visible in the payment section of the order detail view).
2. The buttons only appear when an Adyen PSP reference (a transaction identifier) is stored on the order. If the checkout was interrupted before the payment completed, no transaction data is saved.
3. Enable **Debug Mode** and re-test a full checkout to confirm transaction data is being stored correctly.

### Card declined error at checkout

**Cause:** The card details are incorrect, the card is not authorized for online transactions, or the issuing bank declined the charge.

**Solution:**

1. Ask the customer to double-check their card number, expiry date, and CVV.
2. Ask them to try a different card or contact their bank.
3. In sandbox mode, verify you are using a valid Adyen test card number from the Customer Area under **Developers** -> **Test cards**.

### Missing credentials warning on the J2Commerce dashboard

**Cause:** The API Key or Merchant Account field is empty.

**Solution:**

1. Go to **J2Commerce** -> **Setup** -> **Payment Methods** -> **Adyen Payment**.
2. Fill in the **API Key** and **Merchant Account** fields for whichever environment (live or sandbox) is currently active.
3. Click **Save** to apply the changes.

### Refund or capture fails with an error

**Cause:** The payment may not be in the correct state. You can only capture an authorized payment, and you can only cancel a payment that has not yet been captured.

**Solution:**

1. Check the order's payment state. If the payment has already been captured, use **Issue Refund** instead of **Cancel Payment**.
2. Enable **Debug Mode** and retry the action, then review **System** -> **Logs** for the specific error returned by Adyen.
3. If the problem persists, contact Adyen support with the PSP reference from the order.