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

# Distributors Overview

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

## What are Distributors?

Distributors are trusted intermediaries in the Universal Wallet ecosystem who facilitate cash-in and cash-out operations between the digital wallet system and physical cash. They act as human ATMs, allowing end users to convert physical cash into digital wallet balance and vice versa.

<Panel>
  ```mermaid theme={null}
  graph LR
      A[End User] -->|Gives Cash| B[Distributor]
      B -->|Credits Wallet| A
      A -->|Requests Withdrawal| B
      B -->|Gives Cash| A
  ```
</Panel>

## Core Capabilities

Distributors have several key capabilities within the platform:

### 1. Cash-In Operations

Distributors can accept physical cash from end users and credit the equivalent amount to their digital wallets. This is the primary way users add funds to their wallets.

### 2. Cash-Out Operations

Distributors can fulfill withdrawal requests by providing physical cash to end users in exchange for debiting their wallet balance.

### 3. Balance Management

Distributors maintain their own wallet balance, which must be sufficient to process cash-in operations. They need to regularly top up their balance to continue serving customers.

### 4. Transaction History

Distributors can view and track all their operations, including timestamps, amounts, and end user details.

### 5. API Integration

Distributors can programmatically interact with the platform using API keys, enabling automation and integration with external systems.

## Distributor Workflow

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

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

  <Step title="Balance Management">
    The distributor ensures sufficient balance to process cash-in operations.
  </Step>

  <Step title="Operations">
    The distributor performs cash-in and cash-out operations following the maker-checker approval pattern.
  </Step>

  <Step title="API Integration (Optional)">
    The distributor can create API keys to automate operations and integrate with external systems.
  </Step>
</Steps>

## Maker-Checker Pattern

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

* **Maker**: Creates a new operation request (cash-in, cash-out, 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

Distributors can create API keys to:

* Query their balance programmatically
* View transaction history
* Create cash-in/cash-out operations via API
* Integrate with POS systems or custom applications

Each API key has granular permissions:

* **Read Balance**: Query the distributor's wallet balance
* **Read Transactions**: View operation history
* **Perform Operations**: Create new cash-in/cash-out operations

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

Retail shops can act as distributors, allowing customers to add funds to their wallets while shopping.

### Mobile Money Kiosks

Dedicated kiosks providing cash-in/cash-out services in high-traffic areas.

### Banking Correspondents

Traditional financial institutions can deploy distributors to extend their reach.

### Integration with POS Systems

Stores can integrate distributor functionality directly into their point-of-sale systems using the API.

## Next Steps

<CardGroup cols={2}>
  <Card title="User Tutorials" icon="book" href="/distributors/tutorials/cash-in">
    Learn how to perform operations through the web interface
  </Card>

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

  <Card title="API Reference" icon="terminal" href="/api-reference/distributors/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>