Overview

The Adyen integration lets you take payments in two ways:

• Payment terminals: your staff take card payments in the store on an Adyen card reader.
• Payment links: Fixably emails the customer a link to an Adyen payment page, where they pay an invoice online.

Both use the same settings page and the same webhook. A webhook is a message that Adyen sends to Fixably to say that a payment or refund is done.

Integration availability

Adyen is available for customers on Fixably Enterprise agreements. To have the feature enabled in your tenant, please reach out to support@fixably.com.

For tenants on Premium, Basic or Legacy agreements, please reach out to customer.success@fixably.com for more details.

Before you begin

Make sure you have the following:

• An active Adyen merchant account, with access to the Adyen Customer Area (Adyen's own admin website).
• An Adyen API key. This is a secret key that lets Fixably talk to your Adyen account. You create it in the Adyen Customer Area.
• Your Adyen merchant account name.
• The Manage Adyen settings permission on your Fixably user role.
• For terminals: your card readers must already be set up and connected in the Adyen Customer Area.
• Your company country must be set in Fixably. Adyen terminals use the country to pick the right Adyen data center. Terminals are supported in Europe, the United Kingdom, the United Arab Emirates, North America, Brazil, Australia, New Zealand, Hong Kong, Japan, Malaysia and Singapore.

Note: your Adyen test account and your Adyen live account have different details. Use your test details while you set up, and change them when you go live (see Step 4 below). If you are an enterprise account with a UAT environment, we suggest setting up your Adyen test account with your UAT Fixably tenant.

Setup

Setting up Adyen takes 4 steps:

1. Enter your Adyen account details in Fixably.
2. Connect the Adyen webhook to Fixably.
3. Add your payment terminals to your locations (only if you use terminals).
4. Turn on the Production environment when you are ready to take real payments.

Step 1: Enter your Adyen account details

1. Go to System Settings > Integrations > Adyen.
2. Make sure Enable is ticked. If you do not see the Enable checkbox, Fixably support turns it on for you.
3. Tick Active.
4. In Api Key, paste the API key from the Adyen Customer Area.
5. In Merchant account, enter your Adyen merchant account name.
6. Leave Terminal API version at its default unless Fixably support tells you to change it.
7. Under Payment links, fill in these fields if you want to send payment links:
   • Payment link API version: leave at its default unless Fixably support tells you to change it.
   • Payment link expiry in days: how long a payment link stays open. Enter a number from 1 to 70.
   • Allowed payment methods: pick the payment methods your customers can use on the payment page. Leave it empty to show every method that is turned on in your Adyen account.
8. Under Webhooks, enter your Webhook HMAC key. You create this key in Step 2, so you can come back to it. Fixably cannot save the page without it.
9. Click Save settings.

Please note that your payment methods also need to be turned on in your Adyen account before you select them in Fixably.

Step 2: Connect the Adyen webhook

Adyen uses the webhook to tell Fixably when a customer pays a payment link and when a terminal refund is finished. Without it, these payments and refunds do not show in Fixably.

1. In System Settings > Integrations > Adyen, scroll to Webhooks. After your first save, you see these read-only fields:
   • Webhook URL
   • OAuth Client Id
   • OAuth Client Secret
   • Access Token url
2. In the Adyen Customer Area, create a new standard webhook.
3. Paste the Webhook URL from Fixably as the webhook's server address.
4. For authentication, choose OAuth 2.0 (client credentials). Paste the OAuth Client Id, the OAuth Client Secret and the Access Token url from Fixably.
5. In Adyen, generate an HMAC key for the webhook and copy it.
6. Back in Fixably, paste the key into Webhook HMAC key and click Save settings.
7. Save the webhook in the Adyen Customer Area.

For more detail on the Adyen side, see Adyen's guides on webhooks and securing webhooks.

Check it worked: use the test button in the Adyen Customer Area to send a test message to the webhook. Adyen shows whether Fixably accepted it.

Step 3: Add a payment terminal to a location

Skip this step if you only use payment links.

1. Go to System Settings > Locations.
2. Click the gear next to the location you would like to add a terminal to and click Advanced Settings.
3. Under Adyen Payment Terminals, click Add terminal.
4. Enter a Name for the terminal, for example "Front desk".
5. Enter the Terminal ID (TMS_TID). This is the terminal model and its serial number, joined by a dash, with the dashes taken out of the serial number. For example, model P630 with serial number 123-456-789 is entered as P630-123456789.
6. Click Save.

Fixably checks with Adyen that the terminal is connected to your account. When it is found, you see the message Paired terminal and the terminal shows in the list.

To remove a terminal, click Remove next to it and confirm. This only removes it from Fixably. It stays in your Adyen account.

Adyen terminals do not need to be started or set up again each day.

Step 4: Go live

When you are ready to take real customer payments:

1. Go to System Settings > Integrations > Adyen.
2. Contact support@fixably.com to change the Environment to Production.
3. Replace the Api Key, Merchant account and Webhook HMAC key with the details from your live Adyen account.
4. Make sure Active is ticked.
5. Click Save settings.
6. Set up the webhook again in your live Adyen Customer Area, as in Step 2. The Fixably webhook details stay the same.

Taking a payment on a terminal

1. On the order, click the Shopping Cart > Charge.
2. Confirm the correct payment type and terminal are selected and click Accept.
3. Complete the payment on the terminal.

While the payment is running, Fixably shows Processing payment.... Do not refresh the page, or turn off or restart the terminal, while this window is open.

When the payment is done, Fixably creates the invoice and payment, and saves the card receipt details.

Refunding a terminal payment

You start a terminal refund from the order, the same way as for other payment terminals. Adyen confirms the refund later through the webhook, so the refund stays open until that message arrives.

When Adyen answers, Fixably adds an internal note to the order:

Sending a payment link

1. Create the invoice on the order.
2. Choose Adyen as the Billing method.
3. Save the invoice.

Fixably creates a payment link in Adyen and emails it to the invoice email address. If the invoice has no email, Fixably uses the customer's email. An email note is added to the order.

When the customer pays, Adyen tells Fixably through the webhook. Fixably then:

• adds the payment to the invoice,
• marks the invoice as paid when nothing is left to pay,
• adds an internal order note called Adyen payment success.

If a payment fails, Fixably adds an internal order note called Adyen payment failed with the reason. The customer can try again with the same link until it expires.

Reference: settings

These are the fields on System Settings > Integrations > Adyen.

Troubleshooting

"OAuth client missing. Save settings to generate one"

• You have not saved the Adyen settings yet. Fill in the fields, including Webhook HMAC key, and click Save settings. The OAuth fields then show.

"The settings page does not save"

• The Webhook HMAC key is required, and Payment link expiry in days must be a number from 1 to 70. Check both fields and save again.

"Terminal with id ... not found on available terminals"

• Fixably could not find the terminal in your Adyen account. Check that:
  • the Terminal ID uses the format model-serialnumber, with the dashes taken out of the serial number,
  • the terminal is connected to your merchant account in the Adyen Customer Area,
  • the Api Key and Merchant account are for the same Adyen environment (test or live) as the terminal.

"Adyen request Unauthorized. Check your api key" or "Adyen payment terminal request Unauthorized. Check your api key"

• Adyen did not accept the API key. Check that you pasted the full key, that it belongs to the right merchant account, and that it matches the Environment (test key for Test, live key for Production).

"Failed to send Adyen payment link"

• Fixably created the payment link but could not email it. The order note includes the link, so you can copy it and send it to the customer yourself. Check that the invoice or customer has a valid email address.

"This invoice is already sent"

• A payment link was already created for this invoice. Use the existing link instead of sending a new one.
• The customer paid, but the invoice is not marked as paid
• The webhook did not reach Fixably. Check that:
  • the webhook in the Adyen Customer Area uses the Webhook URL, OAuth Client Id, OAuth Client Secret and Access Token url shown in Fixably,
  • the Webhook HMAC key in Fixably is the same as the key in Adyen,
  • the webhook is turned on in Adyen, and Adyen's webhook log shows no errors.
• Adyen retries messages that fail, so once the webhook is fixed the payment usually arrives on its own. Fixably never books the same payment twice.

A terminal refund stays open

• Terminal refunds are finished by the webhook. Check the webhook as in the entry above.

"Adyen request resulted in an unexpected response, please contact support"

• Contact Fixably support with the details below.

Getting support

Contact support@fixably.com and include:

• your tenant name,
• the order number and invoice number,
• the Terminal ID, if the problem is with a terminal,
• the exact error message, or a screenshot,
• the Adyen PSP reference of the payment, if you have it (you find it in the Adyen Customer Area).

Never send your API key, HMAC key or OAuth Client Secret by email.