> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uw.stargate.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchants Overview

> Understanding the role and capabilities of merchants in the Universal Wallet platform

## What are Merchants?

Merchants are businesses in the Universal Wallet ecosystem that accept digital payments from wallet holders. They receive funds directly into their merchant wallet and can track payment history, manage payouts, and integrate with external systems via API.

<Panel>
  ```mermaid theme={null}
  graph LR
      A[Wallet Holder] -->|Pays Merchant| B[Merchant]
      B -->|Receives Payment| C[Merchant Wallet]
      C -->|Payout| D[Bank Account]
  ```
</Panel>

## Core Capabilities

Merchants have several key capabilities within the platform:

### 1. Accept Payments

Merchants receive payments from wallet holders using their short code or QR code. Payments are credited instantly to the merchant wallet.

### 2. Payout Operations

Merchants can request payouts to transfer funds from their merchant wallet to their bank account or other destinations.

### 3. Balance Management

Merchants can monitor their wallet balance in real-time through the dashboard or API.

### 4. Payment History

Merchants can view and search their complete payment history, including timestamps, amounts, and sender details.

### 5. API Integration

Merchants can programmatically query their balance and payment history using API keys, enabling integration with POS systems, accounting software, and custom dashboards.

## Merchant Workflow

<Steps>
  <Step title="Onboarding">
    A merchant is created by an issuer with a unique ID, name, short code, and super admin mobile phone number.
  </Step>

  <Step title="User Assignment">
    Users are assigned roles within the merchant organization (admin, maker, checker, viewer).
  </Step>

  <Step title="Accept Payments">
    Wallet holders pay the merchant using the merchant's short code or QR code.
  </Step>

  <Step title="Manage Funds">
    The merchant monitors balance and requests payouts as needed.
  </Step>

  <Step title="API Integration (Optional)">
    The merchant can create API keys to automate balance checks and payment tracking.
  </Step>
</Steps>

## Maker-Checker Pattern

All merchant operations follow a maker-checker approval pattern for enhanced security:

* **Maker**: Creates a new operation request (payout, API key creation, etc.)
* **Checker**: Reviews and approves or rejects the request
* **Segregation of Duties**: The same user cannot be both maker and checker for the same operation

This dual-control mechanism prevents fraud and ensures accountability.

## API Access

Merchants can create API keys to:

* Query their balance programmatically
* View payment history with search and pagination
* Integrate with POS systems or accounting software

Each API key has granular permissions:

* **Read Balance**: Query the merchant's wallet balance
* **Read Transactions**: View payment history
* **Perform Operations**: Create new operations (payouts, etc.)

API keys can also have restrictions:

* **Transaction Limits**: Maximum amount per transaction
* **Daily Volume Limits**: Maximum daily transaction volume
* **IP Whitelisting**: Restrict access to specific IP addresses
* **Expiration**: Keys automatically expire after a set period

## Security Features

### Multi-Level Authentication

* SMS verification for initial login
* TOTP (Time-based One-Time Password) for 2FA
* Session management with secure tokens

### Access Control

* Role-based permissions (admin, maker, checker, viewer)
* Feature-level access control
* Audit trails for all operations

### API Security

* API keys with SHA-256 hashing
* Scoped permissions per key
* IP whitelisting support
* Rate limiting and usage tracking

## Use Cases

### Retail Stores

Physical stores accepting digital wallet payments at the point of sale.

### Online Marketplaces

E-commerce platforms integrating merchant payments via the API.

### Service Providers

Utility companies, subscription services, and other recurring payment collectors.

### Integration with Accounting Systems

Merchants can pull payment data via API into their accounting or ERP systems for automated reconciliation.

## Next Steps

<CardGroup cols={2}>
  <Card title="User Tutorials" icon="book" href="/merchants/tutorials/view-payments">
    Learn how to manage your merchant account through the web interface
  </Card>

  <Card title="API Tutorials" icon="code" href="/merchants/api-tutorials/api-keys">
    Get started with the Merchant API for programmatic access
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/merchants/authentication">
    Detailed API endpoint documentation and specifications
  </Card>

  <Card title="Security" icon="shield" href="/concepts/maker-checker">
    Understand security features and best practices
  </Card>
</CardGroup>