Skip to main content

Integration flow

Your EPoS and the yetipay terminal talk over WebSockets — a single connection keeps everything in sync. This page walks through the conversation: what the terminal asks for, what you send back, and when.

For the full request/response shapes, see the API Reference.

The flow at a glance​

  1. Get tables — The terminal asks which tables are available. You send back the list.
  2. Lock a table — The waiter picks one; the terminal requests a lock so nobody edits the bill mid-payment.
  3. POS receipt (optional) — The terminal can ask for a receipt to print before the customer pays.
  4. Take payment(s) — The customer taps. The terminal processes one or more payments and sends you the details.
  5. Final receipt (optional) — If you want a post-payment receipt, the terminal requests it here.
  6. Unlock — The table is released; you can edit it again in your EPoS.

Transaction Flow​

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

1) Waiter fetches list of tables​

What's happening: The waiter opens the terminal to pick a table. The device sends tableListRequest. You reply with tableListResponse — an array of table IDs (or empty if none are open). If you return any tables, include the currency.

Why it matters: Your response is what the waiter sees. Reply before the timeout or the terminal will assume no tables are available.

Links: API Reference — tableListRequest, tableListResponse

2) Waiter locks a table​

What's happening: The waiter taps a table on the terminal. It sends tableLockRequest with the tableId. You reply with tableLockResponse — set confirmed to true to grant the lock, and include amount (in minor units) and currency.

Why it matters: The lock stops anyone from editing that table while payment is in progress. Confirm before the timeout or the terminal will treat the lock as failed.

Links: API Reference — tableLockRequest, tableLockResponse

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

What's happening: The waiter wants a receipt. The terminal sends posReceiptRequest. You reply with posReceiptResponse and receiptLines — an ordered list of lines (text, separators, barcodes, or images).

Why it matters: Your EPoS controls what gets printed. Miss the timeout and the terminal prints a blank receipt so the flow can continue.

Links: API Reference — posReceiptRequest, posReceiptResponse

4) Customer pays — terminal sends the result​

What's happening: The customer taps, inserts, or swipes. The terminal processes one or more payments, then sends transactionResponse with totals and a breakdown of each payment (method, scheme, amounts, auth code, and so on).

What you should do: Use this to reconcile your EPoS. If you never receive it, assume no payment went through and consider a manual reconciliation path (e.g. a supervisor override in your UI).

What happens next:

  • If you've enabled a final POS receipt, the terminal will request it (step 5).
  • Otherwise, it unlocks the table (step 6).

Links: API Reference — transactionResponse

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

What's happening: If your connection string includes final-pos-receipt, the terminal sends finalPOSReceiptRequest. You reply with finalPOSReceiptResponse — same line-based format as the pre-payment receipt.

Why it matters: Useful when the final bill differs from what you showed before payment (e.g. tips added, amounts adjusted).

Links: API Reference — finalPOSReceiptRequest, finalPOSReceiptResponse

6) Table unlock​

What's happening: When the terminal is finished (and after any final receipt), it sends tableUnlock. The table is editable again in your EPoS.

Links: API Reference — tableUnlock

Errors and resilience​

  • Connection dropped: If you get a "connection discontinued" error, finish any in-flight flows, then reconnect. Don't start new flows on the old socket.
  • Timeouts: If you miss a timeout, the terminal falls back safely (e.g. blank receipt, no tables).
  • Error messages: When something goes wrong, you'll get errorMessage with a code and message. Some include a userMessage — show that to staff (e.g. "Terminal unavailable").

See errorMessage in the API Reference for the full list.