Skip to main content

PAT WebSocket API

This page explains how a POS communicates with yetipay over WebSockets for Pay‑at‑Table (PAT). If you want the full request/response shapes, jump to the specs:

API Specifications​

How the PAT flow works (high level)​

  1. Get tables – The terminal asks the EPoS which tables it’s allowed to lock.
  2. Lock a table – The terminal claims one table so nobody else edits it mid‑payment.
  3. Get a POS receipt (optional) – The terminal can print the EPoS receipt before payment.
  4. Take payment(s) – The terminal processes one or more payments and reports them back.
  5. Final receipt (optional) – If enabled, the terminal prints a final EPoS receipt after payment.
  6. Unlock – The table is released so the EPoS can be edited again.

Transaction Flow (PAT)​

The Pay‑At‑Table transaction flow between EPoS, Server, and Terminal.

1) Waiter fetches list of tables​

What’s happening: When the PDQ needs to show open tables, it sends tableListRequest. You respond with tableListResponse containing an array of table IDs. If there are no tables, return an empty array. If you return any tables, include the currency.

Why it matters: This is the source of truth for what the waiter sees on the PDQ. If you don’t reply before timeout, the PDQ assumes no tables are available.

Tip: — click a step to jump to the spec.

Links:

2) Waiter locks a table​

What’s happening: After the waiter picks a table on the PDQ, it sends tableLockRequest with the tableId. You reply with tableLockResponse and set confirmed to true to grant the lock. If true, also include amount (in minor units) and currency.

Why it matters: Locking prevents the EPoS from changing that table while the PDQ is taking payment. If you don’t confirm in time, the PDQ treats the lock as failed.

Tip: — click a step to jump to the spec.

Links:

3) Terminal requests a POS receipt (optional, often before payment)​

What’s happening: If the waiter wants a receipt printed on the PDQ, the terminal sends posReceiptRequest. You respond with posReceiptResponse containing receiptLines—an ordered list of printable lines (text, graphic separators, barcode, or image).

Why it matters: This lets the PDQ print an EPoS‑formatted receipt. If you don’t answer in time, the PDQ prints a blank receipt so the flow doesn’t block.

Tip: — click a step to jump to the spec.

Links:

4) Waiter completes the PAT sale on the PDQ​

What’s happening: The PDQ takes one or more payments and then sends transactionResponse. It includes totals plus a breakdown of each payment (method, scheme, amounts, auth code, etc.).

What you should do: Use this to reconcile your EPoS state. If you never receive it, assume no payments occurred and consider allowing a manual reconciliation flow in your UI (e.g., supervisor action).

Next step depends on settings:

  • If final POS receipt is enabled, the PDQ will request it (see step 5).
  • Otherwise, it will unlock the table (see step 6).

Tip: — click a step to jump to the spec.

Links:

5) Final POS receipt (optional, after payment)​

What’s happening: If the connection string includes final-pos-receipt, the PDQ sends finalPOSReceiptRequest. You respond with finalPOSReceiptResponse, same line‑based format as the earlier receipt.

Why it matters: This lets you print a receipt that reflects the final, paid state (useful if your pre‑payment receipt is different from your final).

Links:

6) Table unlock​

What’s happening: When the PDQ is done (and after any final receipt), it sends tableUnlock so the EPoS can make the table editable again.

Links:

Errors & resilience​

  • If something goes wrong, you’ll receive errorMessage with a code and message. Some errors include a userMessage you should surface directly to staff (e.g., terminal unavailable).
  • Timeouts: If you don’t respond before timeout, the terminal carries on with a safe default (e.g., blank receipt, no tables).
  • Connection discontinued: If you get a “connection discontinued” error, ongoing flows complete, but don’t start new flows on that socket; reconnect.

See the Error Codes section in the EPoS PAT spec for details.