> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/guides/complete-flow.md).

# 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 Businesses

Go to **Dashboard > POS > Businesses > Create Business**.

For each physical location or POS station:

1. Enter a **Location** (e.g., "Front Counter")
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 location.

### 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 businesses:

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

See [Cashier Restrictions](https://docs.makapay.io/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 business:

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

See [Multi-Currency Support](https://docs.makapay.io/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 business:

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

When enabled, cashiers will only see the selected tokens and networks. See [Token Restrictions](https://docs.makapay.io/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 business 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 business:
   * 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 business'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 1b: (Optional) Add a Tip

If tipping is enabled on the business, the customer is asked whether they want to add a tip. They can pick a preset percentage (5%, 10%, 15% by default), type a custom amount, or choose **No tip**. The total including the tip is used for the rest of the flow. See [Tipping](https://docs.makapay.io/point-of-sale-pos/tips.md).

### 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 business shows payment status (pending > confirmed > completed)

> **Partial payments:** If the customer sends less than the requested amount, the business detects it automatically and shows a progress bar with options to collect the partial amount or wait for the remainder. See [Payment History & Recovery](https://docs.makapay.io/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 Front Counter, 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 business crashes, loses power, or the browser closes mid-payment:

1. Reopen the business 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](https://docs.makapay.io/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 businesses
* Filter by business or cashier using Order IDs
* See which cashier processed each payment
* Manage businesses and cashiers in real-time
* Reset PINs if a cashier forgets theirs
* Deactivate cashiers who leave the team

***

## Quick Reference

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
