ZenotiHelp

Processor: Adyen

ZTZenoti Docs Team Updated October 27, 2026 10 min readGuide

Adyen is a global V2 payment processor that supports in-store terminal payments, online card payments, tokenization, stored accounts, and dispute management. It is configured at the organization level and assigned to the centers that should accept Adyen transactions.

Audience: Organization administrators who configure payment processors and front-desk staff who process payments.


On this page


Before you begin

Permission: Organization administrator access is required to configure Adyen.

  • You need an active Adyen merchant account. Adyen is a V2 processor, configured at Configuration > Payments > Process payments > Payment processor onboarding.
  • Identify which centers will use Adyen before starting β€” each center must be assigned to the processor.
  • Terminal payments require a certified Adyen terminal ordered through your Adyen account manager. Verify the model is supported in your region before ordering.

Adyen capabilities in Zenoti

Capability Supported
Sale (terminal) Yes
Sale (online / HPP (Hosted Payment Page)) Yes
Refund Yes
Void Yes (routed through the refund path with the invoice-voided flag)
Pre-authorize and capture Yes
Recurring payments Yes
Stored accounts (tokenization) Yes
Global tokenization Yes β€” cards stored on one merchant account can be charged on another linked Adyen account
Swipe-to-save Yes
Auto-save card on payment Yes
Dispute management Yes
Manual card add (enter card number without a swipe/tap) No β€” use the terminal or HPP
Account health check No
BNPL (Buy Now, Pay Later) (Affirm / Afterpay / Klarna) No β€” use Stripe Connect Express for BNPL

Network requirements

Adyen terminals communicate with Adyen over the center's local network, and Zenoti communicates with Adyen over outbound HTTPS. Work with your network team to confirm both paths before the first transaction.

Connection Direction Protocol / Port Notes
Zenoti to Adyen API Outbound from Zenoti (cloud) HTTPS / 443 Managed by Zenoti; no action needed on the center network.
Zenoti to Adyen Terminal API Outbound from the center network HTTPS / 443 The POS (Point of Sale) device must reach Adyen's Terminal API endpoints.
Adyen terminal to Adyen Outbound from the center network HTTPS / 443 The terminal must resolve and reach Adyen's cloud over the shop's Wi-Fi or Ethernet.
Webhook notifications from Adyen Inbound to Zenoti HTTPS / 443 Configured in the Adyen Customer Area.

If the center network uses a proxy or firewall, whitelist Adyen's published API and Terminal API hosts. A dropped terminal-to-Adyen connection at the point of sale surfaces as a timeout in the POS; Zenoti does not retry automatically.


External-system prerequisites

These tasks happen on the Adyen side and must be completed by the merchant's Adyen administrator before the integration can be enabled.

  1. Create (or confirm) a live merchant account in the Adyen Customer Area. Separate merchant accounts are typically used per brand or legal entity.
  2. Generate an API key with the Checkout webservice role and any additional roles required for your use case (tokenization, terminal management, payouts).
  3. Generate a Client key for online/HPP payments. The client key must be allowlisted for the Zenoti-served domains used at the center.
  4. For terminal payments, request the Terminal API credentials and board each terminal against the correct merchant account and store code.
  5. Record the Merchant account name exactly as shown in the Adyen Customer Area. This is the identifier Zenoti sends on each transaction.

Configure Adyen

Connect the processor

  1. Navigate to Configuration > Payments > Process payments > Payment processor onboarding.

  2. Select Adyen.

  3. Enter your Adyen credentials.

    Field Source / Owner What to enter
    API key Adyen Customer Area > Developers > API credentials (Adyen administrator) The API key generated for Zenoti. Rotate if compromised.
    Merchant account name Adyen Customer Area > Account (Adyen administrator) The merchant account identifier β€” case-sensitive.
    Client key Adyen Customer Area > Developers > API credentials (Adyen administrator) Used by online/HPP flows; must be allowlisted for the Zenoti-served domains.
    Terminal API credentials Adyen Customer Area > Point of Sale > Terminal fleet (Adyen administrator) Only required if the center uses physical terminals.
  4. Configure terminal settings for each center that takes terminal payments. Pair each terminal to a store code in Adyen that matches the Zenoti center.

  5. Assign Adyen to the centers where it should be active.

  6. Select Save.

  7. Select Verify to confirm the credentials are valid.

Security: Credentials are encrypted at rest. Rotate the API key whenever a Zenoti or Adyen administrator with access leaves the organization.

Test the connection

After saving, run a test transaction before opening to guests:

  1. Create a test invoice for a small amount.
  2. Select Collect Payment and complete the payment using a real card on the terminal or HPP.
  3. Confirm the invoice closes and the payment appears in Zenoti's payment dashboard with an Adyen PSP reference.
  4. Immediately void or refund the test charge to return the amount to the card.
  5. Confirm the refund appears on the payment dashboard before moving on.

Important: Always complete and refund a test transaction before enabling Adyen for live guest payments. Do not leave a test charge uncancelled β€” it will appear in settlement reporting.

Tip: If the test fails, pull the PSP reference from Zenoti's payment log and search the Adyen Customer Area by that reference for the detailed error code. Common causes include a mis-typed merchant account name or an API key missing the required roles.


Process a payment with Adyen

  1. Open the POS window for the appointment or invoice.
  2. Review the invoice and select Collect Payment.
  3. Select Credit Card or the appropriate payment method.
  4. Zenoti routes the request to the paired Adyen terminal (for in-store) or the Adyen HPP (for online).
  5. The guest completes the payment on the terminal (chip, swipe, or contactless) or on the hosted page.
  6. On success, the invoice closes and the transaction appears in Zenoti's payment dashboard with the Adyen PSP reference.

Tip: For processing payments at the point of sale, see Payment processing.

Stored accounts

If Auto-save card is enabled for the center, the token returned by Adyen is saved against the guest's profile as a stored account. The stored account can be reused for recurring charges and membership renewals without re-prompting the guest for card details.

Swipe-to-save allows a guest's card to be tokenized at the time of swipe β€” the physical card details are never stored in Zenoti; only the Adyen-issued token is retained.

Global tokenization means a card stored under one Adyen merchant account can be charged on another linked Adyen account. This is useful for multi-brand organizations where a guest books across different centers operating under separate merchant accounts. Confirm that global tokenization is enabled on your Adyen contract before relying on this behavior.


Refund and void

Adyen handles voids (before settlement) and refunds (after settlement) through the same operation surface in Zenoti. The implementation sends a refund request to Adyen and flags the original authorisation as voided when applicable.

Process a refund or void

  1. Open the invoice in Zenoti.
  2. Select Refund.
  3. Choose full or partial refund and confirm the amount.
  4. Zenoti sends the refund or void to Adyen.
  5. The invoice shows the refund entry; Adyen sends an asynchronous notification confirming the outcome.

Dual-perspective behaviour

System What it records
Zenoti Refund line on the invoice; negative transaction in the payment dashboard; stored account token unchanged.
Adyen A separate refund PSP record linked to the original authorisation. For unsettled authorisations, Adyen records it as a cancel (void) instead of a refund β€” the net effect is the same on the guest statement but settlement reports differ.

Partial refunds and multiple partial refunds against the same transaction are supported up to the original captured amount. Refund finality depends on Adyen's asynchronous notification β€” the refund is provisional in Zenoti until Adyen confirms it.

Worked example

A guest is charged $120 for a facial. After the service, they report that the product add-on was not used and request a $20 refund. In Zenoti, open the closed invoice, select Refund, enter $20.00, and confirm. Zenoti sends a partial refund request to Adyen for $20. The Adyen Customer Area shows the original $120 authorisation and a $20 refund record linked by PSP reference. The Zenoti invoice shows the $20 refund line and the net $100 collected.


Edit a transaction

Whether a transaction can be edited depends on the Zenoti invoice state and the Adyen settlement state.

Zenoti invoice Adyen transaction What you can do
Open (not closed) Authorised, not captured Edit the invoice, reprice, or remove the charge. The authorisation is cancelled and a new one is created when the invoice is closed again.
Open Captured / settled Close the invoice, then use the refund flow to return the amount. Re-bill through a new invoice.
Closed Authorised, not captured Close-state edits are blocked by Zenoti. Void the invoice (which voids the authorisation) and create a new invoice.
Closed Captured / settled Close-state edits are blocked. Void the invoice β€” Zenoti posts a refund to Adyen β€” and create a new invoice with the corrected details.

Closed-invoice edits never mutate the Adyen transaction directly. The pattern is always void-and-reissue.


Reconciliation

Reconcile Adyen payments daily to catch discrepancies while they are still straightforward to investigate.

Layer Source Match key
Zenoti Collections by Invoices report filtered to the Adyen custom payment method Invoice number + Adyen PSP reference (shown on the payment record)
Adyen Customer Area > Transactions (per merchant account) PSP reference
Bank Adyen settlement batch report (Customer Area > Finance > Settlement details) Merchant reference (carries the Zenoti invoice number)

Recommended cadence: reconcile daily at end-of-day close. Investigate any Zenoti payment that does not appear in Adyen within 24 hours using the Adyen PSP reference from the Zenoti payment dashboard.


Handle transaction failures

Failure mode Symptom Resolution
Adyen unreachable Timeout or "processor unavailable" in the POS. Verify outbound HTTPS from the POS / terminal to Adyen. Retry once connectivity is confirmed. Do not re-attempt blindly β€” check the Adyen Customer Area first to confirm whether the transaction actually succeeded.
API key expired or rotated All transactions return an authentication error. Regenerate the key in the Adyen Customer Area and re-enter it in Payment processor onboarding > Adyen.
Terminal offline Terminal screen is dark or shows "not connected". Confirm Wi-Fi / Ethernet on the terminal and that it can reach Adyen's Terminal API. Re-pair if needed.
Card declined Guest-visible "Payment declined" on the terminal or HPP. Ask the guest for a different card or an alternate payment method. Adyen's response code appears on the Zenoti payment log for finance review.
Amount out of processor range Adyen returns an amount-validation error. Confirm the merchant account's transaction limits with Adyen. Split the payment across methods if the invoice exceeds the cap.
Currency mismatch Adyen returns "currency not supported for merchant account". Each Adyen merchant account is provisioned for specific currencies. Assign the correct merchant account to the center, or add the currency to the account via Adyen.
Webhook not received Refund or dispute appears in Adyen but not in Zenoti. Confirm the webhook endpoint is active in the Adyen Customer Area. Re-drive the notification from Adyen for the affected PSP reference.
Connectivity loss mid-transaction Terminal shows an interrupted or incomplete state after the guest taps or inserts their card. Do not re-attempt immediately. Check the Adyen Customer Area by the expected time window to see if the authorisation was captured. If no record exists, retry the transaction. If a record exists, do not charge the guest again β€” void it if unsettled, or refund if settled.

Tips

  • For terminal payments, ensure each terminal is bound to the correct merchant account and store code in the Adyen Customer Area β€” mis-boarded terminals succeed at the POS but post revenue to the wrong entity.
  • After any configuration change, run a small test transaction and refund it immediately. Confirm the refund lands on the card before opening to guests.
  • Global tokenization lets a card saved under one Adyen merchant account be charged on another linked account β€” useful for multi-brand organizations. Confirm this is enabled on your Adyen contract.
  • If a transaction fails, pull the PSP reference from the Zenoti payment log and search the Adyen Customer Area by that reference for the detailed error.
  • When a center changes its Adyen merchant account (for example, after a business restructure), existing stored accounts must be migrated to the new merchant account. See Card migration for the migration workflow.

Troubleshooting

Problem Likely cause Resolution
Payments succeed in the POS but no Adyen record appears Merchant account name is mis-typed and transactions are posting to a different account. Verify the merchant account name in Payment processor onboarding matches exactly what appears in the Adyen Customer Area β€” it is case-sensitive.
Terminal pairs but transactions time out Terminal cannot reach the Adyen Terminal API from the center network. Check firewall or proxy rules for the terminal's HTTPS outbound traffic. The terminal requires unrestricted outbound access to Adyen's Terminal API hosts on port 443.
Stored account charges fail after a card is replaced by the guest's bank The token on file refers to the original card and the bank has not pushed an update. The stored account can be re-captured the next time the guest visits in person. Global tokenization does not automatically update expired or replaced cards β€” re-collect card details at the next visit.
Dispute notifications not reaching Zenoti Adyen webhook endpoint is inactive or misconfigured. In the Adyen Customer Area, confirm the webhook URL for Zenoti is active and that all relevant event types are subscribed. Re-test from the Adyen notification settings and confirm the response is 200.
HPP payment redirects but invoice stays open Adyen notification confirming payment was not received by Zenoti. Check the Adyen Customer Area for the payment record. If Adyen shows success, contact Zenoti Support and provide the PSP reference so the payment can be reconciled manually.

Was this article helpful?
Your feedback helps us improve our documentation.