Terminal API

Your till says charge. The terminal takes the tap.

A small REST API that lets any EPOS, booking system or kiosk send a payment to a paired terminal and hear back the result.

Start free trial Book a demo

# Your till asks a paired terminal to take £45.00
POST /v1/terminal/payment-requests
Authorization: Bearer yk_live_…
Idempotency-Key: till-7f3a-0192

{
  "device_label": "Counter 1",
  "amount_pence": 4500,
  "reference": "Table 12"
}

# Then: signed webhook, or listen on SSE
GET /v1/terminal/events   text/event-stream
Yeya-Signature: t=1727164800,v1=9c1f…

The flow

Five hops, one of them in your code.

1TillPOST payment-request
2Yeyaqueues for the device
3Terminalstaff confirms, customer taps
4Viva.comauthorises
5Your serverwebhook or SSE: approved

Amounts are integers in pence. Yeya never calls Viva.com while a database transaction is open; every outcome is recorded before it is reported.

Pair once, address by device

Each terminal gets a device id and label when it pairs. Your till sends requests to it; nothing on the device holds an ISV credential.

Idempotent by design

Send an Idempotency-Key with every request. A retry after a timeout returns the original request, never a second charge.

Signed webhooks

Every event carries a Yeya-Signature header (timestamp and HMAC-SHA256). Verify it and reject stale timestamps.

Server-sent events

No public endpoint? Hold open GET /v1/terminal/events and receive the same events as a stream.

Refunds from the till

POST /v1/terminal/refunds against the original payment, with the amount in pence.

Scoped API keys

Keys are per merchant, created in the portal, revocable at any time and shown once.

Shop network mode

Or skip the cloud and talk to the payment device.

A till on the shop's own network can send the request straight to the payment device. It is the fastest route, and the device does not keep a connection open to Yeya waiting for requests. The merchant chooses Shop network or Cloud under Integrations in their portal.

Find the payment device

GET /v1/terminal/devices lists each payment device with its address on your shop's network: its own name, host_url (https://<name>:9565), and its IP, https://<payment device IP>:9565, or null when it cannot be reached.

Trusted, or pinned

Each payment device's name has a publicly trusted certificate, so any till that can use https connects with nothing to set up. A till that pins can use the IP and trust only the SHA-256 fingerprint from that same list, so nothing else on the Wi-Fi can pose as the payment device.

Send the same request

Same API key, same JSON, same Idempotency-Key, same responses. Yeya stays the record: fees, receipts, webhooks and events work exactly as they do through the cloud.

The device passes each call on to Yeya with your key and never stores it. A till can always use the cloud API above instead, in either setting.

Put your brand on the counter.

Create your partner account in two minutes. Everything works for 14 days, including demo payments.

Start free trial Book a demo