Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

9.6 KB
Raw Blame
---
title: "Connect Adyen payments to Spree Commerce"
sidebarTitle: "Adyen"
description: "Set up Spree's native Adyen integration to accept global payments across multiple methods, with built-in fraud protection and a seamless checkout experience."
---

Adyen is a global payment platform that enables businesses to accept payments across multiple channels and markets. It supports a wide range of payment methods, provides advanced fraud protection, and offers seamless checkout experiences for customers worldwide.

## Installation

Before you can enable Adyen, it must be installed. To do so, you need to run the following command:

<CodeGroup>

```bash Spree CLI (Docker)
spree add adyen
```

```bash Without Spree CLI
bundle add spree_adyen && bin/rails g spree_adyen:install && bin/rails db:migrate
```

</CodeGroup>

The Spree CLI also runs the migrations and restarts the server for you. Without it, restart the server yourself after the commands finish.

## Connect Adyen

Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.

![Adyen listed under Available Payment Methods on the Payments settings page](/docs/images/integrations/adyen/1-payment-method-list.png)

Find Adyen under Available Payment Methods and click **Add**.

This will redirect you to the Adyen setup form.

![The Adyen setup form with fields for Merchant Account, API Key, Client Key, HMAC Key, Webhook, and Live URL Prefix](/docs/images/integrations/adyen/2-setup-form.png)

You only need to provide the **API Key**, **Client Key**, and (for live payments) **Live URL Prefix** to get started. Spree automatically populates the **Merchant Account**, **Hmac Key**, and **Webhook** fields after you create the payment method.

<Warning>Don't enter values into the **Merchant Account**, **Hmac Key**, or **Webhook** fields manually. Spree fills these in automatically after creation — entering values yourself can block the auto-population process.</Warning>

The following steps walk through generating the credentials you need from inside the [Adyen Customer Area](https://ca-live.adyen.com/).

### 1. Select your Merchant Account

Log into the [Adyen Customer Area](https://ca-live.adyen.com/) and select the **merchant account** you're configuring. A company account can contain multiple merchant accounts — if so, pick the one tied to the store you're setting up.

All subsequent steps (generating API credentials, retrieving the Live URL Prefix) happen inside this merchant account.

### 2. Generate API credentials

Inside the merchant account you selected, Adyen groups your Client Key and API Key under a single "API credential" record.

1. Navigate to **Developers → API credentials**.
2. Click **Create new credential** and select **Web service user**.
3. On the next page, go to **Server Settings** and click **Generate API key**.
4. Scroll down to **Client Settings** and click **Generate client key**.
5. Still in **Client Settings**, add your Spree storefront URL under **Allowed origins** (e.g., `https://your-store.com`). Without this, the Drop-in checkout component won't load on your storefront.
6. Click **Save changes**.

<Warning>Copy your API Key and Client Key as soon as they're generated and store them somewhere safe. Adyen displays the API Key **only once** — if you navigate away without copying it, you'll need to generate a new credential. The process is quick, but it's an avoidable annoyance.</Warning>

### 3. Get your Live URL Prefix (live only)

If you're configuring Adyen for live (non-test) payments, you'll need your unique API URL prefix. In the Adyen Customer Area, navigate to **Developers → API URLs** and copy the value under **Prefix**.

This field is not needed for test mode.

### 4. Paste credentials into Spree and create the payment method

Back in the Spree admin form, paste each value into its matching field:

1. **API Key** — from step 2 (Server Settings)
2. **Client Key** — from step 2 (Client Settings)
3. **Live URL Prefix** — from step 3 (required for live sites only)

Leave the **Merchant Account**, **Hmac Key**, and **Webhook** fields blank — Spree populates them automatically once the payment method is created.

Tick **Test Mode** if you're using test credentials, then click **Create** to enable Adyen as a payment method on your store.

![Adyen enabled as a payment method in Spree](/docs/images/integrations/adyen/3-adyen-enabled.png)

## Storefront Configuration

For the Adyen Drop-in SDK to initialize on the Next.js storefront, set the following environment variables in your storefront's hosting platform or `.env` file:

- **`NEXT_PUBLIC_ADYEN_CLIENT_KEY`** — Your Adyen **Client Key** (test or live, matching the environment you're running). This is the same value you pasted into the Spree admin.
- **`NEXT_PUBLIC_ADYEN_ENVIRONMENT`** — Either `test` or `live`. Determines which Adyen environment the Drop-in SDK connects to. Defaults to `test` if unset.

The `NEXT_PUBLIC_` prefix makes the variables available to client-side code so the Adyen JS SDK can initialize in the browser. The Client Key is safe to expose publicly.

<Note>If `NEXT_PUBLIC_ADYEN_CLIENT_KEY` isn't set, the Adyen payment option won't render on the storefront even if Adyen is configured in the Spree admin.</Note>

## Additional Settings

![The Adyen Additional Settings panel after the payment method is created](/docs/images/integrations/adyen/4-additional-settings.png)

You can optionally configure the following settings for your Adyen payment method:

- **Name**: Customize the display name shown for this payment method on the storefront.
- **Display**: Choose where Adyen should be available:
  - Storefront only
  - Admin panel only
  - Both (recommended)
- **Auto Capture**: Decide whether payments should be automatically captured at the time of authorization (recommended), or manually captured later.
- **Active Status**: Enable or disable the payment method. Inactive methods are hidden from checkout but not removed.

## Test Mode

If you'd like to test your checkout flow without processing real payments, Adyen's test environment is a safe and effective way to simulate transactions. To enable it:

1. Tick the **Test Mode** checkbox in the Adyen payment method settings in Spree.
2. Switch your Adyen Customer Area to **Test** mode using the environment switcher in the top-right.
3. Generate separate test credentials (API Key, Client Key) from your test environment following the same steps above.
4. Paste the test credentials into Spree. The **Live URL Prefix** field is not used in test mode.

See [Testing Adyen payments](#testing-adyen-payments) below for a walkthrough of simulating transactions with Adyen's test card numbers.

## Testing Adyen payments

Once Test Mode is set up, you can simulate real payments using Adyen's published test card numbers.

### 1. Use Adyen's test cards

At checkout on your Spree store, Adyen's Drop-in component will present payment options. Use one of Adyen's [official test card numbers](https://docs.adyen.com/development-resources/testing/test-card-numbers/) to simulate:

- **Successful payments** — e.g. Visa `4111 1111 1111 1111`
- **3D Secure authentication flows**
- **Declined payments** — specific test cards trigger different decline reasons
- **Refunds and chargebacks**

For CVC and expiry, any valid-format values work (e.g. `737` CVC, a future expiry date).

### 2. View test transactions in Adyen

To see transactions from Adyen's side, log in to the Adyen Customer Area with **Test** selected in the environment switcher. Navigate to **Transactions → All transactions** to view captures, authorizations, refunds, and webhook delivery attempts.

### Common Issues

- **Drop-in not loading on the storefront**: make sure your storefront URL is in the **Allowed origins** list on the Adyen API credential (Client Settings).
- **Auto-populated fields not filling in**: if the **Merchant Account**, **Hmac Key**, or **Webhook** fields stay empty after creating the payment method, check that you didn't enter values into them manually before saving — any pre-filled input can block the auto-population process. Delete the payment method and re-create it with only the API Key, Client Key, and (if live) Live URL Prefix filled in.
- **Wrong environment**: credentials are environment-specific. Test-mode credentials won't work against the Live URL Prefix, and vice versa.

## Features

Spree's native Adyen integration supports a comprehensive range of features and payment methods to help you offer a fast, secure, and flexible checkout experience:

- Support for 3D Secure and other security standards
- Support for off-session payments
- Support for Storefront API integration (see the API docs [here](/api-reference/storefront/adyen/create-an-adyen-payment-session))
- Accept payments in over 150 currencies
- Accept Credit Cards, Debit Cards, and Digital Wallets
- Accept Buy Now, Pay Later (BNPL) payments
- Accept Bank transfers and Direct Debit
- Accept Local payment methods (iDEAL, SOFORT, Bancontact, etc.)
- Accept Mobile payments (Apple Pay, Google Pay, Samsung Pay)
- Accept Cryptocurrency payments
- Advanced fraud protection and risk management
- Real-time payment status updates
- Comprehensive reporting and analytics

### Storefront Display

Spree's Adyen integration enhances the customer experience with dynamic, context-aware payment options across the storefront:

- Dynamic payment method selection based on customer location
- Real-time payment method availability
- Seamless checkout experience with Adyen's Drop-in component
- Support for one-click payments and saved payment methods
- Mobile-optimized payment flows

Feel free to [reach out](https://spreecommerce.org/contact) to learn more.