@spree/docs 0.1.28 → 0.1.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Connect Adyen payments to Spree Commerce"
|
|
3
|
-
sidebarTitle: Adyen
|
|
3
|
+
sidebarTitle: "Adyen"
|
|
4
4
|
description: "Learn how to set up and manage Spree's native Adyen integration."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
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.
|
|
8
8
|
|
|
9
|
-
> **WARNING:** Adyen integration is currently in **private beta**. [Please contact us](https://spreecommerce.org/contact) to get access to the Adyen integration for your Spree store.
|
|
10
|
-
|
|
11
9
|
## Installation
|
|
12
10
|
|
|
13
11
|
Before you can enable Adyen, it must be installed. To do so, you need to run the following command:
|
|
@@ -22,28 +20,73 @@ After that, you need to make sure to restart the server.
|
|
|
22
20
|
|
|
23
21
|
Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.
|
|
24
22
|
|
|
25
|
-
|
|
26
24
|
|
|
27
25
|
Find Adyen under Available Payment Methods and click **Add**.
|
|
28
26
|
|
|
29
27
|
This will redirect you to the Adyen setup form.
|
|
30
28
|
|
|
31
|
-
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
> **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.
|
|
34
|
+
|
|
35
|
+
The following steps walk through generating the credentials you need from inside the [Adyen Customer Area](https://ca-live.adyen.com/).
|
|
36
|
+
|
|
37
|
+
### 1. Select your Merchant Account
|
|
38
|
+
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
All subsequent steps (generating API credentials, retrieving the Live URL Prefix) happen inside this merchant account.
|
|
42
|
+
|
|
43
|
+
### 2. Generate API credentials
|
|
44
|
+
|
|
45
|
+
Inside the merchant account you selected, Adyen groups your Client Key and API Key under a single "API credential" record.
|
|
46
|
+
|
|
47
|
+
1. Navigate to **Developers → API credentials**.
|
|
48
|
+
2. Click **Create new credential** and select **Web service user**.
|
|
49
|
+
3. On the next page, go to **Server Settings** and click **Generate API key**.
|
|
50
|
+
4. Scroll down to **Client Settings** and click **Generate client key**.
|
|
51
|
+
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.
|
|
52
|
+
6. Click **Save changes**.
|
|
53
|
+
|
|
54
|
+
> **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.
|
|
55
|
+
|
|
56
|
+
### 3. Get your Live URL Prefix (live only)
|
|
57
|
+
|
|
58
|
+
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**.
|
|
59
|
+
|
|
60
|
+
This field is not needed for test mode.
|
|
61
|
+
|
|
62
|
+
### 4. Paste credentials into Spree and create the payment method
|
|
63
|
+
|
|
64
|
+
Back in the Spree admin form, paste each value into its matching field:
|
|
65
|
+
|
|
66
|
+
1. **API Key** — from step 2 (Server Settings)
|
|
67
|
+
2. **Client Key** — from step 2 (Client Settings)
|
|
68
|
+
3. **Live URL Prefix** — from step 3 (required for live sites only)
|
|
69
|
+
|
|
70
|
+
Leave the **Merchant Account**, **Hmac Key**, and **Webhook** fields blank — Spree populates them automatically once the payment method is created.
|
|
32
71
|
|
|
33
|
-
|
|
34
|
-
1. Make sure to be logged into your Adyen Merchant Account
|
|
35
|
-
2. Navigate to **Developers → API credentials**
|
|
36
|
-
3. Configure a new **API credential**
|
|
37
|
-
4. Copy the generated **API Key** (you won't be able to see it later)
|
|
38
|
-
5. Click **Save changes**
|
|
39
|
-
6. Paste the **API Key** into its respective field in the Adyen setup form in Spree
|
|
40
|
-
7. Click **Create** to enable Adyen as a payment method on your store
|
|
72
|
+
Tick **Test Mode** if you're using test credentials, then click **Create** to enable Adyen as a payment method on your store.
|
|
41
73
|
|
|
42
|
-
|
|
43
75
|
|
|
44
|
-
|
|
76
|
+
## Storefront Configuration
|
|
45
77
|
|
|
46
|
-
|
|
78
|
+
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:
|
|
79
|
+
|
|
80
|
+
- **`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.
|
|
81
|
+
- **`NEXT_PUBLIC_ADYEN_ENVIRONMENT`** — Either `test` or `live`. Determines which Adyen environment the Drop-in SDK connects to. Defaults to `test` if unset.
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
> **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.
|
|
86
|
+
|
|
87
|
+
## Additional Settings
|
|
88
|
+
|
|
89
|
+
|
|
47
90
|
|
|
48
91
|
You can optionally configure the following settings for your Adyen payment method:
|
|
49
92
|
|
|
@@ -55,9 +98,41 @@ You can optionally configure the following settings for your Adyen payment metho
|
|
|
55
98
|
- **Auto Capture**: Decide whether payments should be automatically captured at the time of authorization (recommended), or manually captured later.
|
|
56
99
|
- **Active Status**: Enable or disable the payment method. Inactive methods are hidden from checkout but not removed.
|
|
57
100
|
|
|
58
|
-
|
|
101
|
+
## Test Mode
|
|
102
|
+
|
|
103
|
+
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:
|
|
104
|
+
|
|
105
|
+
1. Tick the **Test Mode** checkbox in the Adyen payment method settings in Spree.
|
|
106
|
+
2. Switch your Adyen Customer Area to **Test** mode using the environment switcher in the top-right.
|
|
107
|
+
3. Generate separate test credentials (API Key, Client Key) from your test environment following the same steps above.
|
|
108
|
+
4. Paste the test credentials into Spree. The **Live URL Prefix** field is not used in test mode.
|
|
109
|
+
|
|
110
|
+
See [Testing Adyen payments](#testing-adyen-payments) below for a walkthrough of simulating transactions with Adyen's test card numbers.
|
|
111
|
+
|
|
112
|
+
## Testing Adyen payments
|
|
113
|
+
|
|
114
|
+
Once Test Mode is set up, you can simulate real payments using Adyen's published test card numbers.
|
|
115
|
+
|
|
116
|
+
### 1. Use Adyen's test cards
|
|
117
|
+
|
|
118
|
+
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:
|
|
119
|
+
|
|
120
|
+
- **Successful payments** — e.g. Visa `4111 1111 1111 1111`
|
|
121
|
+
- **3D Secure authentication flows**
|
|
122
|
+
- **Declined payments** — specific test cards trigger different decline reasons
|
|
123
|
+
- **Refunds and chargebacks**
|
|
124
|
+
|
|
125
|
+
For CVC and expiry, any valid-format values work (e.g. `737` CVC, a future expiry date).
|
|
126
|
+
|
|
127
|
+
### 2. View test transactions in Adyen
|
|
128
|
+
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
### Common Issues
|
|
59
132
|
|
|
60
|
-
|
|
133
|
+
- **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).
|
|
134
|
+
- **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.
|
|
135
|
+
- **Wrong environment**: credentials are environment-specific. Test-mode credentials won't work against the Live URL Prefix, and vice versa.
|
|
61
136
|
|
|
62
137
|
## Features
|
|
63
138
|
|
|
@@ -51,7 +51,7 @@ To generate a Webhook ID:
|
|
|
51
51
|
2. Scroll down to the **Webhooks** section (Live or Sandbox depending on the environment).
|
|
52
52
|
3. Click **Add Webhook**.
|
|
53
53
|
4. Enter your Spree webhook URL: `https://your-store-url.com/api/v3/webhooks/payments/[payment_method_id]`
|
|
54
|
-
- The `payment_method_id` is the
|
|
54
|
+
- The `payment_method_id` is the prefixed ID visible in the URL when editing your PayPal payment method in Spree (e.g. `/payment_methods/pm_1example23/edit`).
|
|
55
55
|
5. Select the event types to subscribe to. At minimum:
|
|
56
56
|
- Checkout order approved
|
|
57
57
|
- Checkout order completed
|