Adyen

In this article

Setup

Tokens

Payment Links

Webhooks

Tax-free shopping

Support

Terminal help

All settings to communicate with the terminal are accessible in the Adyen portal (log on from adyen.com).

Adyen website

Setup

There are two connections available for Adyen, Local and Cloud.

Mutual settings

Apart from the default settings indicating the selection, there are a few mutual settings both connection types share:

Setup videos

Adyen Cloud setup video

Adyen Local setup video

Cloud

When you select a cloud connection, LS Pay will communicate with the Adyen gateway and the Adyen gateway will handle the communication to the PED. In this way, it does not matter where the PED connects, it is always reachable.

The offside is that the network must be active, both from the POS/ECR and the PED, it does not cater for offline transactions.

Note: Token payments are only available using a cloud connection.

When setting up cloud communication, additional settings are needed:

Local

When you select local connections, LS Pay will communicate straight to the PED and the PED handles communication to the Adyen gateway. In this way it has full support for offline transactions.

The offside is that it does not support all pre-authorization processes or tokens.

Important: Adyen's public root certificate must be installed in your trust store to use the local connection. See Adyen's documentation.

Specific settings are needed to communicate with the terminal, make sure the PED is on the same network as the POS:

Tokens

Note: Tokens are only supported on an Adyen Cloud connection. Adyen Local does not support tokens.

LS Pay does not support using CVC verifications, so before using tokens with Adyen, contact Adyen and ask them to activate "SkipCvcForOneClick".

Also make sure the necessary additional data is enabled in Adyen's customer area, under Developers > Additional Data:

• Payment > Recurring details
• Payment > Include alias info
• Acquirer > Payment account reference

See Adyen's documentation on enabling tokenization details.

Getting a payment token

When making a purchase, set a shopper reference (such as a user ID or account ID, at least three characters long and without personally identifiable information) on the request. After a successful payment, the token is returned in the response and can be used for future payments with the same shopper reference.

Creating a token without taking a payment

A card can also be stored for later use without taking a payment, using the shopper reference described above. Adyen supports zero-amount tokenization, so no amount needs to be authorized unless the token type requires it. A Mail Order/Telephone Order (MOTO) tender type is used for token creation of this kind. The created token is returned together with the merchant and customer receipts.

Paying with a token

When making a purchase, set the token and its shopper reference on the request to charge the stored token.

Token refunds

Unreferenced refunds of a stored token (without the original transaction's IDs) are supported through Adyen's standalone refunds endpoint, using the token and its shopper reference. This requires the merchant account to be configured for ECOM unreferenced refunds by Adyen support, and requires webhooks to be enabled (see Webhooks) – the outcome is only known once Adyen's REFUND webhook notification arrives. Note: Only available on an Adyen Cloud connection.

Refunds that do include the original transaction's IDs use the normal referenced refund flow instead.

Troubleshooting: A 403 - Not Allowed error on a token refund usually means ECOM unreferenced refunds are not yet configured for the merchant account – contact Adyen support.

Payment Links

Note: Payment links are only supported in LS Pay Service version 3 and up, and only on an Adyen Cloud connection. Adyen Local does not support payment links.

Payment links do not require a terminal device.

Setting up payment links

Adyen uses webhooks to retrieve payment link responses. Set up webhooks in the Adyen portal, with the webhook request URL set to <your LS Pay Service URL>/webhook/Adyen/PaymentLink. Event code: AUTHORISATION.

Creating a payment link

When creating a payment link, set the total amount and, optionally, an expiration date (the default is 24 hours). After the link is created, the link and its ID are returned in the response.

Disabling a payment link

Disabling a payment link requires the link's ID. This forces the link to expire; the response then shows the link's status as Expired.

Getting payment link info

Getting the payment link info returns the current status of a payment link.

Tokenizing the shopper's payment details via a payment link

To tokenize the shopper's payment details while creating a payment link, set a shopper reference and an initiator reason (see Tokens) on the request. When a shopper reference is present, the link is created so the shopper's payment details are stored without further consent prompts.

Once the shopper pays through the link, the created token is returned, together with the shopper reference, on the AUTHORISATION webhook response. Note: This requires the "Recurring details" additional data option to be enabled specifically for this webhook in the Adyen Customer Area (Developers > Additional data > Payment); otherwise the webhook response will not include the token.

The resulting token can then be used to make payments the same way as any other token.

Webhooks

Some Adyen functionality is only supported through webhooks. LS Pay currently supports these webhook functionalities:

Note: Payment link responses and pre-authorization webhooks are only supported in LS Pay Service version 3 and up.

Using webhooks in LS Hardware Station

Note: Only available in LS Hardware Station version 29.0.0.0 and up.

Set up webhooks in the Adyen portal. The webhook request URL should be set to <your LS Hardware Station URL>/webhook/Adyen. See the instructions for display notifications.

Using webhooks in LS Pay Service

1. Set up webhooks in the Adyen portal. The webhook request URL should be set to <your LS Pay Service URL>/webhook/Adyen.
   • Instructions for display notifications.
   • Instructions for referenced refunds. Event code: CANCEL_OR_REFUND.
   • Standalone token refund event codes: REFUND, REFUND_WITH_DATA.
2. Enable refund webhooks in LS Pay. Note: This is only needed for refund webhooks – display message webhooks work without these settings.
   • "WebhooksEnabled", set to true: plugin is running in LS Pay Service, a port has been opened and webhooks have been set up in the Adyen portal.
   • "AllowReferencedRefund", set to false: allows referenced refund without webhooks (not recommended) – bypasses the webhook requirement above for referenced refunds.

    

Tax-free shopping

Adyen supports tax-free shopping (VAT refunds for international travellers) through secure card capture: Adyen shares the shopper's encrypted card details with a tax-free shopping (TFS) provider – currently Global Blue only. See Adyen's documentation.

Tax-free is not a separate transaction type. It is a flag on the normal purchase that is sent to Adyen; Adyen records the indicator on the transaction and, once the TFS webhook is configured, forwards the encrypted card number to the provider.

1. Enable the setting in LS Pay

Enable the "EnableTaxFree" setting to flag every transaction as tax-free.

Important: This is a plugin-level toggle, not a per-transaction choice. When it is on, every transaction on that plugin instance is flagged as tax-free and the shopper's encrypted card data is forwarded to the TFS provider. Only enable it on plugin instances dedicated to tax-free sales (for example a dedicated store or lane), and make sure shopper consent is handled on the POS side.

2. Configure the tax-free webhook in the Adyen Customer Area

The indicator alone does not forward any data – the transfer to the TFS provider is done by an Adyen webhook that must be configured on the merchant account:

1. In the Customer Area, go to Developers > Webhooks and select Create new webhook.
2. Add the Send card number to Global Blue webhook.
3. Under Server configuration, set the URL to https://www.adyen.com (a sentinel value for Global Blue – Adyen routes internally to the provider).
4. Add a Description identifying it as part of the tax-free shopping flow, then select Save configuration.

Note: The Send card number to Global Blue webhook type only appears once Adyen has enabled tax-free shopping/secure card capture and a Global Blue agreement on the account. If it is missing, contact your Adyen account manager to have it enabled.

3. Verify

• LS Pay log (DEBUG): the request log line Tax-free indicator added to payment request.
• Adyen Customer Area, transaction detail: Tax Free Indicator = true confirms Adyen accepted the flag. A Tax Free Identifier appears once the webhook has fired, confirming the provider received the card data. Webhooks are not retroactive – only transactions made after the webhook is enabled get an identifier.

Note: In a test environment, the TFS provider's eligibility check may require provider-approved test card numbers; standard Adyen test cards may not return an identifier.

Support

EFT

Adyen supports the core EFT functions available in LS Pay:

• Purchase
  • Tips on PED, managed in the Adyen portal.
  • MOTO payments (Mail Order Telephone Order).
  • QR payments using a QR code scanned by the merchant.
• Refund
  • Stand-alone refund (no previous purchase).
• Void
  • Can void any previous transaction.
• Get last transaction
  • Gets the last transaction processed in the Adyen portal.
• Cancel
  • Possible to cancel both on PED and from POS/ECR.

   

Pre-authorization

Pre-authorizations are supported using cloud communication. Even if initiating a pre-authorization is accessible using local connection, it is not possible to manage or finalize using local, only through cloud.

• Pre-authorization
• Update pre-authorization to update amount or to prolong the authorization.
• Cancel pre-authorization to release the amount.
• Finalize pre-authorization to confirm the amount used for the transaction.

Printing

Adyen PEDs that have printers (like V400m) can receive print requests from LS Pay, using interfaces IPrinterService and IRecieptPrinting.

public async Task PrintReceiptLine(ReceiptLine receiptLine)
{
    if (receiptLine != null)
    {
        List<ReceiptLine> lines = new List<ReceiptLine>();
        lines.Add(receiptLine);

        if(eaManagement is IPrinter)
        {
            IPrinterService printerService = ((IPrinter)this.eaManagement).GetPrinterService();
            printerService.PrintingEvent += OnPrintEvent;

            if (printerService is IReceiptPrinting)
            {
                await ((IReceiptPrinting)this.printerService).PrintAsync(lines);
            }
        }
    }
}

Gift cards

Gift card features have been added to the integration:

• Activate
• Add value
• Balance inquiry
• Close card
• Deactivate

Terminal help

• Settings > Server reports > Standard notification.
• Access the Admin menu: press 9, then the green button. The password is (0208), which can be changed or looked up in the Adyen portal.
• Ping backend: Network > Diagnostics.
• Update config: Config > Sync (update).