Payment Gateways: Europe

This page covers the setup of the European gateways: Pay., Buckaroo, Adyen, Viva.com, Worldline Saferpay, Worldpay, Opayo and GoCardless. For how these gateways work in general, and the general go-live checklist, see Payment Gateways.

Pay.

For merchants in the Netherlands and Belgium. The customer picks iDEAL, Bancontact, cards, PayPal or another method enabled on your sales location, on the payment page hosted by Pay. The currency is not limited by the module: any currency your Pay. account supports.

Available from v3.13.0

payment_gateway="pay_nl"

Setup

1. Log in to my.pay.nl.
2. Go to Merchant → API tokens and copy the token code (AT-xxxx-xxxx) and its API token.
3. Go to Settings → Sales locations and copy the code of the sales location you use (SL-xxxx-xxxx) and its secret.
4. Enable the payment methods you want to offer on that sales location.

Field	Description
Debug mode	On creates the payments as test payments (integration.test), off creates live payments
Token code (AT-xxxx-xxxx)	The token code from Merchant → API tokens
API token	The API token that belongs to the token code
Sales location / Service ID (SL-xxxx-xxxx)	The code of your sales location from Settings → Sales locations
Sales location secret	The secret of that sales location. Used to verify exchange calls that are signed with the sales location key

Pay. uses the same credentials for test and live. Debug mode only decides whether a payment is created as a test payment. See Use our sandbox at Pay.

Webhook

No setup needed. The module sends the exchange (notify) URL with every payment, so the CP does not show it.

Pay. can sign exchange calls with HMAC (signing). The Signature-KeyId header of the call tells which key was used: the token code (then the API token is the secret) or the sales location code (then the Sales location secret is the secret). The module accepts both, so fill in both fields.

• A signed call with an invalid signature is refused, and exchange signature verification failed is logged.
• An unsigned (legacy) call is accepted, but only as a trigger: the module always fetches the order status from the Pay. API itself.

How the payment works

• On checkout, the module creates an order at Pay. and sends the customer to the Pay. payment page.
• When the customer returns, and on every exchange call, the module looks up the order status at Pay. by its order id.
• Paid makes the order complete. Authorized, partly captured, "verify" (flagged for a manual check) and "paid, check amount" make the order pending.
• Cancelled orders become cancelled, expired orders expired, failed or denied payments failed.
• Refunds and chargebacks done at Pay. are applied when Pay. sends an exchange call for them.
• Refunds from the CP refund the full order amount via the Pay. API.

Limitations

• The description on the bank statement is Order #<order id>, cut to 32 characters.

Test checklist

• [ ] Exchange calls for orders arrive and verify: the Store log shows [NotifyEvent] lines and no exchange signature verification failed (or webhook verification failed) error.
• [ ] Check which key signs the exchange calls of your account (sales location secret or API token), and that the matching field is filled in. If the calls arrive unsigned, the log says unsigned exchange call received.
• [ ] The order status lookup by order id works: after paying, the order becomes complete on return, even before the exchange call arrives.
• [ ] A refund from the CP works for these orders and shows up in the Pay. dashboard.
• [ ] Use the test options in Use our sandbox to simulate a paid, cancelled and failed payment.

Buckaroo

For merchants in the Netherlands and Belgium. The customer picks iDEAL, Bancontact, cards, PayPal, Apple Pay, bank transfer or another enabled method on the checkout page hosted by Buckaroo. The currency is not limited by the module: any currency your Buckaroo account supports.

Available from v3.13.0

payment_gateway="buckaroo"

Setup

1. Log in to Buckaroo Plaza.
2. Go to My Buckaroo → Websites and copy the website key.
3. Go to Configuration → Security → Secret Key and copy (or set) the secret key.
4. Go to Configuration → Websites → Push settings and set the push content type to JSON. The module only reads JSON pushes.
5. For test payments, enable test transactions for the website key.

Field	Description
Debug mode	On uses Buckaroo's test environment (testcheckout.buckaroo.nl), off uses the live environment
Available payment methods	The methods the customer can choose from. Each method must also be activated on your Buckaroo account. Leave empty to offer all active methods
Website Key	From My Buckaroo → Websites
Secret Key	From Configuration → Security → Secret Key

Webhook

The module sends the push URL with every payment, so you do not have to enter it in Plaza. The CP shows the notify URL for reference. Only the push content type must be set to JSON (see Setup).

Pushes are verified with the HMAC Authorization header, using the website key, the secret key and the push URL. A push that does not verify is refused and webhook verification failed is logged. Without a secret key, pushes are accepted without verification and an error is logged.

Pushes about refunds are ignored; the payment itself is what counts.

How the payment works

• On checkout, the module creates a transaction without a payment method. Buckaroo then shows its hosted checkout page, where the customer chooses a method.
• The customer may end up paying in another transaction than the one created first (for example after changing the method). Its transaction key is read from the return and the push, and used for the status and for refunds, but only when that transaction belongs to this order and covers the full order amount in the order currency.
• Success makes the order complete. Pending processing, on hold and pending approval make it pending. Failed, rejected and validation or technical errors make it failed. Cancelled by the customer or merchant makes it cancelled.
• When the customer cancels, or the payment is rejected or fails, the customer returns to the checkout.
• Refunds from the CP refund the full order amount, with the same payment method as the payment.

Limitations

• Split payments, for example a gift card that covers part of the order, do not complete the order. A transaction for less than the order total is ignored.

Test checklist

• [ ] On checkout without a preselected method, Buckaroo's hosted page is shown and you can choose the payment method there.
• [ ] The push content type is set to JSON in Plaza.
• [ ] Pushes verify with the push URL: the log shows [NotifyEvent] lines and no webhook verification failed.
• [ ] Pay with a different method than the one you first picked, so the paid transaction key differs from the created one. The order becomes complete, and a refund from the CP still works.
• [ ] A split or partial payment (for example a gift card for part of the amount) does not complete the order.
• [ ] Use the test data per payment method from Test transactions.

Adyen

For merchants in the Netherlands, the EU and worldwide. The module uses Adyen Pay by Link: the customer pays on Adyen's hosted payment page, with iDEAL, Bancontact, cards, PayPal, Apple Pay, Google Pay, Klarna, SEPA Direct Debit or another method enabled on your merchant account. The currency is not limited by the module: any currency your Adyen account supports.

Available from v3.13.0

payment_gateway="adyen"

Setup

1. Log in to the Customer Area: ca-test.adyen.com for test, ca-live.adyen.com for live.
2. Go to Developers → API credentials and create an API key with the Checkout webservice role.
3. For live, go to Developers → API URLs in the live Customer Area and copy the Prefix. Without it, live payments do not work.
4. Add the webhook (see Webhook below).

Field	Description
Debug mode	On uses the Adyen test environment and the test keys, off uses the live environment and the live keys
Merchant Account	The merchant account name, for example YourCompanyECOM
Available payment methods	The methods offered on the payment page. Each method must also be activated on your Adyen account. Leave empty to offer all active methods
Test API Key	The API key from the test Customer Area
Test Webhook HMAC Key	The HMAC key of the webhook in the test Customer Area
Live API Key	The API key from the live Customer Area
Live Webhook HMAC Key	The HMAC key of the webhook in the live Customer Area
Live URL prefix	From Developers → API URLs → Prefix in the live Customer Area, for example 1797a841fbb37ca7-AdyenDemo. Required for live

The billing country of the order is sent to Adyen; it decides which methods are shown.

Webhook

The CP shows the notify URL. In the Customer Area, go to Developers → Webhooks and add a Standard webhook with that URL, in JSON format, with the AUTHORISATION event. Generate its HMAC key and copy it into the matching Webhook HMAC Key field.

The webhook is essential for Adyen: the pspReference of the payment, which refunds need, is only sent in the AUTHORISATION webhook. Without it, the order can still become complete (the status comes from the payment link), but it cannot be refunded from the CP.

A webhook with an invalid HMAC signature is refused and webhook verification failed is logged. Without an HMAC key, webhooks are accepted without verification and an error is logged.

How the payment works

• On checkout, the module creates a single-use payment link and sends the customer to it.
• When the customer returns, and when the webhook arrives, the module fetches the payment link from the Adyen API.
• Link status completed or paid makes the order complete, paymentPending makes it pending, expired makes it expired.
• A failed attempt keeps the link active, so the customer can try again; the order status does not change.
• Refunds from the CP refund the full order amount. Adyen handles refunds asynchronously.

Limitations

• Refunds and chargebacks done in the Adyen Customer Area are not reflected on the order automatically. The module only processes the AUTHORISATION event.
• If your merchant account captures payments manually, a refund only works after the payment is captured in Adyen.

Test checklist

• [ ] For live: the Live URL prefix is filled in. Without it, the checkout shows The Adyen live URL prefix is not configured.
• [ ] After a successful payment, the payment link has status completed (or paid) and the order becomes complete.
• [ ] The AUTHORISATION webhook arrives with HMAC enabled: the log shows [NotifyEvent] lines and no webhook verification failed. Without it, refunds are impossible, because the pspReference is only in the webhook.
• [ ] A refund from the CP works. If your account captures manually, test the refund after capturing the payment.
• [ ] Remember that a refund or chargeback done in the Customer Area does not change the order status in the store.
• [ ] Use Adyen's test card numbers.

Viva.com

For merchants in Europe. The customer pays on Viva's hosted Smart Checkout page, with cards, Apple Pay, Google Pay, iDEAL, Bancontact, BLIK and the other methods enabled on your account. Supported currencies: EUR, GBP, RON, PLN, CZK, HUF, SEK and DKK.

Available from v3.13.0

payment_gateway="viva_wallet"

Setup

Do this in the demo account for test mode and again in the live account for live mode.

1. Log in to Viva (demo or live).
2. Go to Settings → API Access and copy the Merchant ID, the API Key and the Smart Checkout Client ID and Client Secret.
3. On the same page, enable Allow refunds if you want to refund from the CP.
4. Go to Sales → Online Payments → Websites/Apps and create a payment source. Set both its Success URL and Failure URL to the notify URL shown in the CP, with method=notify replaced by method=redirect. Copy the 4-digit source code.
5. Add the webhook (see Webhook below).

Viva does not accept a return URL per payment. That is why the return URL is set on the payment source. Viva adds the transaction id and order code to it, and the module finds the order from those.

Field	Description
Debug mode	On uses the demo environment and the test fields, off uses the live environment and the live fields
Test/Live Smart Checkout Client ID	From Settings → API Access
Test/Live Smart Checkout Client Secret	From Settings → API Access
Test/Live Merchant ID	From Settings → API Access. Used for the webhook verification and refunds
Test/Live API Key	From Settings → API Access
Test/Live Payment Source Code	The 4-digit code of the payment source with the return URL

Webhook

The CP shows the notify URL. Go to Settings → API Access → Webhooks, add that URL for the event Transaction Payment Created and click Verify. Viva then calls the URL, and the module answers with your webhook key (fetched with the Merchant ID and API Key).

Viva's webhook events are not signed. The module uses them only to find the transaction, fetches it from the Viva API and checks that it belongs to the order and matches the order total. Other events are ignored, because the customer may still retry after a failed attempt.

How the payment works

• On checkout, the module creates a payment order and sends the customer to Smart Checkout. The payment order times out after 30 minutes.
• After paying, Viva sends the customer to the Success URL of the payment source. The module finds the order, checks the transaction and sends the customer to the order page.
• Transaction status F (finished) makes the order complete, A makes it pending, E (error) failed, X cancelled, R refunded and a lost dispute a chargeback.
• A customer who cancels on Viva's page without any transaction lands on your site's homepage, because there is no transaction to identify the order. The order is not changed.
• Refunds from the CP refund the full order amount (sent in the smallest currency unit, for example cents). Allow refunds must be enabled in Viva.

Limitations

• Only the currencies listed above. The checkout shows an error for other currencies.

Test checklist

• [ ] The Success URL and Failure URL of the payment source are the notify URL with method=notify replaced by method=redirect, and after paying the customer lands on the order page.
• [ ] A customer who cancels on Viva's page without a transaction lands on the homepage, and the order stays open.
• [ ] The webhook verification handshake works: Verify in Settings → API Access → Webhooks succeeds.
• [ ] Allow refunds is enabled, and a refund from the CP works.
• [ ] The refunded amount in Viva equals the order total (the module sends it in the smallest currency unit, for example cents).
• [ ] For the demo environment, see Getting started with a sandbox demo account and the Viva developer portal for test cards. Demo payments must be at least 0.30.

Worldline Saferpay

For merchants in Switzerland and Europe. The customer pays on the Saferpay Payment Page with cards, TWINT, PostFinance Pay, PayPal, Klarna, iDEAL, Bancontact, EPS, BLIK or another method enabled on your terminal. In the CP, this gateway is listed as Saferpay. The currency is not limited by the module: any currency your terminal supports.

Available from v3.13.0

payment_gateway="saferpay"

Setup

Do this in the test Backoffice for test mode and in the live Backoffice for live mode.

1. Log in to the Saferpay Backoffice. A test account is available from Worldline.
2. Go to Settings → JSON API basic authentication and create a JSON API user and password.
3. Note your Customer ID: the first part of your account id (for account 123123-12345678 it is 123123).
4. Go to Settings → Terminals and copy the Terminal ID of your e-commerce terminal.

Field	Description
Debug mode	On uses the Saferpay test environment and the test fields, off uses the live environment and the live fields
Available payment methods	The methods offered on the Payment Page. Each method must also be activated on your terminal. Leave empty to offer all methods of the terminal
Test/Live Customer ID	The first part of your account id
Test/Live Terminal ID	From Settings → Terminals
Test/Live JSON API Username	From Settings → JSON API basic authentication
Test/Live JSON API Password	The password of that JSON API user

Webhook

No setup needed. The module sends the notify URL with every payment, so the CP does not show it. The notify URL contains the order hash and a signature made with the JSON API password; a notification with a wrong signature is refused and webhook verification failed is logged.

How the payment works

• On checkout, the module initializes a Payment Page and sends the customer to it.
• When the customer returns, or when Saferpay sends the notification, the module asks Saferpay for the result. An authorized payment is then captured automatically, and the order becomes complete.
• A payment whose capture is still pending makes the order pending.
• An aborted payment makes the order cancelled; a declined payment, failed 3D Secure or a risk block makes it failed; an expired page makes it expired.
• Refunds from the CP refund the full order amount (the refund is captured right away as well).

Test checklist

• [ ] After paying, the payment is captured automatically: the transaction shows as captured in the Backoffice and the order is complete.
• [ ] The JSON API username and password, Customer ID and Terminal ID are filled in for both test and live.
• [ ] No webhook setup is needed: the notify URL is sent with each payment. Check the log for [NotifyEvent] lines without webhook verification failed.
• [ ] An aborted payment returns the customer to the checkout with a cancelled order.
• [ ] A refund from the CP works.
• [ ] See Saferpay JSON API and the test data you receive with your test account.

Worldpay

For merchants in the United Kingdom and worldwide. The customer pays by card on the Access Worldpay Hosted Payment Pages; card details and 3D Secure are handled by Worldpay. The currency is not limited by the module: any currency your Worldpay account supports.

Available from v3.13.0

payment_gateway="worldpay"

Setup

1. Log in to the Worldpay Dashboard and go to Developer Tools for your API username, password and entity (for the Try environment and for live).
2. Enable webhooks with the notify URL (see Webhook below).

Field	Description
Debug mode	On uses the Worldpay Try environment and the test fields, off uses the live environment and the live fields
Statement narrative	Shown on the customer's card statement, max 24 characters. Defaults to Order #<order id>
Test/Live API Username	From Developer Tools
Test/Live API Password	From Developer Tools
Test/Live Entity	Your entity from Developer Tools. Defaults to default
Test/Live Event-Signature Secret	The shared secret for the Event-Signature header of the webhooks

The billing address is sent to Worldpay when the order has a complete one (address, city, postcode and country).

Webhook

The CP shows the notify URL. Webhooks are enabled in the Worldpay Dashboard, or by your Worldpay Implementation Manager, with that URL. The Event-Signature shared secret may also have to be set up by your Implementation Manager; ask them for it and copy it into the matching Event-Signature Secret field.

A webhook with an invalid signature is refused (HTTP 400) and webhook verification failed is logged. Without a secret, webhooks are accepted without verification and an error is logged. Only payment events are processed.

How the payment works

• On checkout, the module creates a Hosted Payment Pages session and sends the customer to it. Payments are settled automatically.
• When the customer returns, and when a webhook arrives, the module looks up the payment with the Payment Queries API.
• Authorized or settled payments make the order complete. Refused or failed payments make it failed; cancelled or reversed payments cancelled.
• The Payment Queries API can lag up to about 60 seconds behind. A customer who returns before the payment can be found gets the pending status and is sent to your site's homepage instead of the order page; the next webhook (or a later return) completes the order.
• When the customer cancels, or the payment fails, errors or expires, Worldpay sends the customer back to the checkout and the order becomes cancelled.
• Refunds from the CP refund the full order amount, and are only possible once the payment is settled. Worldpay processes them asynchronously.

Limitations

• Card payments only. Alternative payment methods (APMs) are not covered by the Payment Queries API, so the module cannot track them.
• Refunds only after settlement. Before that, the CP shows This Worldpay payment cannot be refunded (yet), it may not be settled.

Test checklist

• [ ] Webhooks arrive with a valid Event-Signature: the log shows [NotifyEvent] lines and no webhook verification failed. Ask your Worldpay Implementation Manager if signing has to be set up for you.
• [ ] The order may show pending first after returning, because payment queries can lag up to about 60 seconds. It becomes complete once the webhook arrives.
• [ ] A refund from the CP works once the payment is settled, and is refused before that.
• [ ] Only card payments are used: APMs are not covered by Payment Queries.
• [ ] Use the test values from Hosted Payment Pages testing in the Try environment.

Opayo

For merchants in the United Kingdom and Ireland. Opayo by Elavon (formerly Sage Pay), using the Form integration: the customer pays by card or PayPal on Opayo's hosted payment pages. The currency is not limited by the module: any currency your Opayo account supports.

Available from v3.13.0

payment_gateway="opayo"

Setup

1. Find your vendor name and the Form integration encryption passwords (test and live) in the welcome emails from Opayo, or in MyOpayo under Settings → Encryption password.
2. Make sure your checkout asks for the billing address: first name, last name, address, city, postcode and country (and the state for the US). Opayo requires these fields.

Field	Description
Debug mode	On uses the Opayo sandbox and the test encryption password, off uses live and the live encryption password
Vendor Name	Your Opayo vendor name
Test Encryption Password	The Form encryption password of the test environment
Live Encryption Password	The Form encryption password of the live environment

The module uses protocol 4.00 and the Elavon hosts (sandbox.opayo.eu.elavon.com and live.opayo.eu.elavon.com), see the Elavon test and live URLs.

Webhook

Opayo Form has no webhooks. The result of the payment comes back encrypted on the return URL when the customer returns to your site. That means:

• If the customer does not return (closes the browser after paying), the order is not updated. Check the transaction in MyOpayo and update the order manually.
• The Store log shows no result received on the return URL, check the transaction in MyOpayo when a return arrives without a result.

How the payment works

• On checkout, the browser posts the encrypted payment data to Opayo's payment page.
• After paying, Opayo sends the customer back to the return URL (with its query string intact) with the encrypted result. The module decrypts it, checks that it belongs to the order and matches the order total, and sends the customer to the order page.
• OK makes the order complete, PENDING makes it pending, ABORT makes it cancelled, and a rejected, not authorised or invalid payment makes it failed.
• Opayo does not send its own emails to the customer; the store sends the confirmation email.

Limitations

• No refunds from the CP. Refund in MyOpayo instead, and update the order status yourself.
• No webhooks, see above.
• The billing address fields are required by Opayo.

Test checklist

• [ ] There are no webhooks and no refunds from the CP. Refund a test payment in test MyOpayo.
• [ ] After paying, the customer returns with the encrypted result and the order becomes complete. If the customer does not return, check the transaction in MyOpayo.
• [ ] The return URL with its query string survives Opayo: the customer lands on the order page.
• [ ] The checkout asks for all billing address fields (name, address, city, postcode, country). Opayo refuses the payment without them.
• [ ] Payments go to the Elavon sandbox host with protocol 4.00, using the test encryption password.
• [ ] Use the test cards that Opayo provides for test MyOpayo.

GoCardless

For merchants in the United Kingdom and the Eurozone. The customer pays with Instant Bank Pay (open banking) on GoCardless's hosted payment page. Supported currencies: GBP and EUR.

Available from v3.13.0

payment_gateway="go_cardless"

Setup

Do this in the sandbox dashboard for test mode and in the live dashboard for live mode.

1. Make sure Instant Bank Pay is enabled on your account.
2. Go to Developers → Create → Access token and create a read-write access token.
3. Add the webhook endpoint (see Webhook below).
4. If you want to refund from the CP, ask GoCardless to enable refunds: they are disabled by default.

Field	Description
Debug mode	On uses the GoCardless sandbox and the sandbox fields, off uses live and the live fields
Sandbox Access Token	The read-write access token from the sandbox dashboard
Sandbox Webhook Endpoint Secret	The secret of the webhook endpoint in the sandbox dashboard
Live Access Token	The read-write access token from the live dashboard
Live Webhook Endpoint Secret	The secret of the webhook endpoint in the live dashboard

Webhook

The CP shows the notify URL. Go to Developers → Create → Webhook endpoint, add that URL and copy its secret into the matching Webhook Endpoint Secret field.

The webhook is what completes the order, because the payment is confirmed days after the customer paid. Payment events are linked to the order through the order metadata the module sends with the payment. One webhook can contain events for several orders; all of them are processed.

A webhook with an invalid signature is refused (HTTP 498) and webhook verification failed is logged. Without a secret, webhooks are accepted without verification and an error is logged.

How the payment works

• On checkout, the module creates a billing request and sends the customer to GoCardless's payment page.
• When the customer has authorised the payment, the order becomes pending and the customer is sent to your site's homepage (the store does this for every pending order). Bank payments are asynchronous: the order stays pending until GoCardless confirms the payment, which can take days.
• Confirmed or paid out makes the order complete (and sends the confirmation email). A failed payment makes it failed, a cancelled one cancelled, a charged back one a chargeback.
• When the customer leaves the payment page, they return to the checkout and the order becomes cancelled.
• Refunds from the CP refund the full order amount.

Limitations

• GBP and EUR only.
• The customer receives the confirmation email only when the payment is confirmed, not right after paying.
• Refunds are disabled by default in GoCardless, and are only possible after the safer refund period (by default 7 days after the charge date), unless GoCardless changed this for your account.

Test checklist

• [ ] After paying, the order is pending, and it becomes complete only when GoCardless confirms the payment via the webhook (in live this can take days). Use the scenario simulators in the sandbox to move a payment forward.
• [ ] Instant Bank Pay is enabled on the account.
• [ ] Payment webhooks carry the order metadata and update the right order: the log shows [NotifyEvent] lines and no webhook verification failed.
• [ ] Refunds are enabled by GoCardless for your account, and a refund from the CP works after the safer refund period.