What is local integration?
Local integration lets your cash register software send payment requests directly to your Vivid payment terminal over your local network (Wi-Fi or wired). The terminal still connects to Adyen’s cloud for authorisation and settlement — your software simply talks to it locally.
This guide is for merchants and their software vendors who want to set this up themselves.
Before you begin
Make sure you have:
A Vivid payment terminal is already set up and linked to your merchant account.
Cash register software that can send HTTPS requests (yours or your vendor’s).
A local network where both your cash register machine and the terminal can reach each other.
An encryption passphrase configured in the Vivid app or web (covered in Step 3).
Step 1. Set up your network
Make sure the following ports are open on your firewall:
Connection | Port | Why |
Payment terminal → Internet | TCP 443 | Terminal communicates with Adyen |
Cash register → Payment terminal | TCP 8443 | Local payment requests |
Allowlist these two domains by name (not by IP — Adyen’s IP addresses change):
*.adyen.com
*.adyenpayments.com
Two more things:
Do not configure your firewall to inspect or downgrade TLS traffic to the terminal — this will break the connection.
Give each terminal a fixed IP address (via DHCP reservation or static IP) so your cash register always knows where to find it.
Step 2. Install an Adyen library (optional but recommended)
Adyen offers free open-source libraries that take care of most of the technical work in Steps 3 and 4. If your cash register software is built on one of these platforms, we recommend using the relevant library:
Platform | Library |
Java | |
.NET | |
Node.js | |
iOS |
If your platform is not listed, you can still complete the integration manually.
Step 3. Set up encryption
To keep payment data secure on your local network, you need to set up an encryption key shared between your terminal and your cash register software. There are three parts to this.
Set up your encryption key in the Vivid app:
In the Vivid app or web, go to Payment terminal settings > Encryption key and fill in:
Key identifier — a name for your key.
Key passphrase — at least 12 characters, with at least one uppercase letter, one lowercase letter, one number, and one special character.
Key version — a version number (any positive whole number).
Tap Save. The values will be hidden after saving — use the eye icon to view them. To delete the key, clear all three fields and tap Save.
Keys take effect the next time the terminal connects to the platform, which typically happens every three hours. You can also trigger this manually via Settings on the terminal.
Install Adyen’s root certificate:
Your cash register machine needs to trust Adyen’s security certificate to verify it is talking to the correct terminal.
Download and install the certificate following the instructions for your operating system: https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local#install-root-cert
Restart your cash register software after installing.
Configure your cash register software:
Your cash register software must do two things on every payment request:
Verify the terminal’s certificate against Adyen’s root certificate. Never skip this step or fall back to an unencrypted connection.
Encrypt the request using the shared passphrase from the Vivid app.
If you are using the Adyen library from Step 2, this is handled automatically — you just provide the passphrase and the certificate path.
If you are implementing manually, follow Adyen’s encryption documentation (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local) to implement certificate pinning, key derivation, and message encryption.
Step 4. Send payment requests
Your cash register software sends payment requests to the terminal at:
The terminal responds on the same connection. If you are using the Adyen library, call the relevant sync method. If you are implementing manually, build the JSON request, encrypt it as described in Step 3, and POST it.
Step 5. Handle slow or lost connections
Payment transactions can sometimes take a while — for example, if a customer needs extra time to enter their PIN. Make sure your cash register software:
Waits at least 120 seconds before timing out a payment request.
If there is no response after 150 seconds, automatically checks Transaction Status before assuming the payment failed.
Has a manual Check last transaction option for staff to resolve unclear situations.
Logs each request and response, including the ServiceID, SaleID, and POIID — these will be needed if you contact support.
What Vivid is responsible for
Vivid provides the payment terminal and sets it up on your merchant account. Everything described in this guide — network configuration, certificates, encryption, and your cash register software — is your responsibility (or your vendor’s). Vivid does not support or certify cash register software integrations.
For help with the terminal itself — boarding, hardware, or the encryption key on the terminal side — contact Vivid support.
Important: Do not modify the payment terminal. You must not install software on it, tamper with its firmware, or interfere with its connection to Adyen. Doing so voids its certification, breaks PCI compliance, and may result in the terminal being disabled remotely.
Common questions
Does Vivid help set up my cash register software?
No — integrating your cash register software is your responsibility or your vendor’s. For technical guidance, refer to the Adyen Terminal API documentation (https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/local).
The encryption key isn’t showing on the terminal — what should I do?
Keys are applied when the terminal next connects to the platform, which typically happens every three hours. You can also trigger this manually via Settings on the terminal. If the problem continues, contact Vivid support.
Can I use a wired network?
Yes, wired and Wi-Fi networks both work, as long as the cash register machine and terminal are on the same network and the ports in Step 1 are open.
How do I update or remove the encryption key?
Go to Payment terminal settings > Encryption key in the Vivid app or web. Enter new values and tap Save to update. Clear all three fields and tap Save to remove the key.