# POS Guide

This is a step-by-step walkthrough of the entire POS system, from initial setup to accepting payments.

## End-to-End Overview

> **Setup (once)** --> **Cashier logs in** --> **Creates payment** --> **Customer pays** --> **Payment tracked**

***

## Phase 1: Merchant Setup (One-Time)

The merchant does this from the main dashboard, logged in with their account.

### Step 1: Create Terminals

Go to **Dashboard > POS > Terminals > Create Terminal**.

For each physical register or POS station:

1. Enter a **name** (e.g., "Register 1")
2. Enter a **short code** (e.g., `R1`) -- this is an identifier, not a password
3. Select the **merchant wallet address** to receive payments
4. Optionally set a default blockchain network and token
5. Click **Create**

Repeat for each register.

### Step 2: Create Cashiers

Go to **Dashboard > POS > Cashiers > Create Cashier**.

For each staff member:

1. Enter their **name** (e.g., "John Doe")
2. Enter a **short code** (e.g., `JD`) -- used in order tracking
3. Enter a **PIN** -- must be **8+ digits, numbers only**
4. Click **Create**
5. Share the PIN with the cashier privately

Repeat for each staff member.

### Step 3: (Optional) Set Cashier Restrictions

If you want to limit which cashiers can use which terminals:

1. Go to **Dashboard > POS > Terminals**
2. Click **Edit** on a terminal
3. Toggle on only the cashiers who should access this terminal
4. Click **Save**

See [Cashier Restrictions](/point-of-sale-pos/cashier-restrictions.md) for details.

### Step 3b: (Optional) Configure Currencies

If your business operates outside the US or serves international customers:

1. Go to **Dashboard > POS > Currencies**
2. Enable the currencies you need (e.g., EUR, GBP, JPY)
3. Set your **default currency**
4. Click **Save Currency Settings**

Then for each terminal:

1. Go to **Dashboard > POS > Terminals**
2. Click **Edit** on a terminal
3. Set the terminal's **default currency** (e.g., EUR for a Paris location)
4. Optionally enable **Allow cashier to switch currency** for tourist-facing terminals
5. Click **Save**

See [Multi-Currency Support](/point-of-sale-pos/multi-currency.md) for details on supported currencies, exchange rates, and zero-decimal currencies.

### Step 3c: (Optional) Set Token Restrictions

If you want to limit which tokens are available on a terminal:

1. Go to **Dashboard > POS > Terminals**
2. Click **Edit** on a terminal (or configure during creation)
3. Toggle on **Restrict Available Tokens**
4. Select the tokens you want this terminal to accept
5. Click **Save**

When enabled, cashiers will only see the selected tokens and networks. See [Token Restrictions](/point-of-sale-pos/token-restrictions.md) for details.

### Step 4: Set Up the Device

On your POS device (tablet, phone, laptop):

1. Open a browser
2. Navigate to the terminal URL: `https://your-domain.com/pos/{terminalId}`
3. Bookmark it or add to home screen
4. Use **fullscreen mode** for the best experience
5. The PIN login screen appears -- ready for cashiers

***

## Phase 2: Cashier Login

This happens at the start of a shift or after a session expires.

1. Cashier sees the **PIN keypad** on screen
2. Cashier enters their **8+ digit PIN** using the on-screen number pad
   * Only digits are shown -- no letters, no special characters
3. If the PIN is valid and the cashier is allowed on this terminal:
   * Login succeeds
   * 15-minute session starts
   * Payment screen appears
4. If the PIN is invalid or cashier is not allowed:
   * Error message is shown
   * Cashier can try again

***

## Phase 3: Creating a Payment

Once logged in, the cashier creates payments for customers.

### Step 1: Enter Amount

1. The payment creation screen shows a **numeric keypad** in the terminal's configured currency
2. If currency switching is enabled, the cashier can tap a different currency pill at the top
3. Cashier enters the amount (e.g., `50.00` EUR or `1500` JPY)
4. Clicks **Next** or **Continue**

### Step 2: Select Network & Token

1. Choose the **blockchain network** (e.g., Ethereum, Polygon, Base)
2. Choose the **token** (e.g., USDC, USDT, ETH)
3. If a non-stablecoin is selected, the system calculates the equivalent amount at current price
4. Clicks **Create Payment**

### Step 3: Customer Pays

1. A **QR code** is displayed on screen
2. Below the QR, the wallet address is shown in truncated form -- tap it to **reveal the full address** (useful for customers who cannot scan)
3. The customer scans the QR code with their crypto wallet
4. The customer confirms the payment in their wallet
5. The terminal shows payment status (pending > confirmed > completed)

> **Partial payments:** If the customer sends less than the requested amount, the terminal detects it automatically and shows a progress bar with options to collect the partial amount or wait for the remainder. See [Payment History & Recovery](/point-of-sale-pos/payment-history.md) for details.

### Step 4: Order ID is Generated

The system automatically creates an Order ID:

```
POS-R1-JD-1707842400000
```

This links the payment to Register 1, cashier John Doe, at the exact timestamp.

***

## Payment Flow Summary

| #  | Who        | Action                                                         |
| -- | ---------- | -------------------------------------------------------------- |
| 1  | Cashier    | Enters PIN on numeric keypad                                   |
| 2  | Server     | Verifies PIN, finds matching cashier                           |
| 3  | Server     | Creates session (15 min)                                       |
| 4  | Cashier    | Enters payment amount in configured currency (e.g., EUR 50.00) |
| 5  | Cashier    | Selects network and token                                      |
| 6  | Server     | Generates Order ID (`POS-R1-JD-17078...`)                      |
| 7  | Server     | Creates QR code                                                |
| 8  | Customer   | Scans QR code with wallet                                      |
| 9  | Customer   | Confirms and sends payment                                     |
| 10 | Blockchain | Confirms transaction                                           |
| 11 | Server     | Marks payment complete                                         |

***

## Phase 4: Session Management

During the shift:

* The **countdown timer** shows remaining session time
* Every action (entering amounts, creating payments) **resets the timer** to 15 minutes
* If the cashier is idle for 15 minutes, they are **automatically logged out**
* A **warning** appears when less than 60 seconds remain
* The cashier can **manually log out** at any time (e.g., end of shift, break)
* The **History** button (clock icon) lets cashiers view their payment history and resume pending payments

### Payment Recovery

If the terminal crashes, loses power, or the browser closes mid-payment:

1. Reopen the terminal and log in
2. Tap the **History** button in the header
3. Find the pending payment and tap **Resume**

The original payment is restored -- same QR code, same address, same amount. See [Payment History & Recovery](/point-of-sale-pos/payment-history.md) for full details.

***

## Phase 5: Merchant Monitoring

The merchant can monitor all activity from the dashboard:

* View all payments across terminals
* Filter by terminal or cashier using Order IDs
* See which cashier processed each payment
* Manage terminals and cashiers in real-time
* Reset PINs if a cashier forgets theirs
* Deactivate cashiers who leave the team

***

## Quick Reference

| Action            | Where                                  | Who      |
| ----------------- | -------------------------------------- | -------- |
| Create terminal   | Dashboard > POS > Terminals            | Merchant |
| Create cashier    | Dashboard > POS > Cashiers             | Merchant |
| Set restrictions  | Dashboard > POS > Terminals > Edit     | Merchant |
| Reset PIN         | Dashboard > POS > Cashiers > Reset PIN | Merchant |
| Login to terminal | Terminal URL (/pos/{id})               | Cashier  |
| Create payment    | Terminal (after login)                 | Cashier  |
| View payments     | Dashboard > Payments                   | Merchant |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.makapay.io/guides/complete-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.