Terminal Simulator

Last updated: 2026-03-22

Overview

The Terminal Simulator is a virtual Westpay payment terminal that runs entirely in your browser. It connects to the Westpay backend over SignalR (WebSockets) and receives the same real-time transaction notifications that a physical terminal would receive on the shop floor.

This lets you test every aspect of your ECR integration — linking, payment flows, cancellations, error conditions — without needing access to physical hardware.

Connecting

When you open the Terminal Simulator tab, a SignalR connection is established automatically using your Subscription Key. The connection process takes a few seconds.

Once connected, the toolbar shows:

Connection ID chip — a unique identifier for this session (e.g. a1b2c3d4-...). This is the value your ECR must send in the ConnectionId request header so the backend routes transactions to your simulator instance.
Virtual terminal display — the terminal screen renders the current state

If the connection fails, a retry button is shown. The most common cause is an incorrect Subscription Key.

Toolbar Controls

The simulator toolbar exposes all the controls you need to set up and manage the virtual terminal state.

Terminal Model

Choose between two supported Westpay terminal models:

Model	Description
C100	Full-size countertop terminal
C10	Compact PIN pad terminal

The selection changes the visual appearance of the virtual terminal display.

Linked / Not Linked

Toggles whether the virtual terminal considers itself linked to a merchant account.

State	Behaviour
Not Linked (default)	Terminal shows a 6-digit Registration Code on screen. Link requests with a matching code will succeed. Purchase requests will be rejected with error code `102`.
Linked	Terminal accepts purchase, refund, and reversal requests. Link requests are rejected (already linked). Unlink requests will succeed.

You can also toggle this directly in the toolbar without going through the API — useful for resetting state between tests.

Connected / Disconnected

Simulates the physical connectivity of the terminal (e.g. network cable unplugged).

State	Behaviour
Connected (default)	Terminal processes incoming requests normally
Disconnected	All incoming requests are rejected with error code `23` (terminal offline)

Busy Indicator

While a transaction is in progress, an amber Processing badge appears. The Linked and Connected toggles are disabled while a transaction is active to prevent state conflicts.

Virtual Terminal Display

The terminal screen renders the real flow of each transaction type.

Unlinked State

When the terminal is not linked, the screen shows:

text
REGISTRATION CODE
  ┌─────────┐
  │ 4 8 3 2 9 1 │
  └─────────┘
Enter this code in your ECR to link this terminal.

A new code is generated each time the terminal transitions from Linked to Unlinked, ensuring codes cannot be reused.

Payment Flow Screens

Once linked and a purchase request arrives, the terminal steps through:

Welcome / Tap to Pay — customer presented with payment prompt
Enter PIN — PIN entry (simulated via on-screen keypad)
Confirm PIN — confirmation step
Processing — communicating with acquirer
Approved / Declined — final result displayed

You advance through the flow using the on-screen action buttons (which mirror the physical terminal buttons).

Other Transaction Screens

Transaction Type	Trigger
Refund	ECR sends a refund request
Reversal	ECR sends a reversal request
Cancellation	ECR sends a cancel request while a transaction is in progress

Transaction Sequence Panel

The left panel shows a chronological list of every transaction that has passed through this session, including:

Transaction type (Purchase, Link, Unlink, Cancel, etc.)
Timestamp
Current status

Click any transaction row to load its full request and response data in the right panel.

Request / Response Panel

The right panel shows the raw JSON for the selected transaction. Toggle between Request and Response tabs to inspect:

The full request body your ECR sent to the API
The response the API returned, including any error codes

This is the primary tool for debugging integration issues.

Registration Code Behaviour

The registration code is central to terminal linking:

The virtual terminal generates a random 6-digit code on startup
The code is displayed on the terminal screen
Your ECR must send this exact code in the registrationCode field of the link request
On a successful link, the terminal transitions to the Linked state
On unlink, a new registration code is generated automatically

When using Simulation Mode in the ECR Simulator, the registration code is read automatically from the terminal display and sent with the link request — no manual entry required.

Simulating Error Conditions

Use the toolbar controls to reproduce specific error scenarios:

Scenario	How to reproduce
Terminal offline	Toggle Disconnected before sending a request
Terminal busy	Send a purchase request, do not complete it, then send another
Already linked	Toggle Linked in the toolbar, then send a Link request from ECR
Wrong registration code	Turn Simulation Mode OFF in ECR Config, enter an incorrect 6-digit code
Invalid credentials	Enter a wrong Bearer Token in ECR Config