Adyen
Adyen
Payments made easyTo perform payments in any of our frontends, we offer an integration with Adyen. This is our preferred and recommended payment service provider. The configuration varies between different frontends and payment methods, this document will tell you exactly how to set up your EVA and Adyen environments correctly.
Adyen offers merchants online services for accepting electronic payments by payment methods including credit cards, bank based payments such as debit cards, bank transfers, and real-time bank transfers based on online banking. Adyen's online payment platform connects to payment methods across the world. Payment methods include international credit cards, local cash-based methods, such as Boleto in Brazil, Internet banking methods, such as iDEAL in the Netherlands and Mobile payment methods, such as Blik in Poland.
Getting started
For EVA and Adyen to communicate with each other, we need certain configuration to be allowed to make requests between these two systems.
- For EVA to talk to Adyen, we need to configure an API credential in Adyen, which we will use to authenticate calls coming from EVA.
- For Adyen to talk to EVA, we need to set up an API user in EVA, which we will use to authenticate calls coming from Adyen.
Before we set these up, make sure you have a Merchant Account set up correctly in your Adyen environment.
Adyen API credential
To set up your API credential, head over to Developers > API credentials in Adyen. Here, select Create new credential.
After setting up this API credential, you can generate an API key for this specific credential. Generate the key and store it someplace safe, you can't see or copy this key after saving.
Next, we need to make this information known in EVA, so EVA knows what to include in its messages for them to be successful. We will need the following settings in EVA:
| Setting | Description |
|---|---|
| Adyen:CheckoutAPI:ApiKey | Your API credential's API key as configured before. |
| Adyen:CheckoutAPI:BaseUrl | Your Adyen API url as found under Developers > API urls. Something in the format of; https://checkout-test.adyen.com/checkout/v69/paymentMethods. |
| Adyen:MerchantAccount | Your Adyen Merchant Account. |
| Adyen:TerminalAPI:ApiKey | Your API credential's API key as configured before. |
| Adyen:UseCheckoutAPIForRefundsAndCaptures | true |
| Pin:ClientVersion | ADYEN |
EVA API user
To create an API user in EVA, see API Users.
This user should have a Role containing the AdyenNotificationEndpoint permission. The chapter is hidden if the inquiring user does not have that permission. Permissions are managed from the Roles and rights chapter namely, from the functionalities card of a users role.
After creating our API user for the Adyen integration, we need to create an API key for that API user. Store the API key somewhere safe, you won't be able to view or fetch the token after creating it.
Next, we need to make this information known in Adyen, so Adyen knows what to include in its messages towards EVA. To do so, head over to Developers > Webhooks and create a new 'Standard notification' webhook with the following settings:
| Name | Value |
|---|---|
| Server configuration | Your EVA endpoint suffixed with /adyen. Example: https://api.eva-dev.on-eva.io/adyen |
| Security > Basic authentication > Username | eva |
| Security > Basic authentication > Password | Your EVA API User's API key as configured before. |
HMAC keys
Now, under the same Security header, we need to set up an HMAC key. This HMAC key will be used to encrypt traffic between Adyen and EVA. This is mandatory, our Adyen integration will not work without this. Create an HMAC key and store it someplace safe, you will not be able to retrieve this key later on.
Now, we have to make this HMAC key known in EVA so EVA can decrypt Adyen's messages. To do so, fill out your newly created HMAC key in the Adyen:HmacKeys setting.
To make things even easier, see Enable HMAC signatures on Adyen's own support page. Save the HMAC key in the setting mentioned above. Be sure to give Adyen some time before you enable this validation in EVA. Once configured, EVA will immediately enforce it. This EVA setting is a comma-separated list of keys, to allow you to securely transition between two keys, if you ever need to.
Testing
After having set up your EVA API User, your Adyen Standard Notification webhook and your HMAC key, make sure to test your configuration. You can do so in your Adyen webhook configuration page, by clicking Test configuration at the bottom of the screen. You will get one of the following response codes;
Your webhook is functioning as it should.
Check your EVA API User's role and whether it has the AdyenNotificationEndpoint permission. Permissions are managed from the Roles and rights chapter namely, from the functionalities card of a users role.
Check whether your HMAC key is set up correctly, and if your endpoint is correct.
Now, having set up all the above, we have put in place our standard, recommended, configuration harmony between EVA and Adyen using the Adyen CheckoutAPI. Having set up the above configuration will allow you to support online payments, as well as terminal payments in store.
Additional configuration
Up to this point, we have made sure that EVA and Adyen can communicate. Before we can accept payments however, there are some additional things to consider and configure.
Setting up payment methods
In order to start supporting a specific payment method, we need to enable the method in EVA, as well as in Adyen.
Payment methods in Adyen
In order to enable certain payment methods in Adyen, head over to Settings > Payment methods in your Adyen dashboard.
Here you can configure what payment methods you want to support.
Payment methods in EVA
In order to also enable these methods in EVA, head over to the Payment methods chapter in the Financials module.
Here you can add your corresponding payment methods under the Adyen Checkout API payment type since we are using the CheckoutAPI as default here. The payment method's Code should correspond with Adyen's payment method codes as mentioned in their payment method documentation, prefixed with ADYEN_CHECKOUT_API_. For example:
ADYEN_CHECKOUT_API_IDEALfor iDEAL paymentsADYEN_CHECKOUT_API_SCHEMEfor credit card payments
Payment terminal settings
AdyenPOS terminal
As an alternative to the payment terminal, you can also use the AdyenPOS terminal. This new smaller terminal is wireless and allows you to use it throughout the stores. This is currently being rolled-out however, so it might not be available in your region yet.
The following two settings are all that's required to get it up and running.
| Setting | Description |
|---|---|
| Adyen:PosSdk:BaseUrl | BaseURL can be found in your Adyen environment under Developers > API urls. |
| Adyen:PosSdk:ApiKey | ApiKey can be found in your Adyen API credential. |
Aside from those two, the PosSdk makes use of the other settings which were specified by you earlier, such as the Adyen:MerchantAccount and the Adyen:UseCheckoutAPIForRefundsAndCaptures for refunding.
Additional CheckoutAPI options
Adyen Drop-in
The Adyen Drop-in payment method is specifically described in the same section as the CheckoutAPI since it runs on mostly the same settings as the CheckoutAPI.
Refunds are performed via the basic Adyen integration or CheckoutAPI.
There's only one extra setting required when setting up Adyen Drop-in, as you can see in the table below.
| Setting | Description |
|---|---|
| Adyen:CheckoutAPI:ClientKey | ClientKey can be found in your Adyen API credential. |
Aside from requesting the payment methods for this drop-in integration in your Adyen account, creating payment types for this integration is done in twofold:
- Create the basic (fallback) version of the payment type
The code for the basic variant of the Adyen drop-in payment method consists of ADYEN_DROPIN only. This is what's sent to Adyen when the payment method is initiated. The payment method that's returned by Adyen however, consists of that same code + the specific payment method chosen by the customer in the checkout. This will turn into 'ADYEN_DROPIN_ideal' for example.
- ADYEN_DROPIN_payment-brandname
Although it's not a necessity to create anything else than the generic 'ADYEN_DROPIN' payment type, it is required if you want type specific actions. By creating the brandname specific types, you can determine the relevant options, such as return actions and ledger choice but also allow for detailed finance processing through cookbook.
By not creating the specific brandnames in EVA, the payment will fall back on the generic type and the payment options specified in it.
Adyen:CheckoutAPI:BaseUrl needs to be set at least to v68.
The Drop-in payment method by default uses the 'Order.SoldFromOrganizationUnit.CountryID' to determine what payment methods are shown to shoppers. If you don't have OUs on country level, you may instead want to enable the setting Adyen:CheckoutAPI:PreferBillingAddressCountryID. The available payment methods will then be based on 'Order.BillingAddress.CountryID'.
Anonymous ApplePay
By using Anonymous ApplePay, you enable your customers to perform a quick checkout without the need for logging in and/or providing personal information. It's mentioned in the same chapter as the CheckoutAPI because it runs on the same framework. It does not require any additional settings aside from a new payment type: ApplePay
There is some integration work required; you can read up on that here.
ApplePay and Google Pay
Both Apple Pay and Google Pay need the same configuration as the Adyen Drop-in. This means that you are probably already good to go for these new payment types. All you need to do is specify a new payment method, if you want to be able to differentiate between payments in Cookbook.
Additional Adyen integration possibilities
Basic integration (legacy)
This method does not support creating payments specifically, but can instead be used to map payment transactions pushed into EVA with the PushSalesOrder service. By using this payment method, the pushed transactions can be refunded and captured.
We mention it here - under Archived - because we recommend that the CheckoutAPI is used for all payments, even for payments which are pushed into EVA. This way refunds can be performed with the CheckoutAPI.
You can however keep using the basic Adyen integration for now. You will need to define the following four settings to do so.
| Setting | Description |
|---|---|
| Adyen:BaseUrl | Adyen has customer specific endpoints, EVA needs to know that up until the /[method] so https://pal-test.adyen.com/pal/servlet/Payment/[version] or for Live https://[random]-[companyname]-pal-live.adyenpayments.com/pal/servlet/Payment/[version] |
| Adyen:Username | Username for your 'web service user' as specified in the Adyen account settings. |
| Adyen:Password | Password for your 'web service user' as specified in the Adyen account settings. |
| Adyen:UseCheckoutAPIForRefundsAndCaptures | When set to 'false' will use the URL, username & password in this table for refunds and captures. |
The payment types for the basic Adyen integration are prefixed with ADYEN_ followed by the brand name like IDEAL.
Note: How these specific codes in the payment types must be formatted, depends on Adyen. There is no guarantee that these codes will be the same per customer, or even country.
CheckoutSDK (v2)
This specific SDK development is no longer in development at Adyen. Although it is still referenced here for customers who currently make use of it, and for EVA Pay, this SDK should no longer be used in new implementations and will be deprecated in 2022.
| Setting | Description |
|---|---|
| Adyen:Checkout:SDK:BaseUrl | Adyen has customer specific endpoints, EVA needs to know that up until the /[method]. In this case the SDK checkout endpoint. https://checkout-test.adyen.com/[version] or for Live: https://[random]-[company name]-checkout-live.adyenpayments.com/checkout/[version] Note: our latest supported version for the CheckoutSDK is v67. |
| Adyen:Checkout:SDK:ApiKey | API key for your 'web service user' as specified in the Adyen account settings. |
| Adyen:Checkout:SDK:PublicKeyForClientEncryption | Found in your Adyen account setting under 'Client Encryption Public Key'. |
| Adyen:Checkout:SDK:AllowedPaymentMethods | Payment methods you request for the checkout SDK. Values must resemble the 'brandname' used in Adyen. Do note they must be configured in Adyen as well. not recommended, manage what's available in Adyen in combination with the block setting below |
| Adyen:Checkout:SDK:BlockedPaymentMethods | What payment methods you want to block on the checkout SDK. Values must resemble the 'brandname' used in Adyen. |
Many frontends still use the SDK checkout which also supports extra control through allow and block payment methods based on Adyen codes for that frontend.
In the contrary to the CheckoutAPI, the CheckoutSDK is more limited and does not need to be subdivided by payment methods on brand level, since this all taken care of on the side of Adyen. You do however still have to get the specific payment methods (such as iDEAL) configured on the side of Adyen. The CheckoutSDK code in the payment is ADYEN_CHECKOUT_SESSION
Klarna
Klarna provides online financial services such as payments for online storefronts and direct payments along with post-purchase payments. EVA supports the use of Klarna via our partner Adyen, and for this, specific settings and considerations apply.
3 Klarna payment types
- Klarna pay later: buy now, pay later in one payment
- Klarna pay over time: buy now, pay later in multiple installments
- Klarna pay now: buy now, pay now
Configuration of payment methods
When you push in Klarna paid orders via PushSalesOrder, you need to enable the payment methods as such:
| Payment type name | Payment method | Code |
|---|---|---|
| Klarna pay later | ADYEN | ADYEN_KLARNA |
| Klarna pay over time | ADYEN | ADYEN_KLARNA_ACCOUNT |
| Klarna pay now | ADYEN | ADYEN_KLARNA_PAYNOW |
Pushing in Klarna orders
When pushing in orders paid with Klarna via PushSalesOrder, some additional details are needed. This is because Klarna shows consumers the details of their ordered items in a Klarna portal. If some or all these items are cancelled or returned via EVA, EVA needs to inform Klarna which items the refund refers to so their portal correctly shows this data on an item level.
For this, you'll need to include some orderline-level data that your front-end (e.g. e-commerce shop) also sends to Klarna during the initial payment in checkout.
This info is stored in EVA via the PaymentLineIdentifier found in the Lines and ShippingInformation objects in the PushSalesOrder web service.
Insert these values in your PushSalesOrder, matching them to the value included in the ‘#’ of the object openinvoicedata.line#.itemId: # that your front-end passed to Adyen/Klarna upon initial payment in your front-end.
Example of order
| Item | Amount authorized | Field from your check-out to Adyen/Klarna | Value on line level in the PaymentLineIdentifier in PushSalesOrder to EVA | Payment amount pushed to EVA via PushSalesOrder |
|---|---|---|---|---|
| T-shirt | 20.00 | openinvoicedata.line1.itemId: 1 | 1 | |
| Jeans | 30.00 | openinvoicedata.line2.itemId: 2 | 2 | |
| Total | 50.00 | 50.00 |
Capturing
A Klarna payment, like many payments, consists of an authorization(/reservation) step and a capture step.
The authorization just ensures the amount is available and reserved on an account without truly charging it. Only upon capture is the account truly charged.
You can determine when this capture takes place — the moment the order gets created in EVA, or upon the shipment of the goods. Shipment is often chosen, as to not overcharge the account initially, as some items from an order might not be fulfillable.
To set the capture moment to Shipment for Klarna:
- Go to Payment Methods in Admin Suite
- Find the Klarna payment type under Adyen Payment Method
- Go to Organization Unit settings and determine for which OU(set) you want to define the capture moment
- Set the Capture moment to Ship
Removing any ‘left over’ authorized amounts upon partial cancellation
By default, Adyen will keep the initially authorized amount reserved for X days, awaiting a capture. In case (a part of) the order is not fulfillable, you want to free up any ‘left over’ authorized amount on the consumers’ account immediately. To do so set the setting Payments:TriggerCancellationsAfterLastCapture to true.
Discounts
When the setting Adyen:CheckoutAPI:IncludeDisounts is set to true EVA sends the line amount minus the discount to Klarna. This ensures a match between the amounts Klarna receives from Adyen and EVA.
To find out how to set it, check how your front-end sends the data to Adyen/Klarna. It needs to be set to true if the checkout also sends discounted amounts. If they do not send discounted amounts, it needs to be set to false.
Refunds
In order to correctly display info to consumers via the Klarna portal, they need to know more than just ‘€30 of an original €50 transaction was refunded’. Klarna needs to know which item that €30 refund belongs to.
To correctly send in this data, set the setting Adyen:EnableKlarnaLineInfoForRefunds to true.
Note: this process uses the PaymentLineIdentifier as described above and only works when EVA knows which item cancellation or return triggered the refund. Editing an existing orderline amount might cause a mismatch with the Klarna portal.
Because of the different nature and relationship that the different elements (payments, OrderAmounts, OrderLines) have in EVA we needed to jump through quite a few (burning) hoops to communicate the additional data to Klarna.
For example, an orderline being returned results in an open amount on the order, that open amount can then result in a PaymentTransaction. As you can see there is at the moment of payment no relationship between the orderline and the refund payment. Because Klarna requires this information (they keep track of the invoice at their side) we implemented some things that allow EVA an educated guess on which orderline is related to this particular refund or capture, it should be noted that it will not work in all cases.
Adyen Deprecations
Several Adyen payment methods have been deprecated some time ago by Adyen and have now in turn been deprecated in EVA. It means that refunds will now only be possible on existing transactions for the following methods:
- Adyen Hosted Payment Pages
- AdyenCheckoutLegacySDK
- AdyenPin
To be deprecated in 2022:
- AdyenCheckoutSDK (AdyenCheckoutSession)
- AdyenAnonymousCheckoutSDK.