Card terminal
What you’ll find here
Section titled “What you’ll find here”- Pick the transport your terminal uses (LAN / WebSocket / Stripe Cloud).
- Pair the device from the dashboard or POS workspace.
- Pair with a sandbox to train cashiers.
- Read what “pending” / “captured” / “voided” mean in the order timeline.
I. Two terminal families
Section titled “I. Two terminal families”LionPOS supports two terminal transports, exposed separately in the device settings:
| Transport | When to use | Backend |
|---|---|---|
pax_lan (PAX over LAN) | A PAX terminal (A35, A920, …) on the same LAN as the lane PC, talking via the POS bridge. | Vendor Desktop ECR Hub ↔ PAX device |
codepay_ws (CodePay WebSocket) | A CodePay gateway reachable via a WebSocket URL stored on the device row. | ECR Hub relay ↔ terminal gateway |
The lane never talks to the card processor directly — the POS bridge is the relay. The terminalWsUrl (for codepay_ws) and the pax_lan LAN fields are different device properties and shouldn’t be confused.
See POS bridge & ECR Hub for the bridge setup.
II. Pair the terminal
Section titled “II. Pair the terminal”Settings → Devices → Card terminal → Add.
Fields:
| Field | What to enter |
|---|---|
| Name | Friendly name (e.g. “Lane 1 PAX”). |
| Transport | pax_lan or codepay_ws. |
| Connection | LAN IP, terminal id, or WebSocket URL depending on transport. |
| API key | Copied from the terminal gateway (regenerate via Devices → Terminal API key → Regenerate). |
| Default currency | Should match the store currency. |
| Settlement schedule | Auto-close batch at end-of-shift (POST) or daily. |
Tap Test connection — the bridge sends a no-op ping to the terminal. A green light = OK.
The endpoint is POST /api/v1/vendor/settings/devices/test-connect (see API catalog → “Vendor: Settings”).
III. Run a sandbox transaction
Section titled “III. Run a sandbox transaction”To train cashiers without charging real cards:
- Add a second terminal with transport = sandbox (or set the existing terminal to “Sandbox mode” if supported).
- The dashboard shows a yellow sandbox badge on the device card.
- Take a checkout in the POS workspace → pick the sandbox terminal → the payment goes through the test gateway.
- Sandbox sales show up in Finance → Transactions with
sandbox = trueso they don’t pollute real numbers.
IV. Card payment lifecycle
Section titled “IV. Card payment lifecycle”The order’s card payment goes through these states:
| State | What it means | Next |
|---|---|---|
pending | Terminal is asking the customer to tap / insert / swipe. | Wait for the terminal to respond. |
captured | Approved and the funds are reserved. | Order completes. |
voided | Approved then post-capture void — used when you need to refund mid-day. | Funds released. |
failed | Declined or terminal timeout. | Retry. |
You can manually mark a stuck pending as success from the order detail screen — see API catalog → POS mark-payment-success. The system also calls POST /api/v1/pos/orders/{orderId}/terminal-post-capture to send the tip / void flow after capture.
V. End-of-day settlement
Section titled “V. End-of-day settlement”When the cashier closes a shift, the bridge auto-closes the batch if the device is configured for it. Otherwise, owners can close manually:
Devices → card terminal → Close batch → POST /api/v1/vendor/settings/devices/payment-terminal/close-batch.
The batch total shows up in Finance → Transactions as one lump-sum entry.
VI. Common pitfalls
Section titled “VI. Common pitfalls”“Pending” stays for minutes. The terminal lost contact with the bridge. Check POS bridge status; if the WebSocket is down, the dashboard falls back to a manual capture flow — owner-only.
Pairing succeeds but the terminal doesn’t ring. Wrong transport selected. PAX terminals need pax_lan; CodePay gateways need codepay_ws.
API key keeps invalidating. Your terminal gateway rotates keys. Regenerate via Devices → Terminal API key → Regenerate, then paste the new value back into the device card.
Cash payment charged. The cashier selected the wrong payment method at checkout. Refund via Orders → Refund and pick card-void.