API

Add on : Security, signature and HTTPS

View as Markdown

Overview

The Local API uses HTTP by default, which is enough for a secured network between the cash register and the terminal. When more security is required, two options are available, from the strongest to the lightest:

  1. HTTPS on port 16126, through certified Yavin hostnames resolved by your local DNS
  2. Signature verification over HTTP, to guarantee the response payload has not been tampered with

HTTPS

Yavin terminals can expose both ports, so a cash register can choose the protocol per point of sale:

ProtocolPort
HTTP16125
HTTPS16126

Port 16126 is opened only if the terminal has retrieved its HTTPS certificate from the Yavin backend. This requires network access when the terminal starts for the first time, and the certificate is renewed periodically. Without a certificate, the terminal starts in HTTP only, without any warning.

If you implement HTTPS, we highly recommend you also implement HTTP, to be able to install points of sale that cannot handle HTTPS for operational reasons.

For HTTPS, the cash register must connect through one of the Yavin hostnames listed below. The partner's router or local DNS server maps that hostname to the terminal's local IP address.

Production hostnames

Sandbox hostnames

The partner can connect many cash registers to many terminals locally. For example:

No public DNS A or CNAME record is required for these hostnames. They are intended to resolve locally at the partner site.

Text
tpe-local-1.p.yavin.com
tpe-local-2.p.yavin.com
...
tpe-local-20.p.yavin.com
Text
tpe-local-1.sandbox.yavin.com
tpe-local-2.sandbox.yavin.com
...
tpe-local-20.sandbox.yavin.com
Text
tpe-local-3.p.yavin.com  -> 192.168.1.103  -> Terminal A
tpe-local-7.p.yavin.com  -> 192.168.1.107  -> Terminal B

Prerequisites

  • The cash register and the Yavin terminal are connected to the same local network
  • The terminal has a stable local IP address, preferably through DHCP reservation
  • The device or router supports local DNS overrides / split-horizon DNS, or the site has another local DNS resolver
  • The partner has chosen one available hostname per HTTPS terminal

Choosing HTTP or HTTPS

Cash register software can choose which local port to use:

Use HTTP when the local integration does not require TLS:

Use HTTPS when TLS is required. For HTTPS, do not connect with the raw IP address; use the chosen hostname:

Text
http://<terminal-local-ip>:16125/
https://<chosen-hostname>:16126/
Text
http://192.168.1.103:16125/
Text
https://tpe-local-3.p.yavin.com:16126/

Router configuration for HTTPS

For HTTPS, the router must answer local DNS queries for each chosen hostname with the terminal's LAN IP.

Recommended setup:

  1. Create a DHCP reservation for each terminal so its local IP stays stable
  2. Add a local DNS override for each chosen hostname

Example with three terminals:

Example dnsmasq entries:

This makes DHCP changes invisible to cash registers: the terminal keeps the same reserved IP, and the hostname always resolves to that IP.

Text
tpe-local-3.p.yavin.com   -> 192.168.1.103
tpe-local-7.p.yavin.com   -> 192.168.1.107
tpe-local-12.p.yavin.com  -> 192.168.1.112
Text
address=/tpe-local-3.p.yavin.com/192.168.1.103
address=/tpe-local-7.p.yavin.com/192.168.1.107
address=/tpe-local-12.p.yavin.com/192.168.1.112

Cash register configuration

For HTTP:

For HTTPS:

One cash register can connect to one terminal. Multiple cash registers can also connect to the same terminal by using the same hostname. Multiple terminals at the same site should use different hostnames from the available set.

Text
http://192.168.1.103:16125/
Text
https://tpe-local-3.p.yavin.com:16126/

Verification

From a machine using the same router / DNS resolver as the cash register, check that the HTTPS hostname resolves locally:

Expected result: it resolves to the terminal's reserved local IP.

Check the HTTP Local API:

Check the HTTPS Local API:

Expected result:

If the hostname resolves without editing /etc/hosts, the router DNS setup is working.

cURL
ping tpe-local-3.p.yavin.com
cURL
curl http://192.168.1.103:16125/localapi/v4/ping
cURL
curl https://tpe-local-3.p.yavin.com:16126/localapi/v4/ping
JSON
{"status": "ok"}

Troubleshooting

SymptomLikely causeFix
HTTP works but HTTPS does notDNS override missing or wrong hostname usedCheck the local DNS entry and use the chosen hostname on port 16126
tpe-local-3.p.yavin.com does not resolveRouter DNS override missingAdd the local DNS override
Hostname resolves to the wrong IPWrong DNS override or DHCP reservationCheck the terminal's reserved IP and router DNS entry
Certificate errorCash register connects by raw IP or wrong hostnameUse one of the certified hostnames, eg https://tpe-local-3.p.yavin.com:16126/
Connection refusedTerminal service not running, wrong port, firewall, or (on port 16126 only) the terminal has no HTTPS certificate and runs in HTTP onlyCheck terminal status, port, and local firewall. If HTTP on 16125 works but 16126 is refused, make sure the terminal had network access at start-up to retrieve its certificate
Hostname worked before but no longer reaches the terminalTerminal IP changedAdd or fix the DHCP reservation
Two terminals answer on the same hostnameDuplicate router DNS assignmentAssign each terminal a different hostname

Fallback: hosts file

If the router cannot configure local DNS overrides, a hosts file can be used on each cash register machine. This is a fallback and is not recommended for multi-register or multi-terminal sites.

Windows (C:\Windows\System32\drivers\etc\hosts, opened as Administrator):

Flush DNS:

macOS / Linux (/etc/hosts):

macOS flush:

If the terminal IP changes, every hosts file entry must be updated. Prefer DHCP reservation plus router DNS whenever possible.

Text
192.168.1.103   tpe-local-3.p.yavin.com
cURL
ipconfig /flushdns
Text
192.168.1.103   tpe-local-3.p.yavin.com
cURL
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Known limitations

  • The current certificate covers 20 hostnames for production and 20 hostnames for sandbox
  • The partner is responsible for choosing which hostname maps to which terminal
  • Router support for local DNS overrides varies by model
  • iPad, iPhone and Android devices do not provide a simple editable hosts file: router DNS or MDM-managed DNS is required. Another option for these devices is to stay in HTTP and validate the signature of the responses (see below)

Signature

If HTTPS is too complex to set up at a point of sale, the cash register can use signature verification over HTTP. Even if a man in the middle could see the traffic, verifying the signature guarantees the payload has not been compromised. Signature is optional: the terminal adds a Yavin-Signature header only when response signature is enabled for your company (company setting verify_local_api_signature, contact Yavin support to enable it) and the terminal holds the company secret key. The setting is retrieved when the merchant logs in to Yavin Pay and applied when the Local API server starts.

Scope of the signature. Only JSON response bodies are signed. HTTP 400 or 500 errors returned without a JSON body are not signed. If the Yavin-Signature header is absent, the response is not signed: never treat it as verified. If your integration requires signed responses, reject any response without the header.

The signature is computed as follows:

Where:

  • yavin_secret_key is the company's API key, available in MyYavin under Settings > API > API key (one key per company)
  • response_payload is the raw JSON response body as a string

To verify a response, recompute the signature on your side and compare it with the Yavin-Signature header.

Python
import hashlib

signature = hashlib.sha256(
    '|'.join([yavin_secret_key, response_payload]).encode('utf-8')
).hexdigest()

In-store payment: Local API

Add on : Protocole Bonjour