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

# Processors

> Payment processor (merchant) management

<Info>
  Processors are merchants who accept NFC card payments via POS terminals. Each processor gets API credentials for integration.
</Info>

## Processor Lifecycle

<Steps>
  <Step title="Registration">
    Admin creates processor with business details
  </Step>

  <Step title="Credentials Issued">
    API key and HMAC secret generated for POS integration
  </Step>

  <Step title="Processing Payments">
    Processor accepts card payments via POS terminal
  </Step>

  <Step title="Funds Settlement">
    Processor can transfer funds or request reclaim
  </Step>
</Steps>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Processor" icon="plus" color="#10b981" href="/api-reference/processors/create">
    `POST /api/v1/processors`

    Register new processor with credentials
  </Card>

  <Card title="Get Processor" icon="search" color="#6366f1" href="/api-reference/processors/get">
    `GET /api/v1/processors/:id`

    Retrieve processor details
  </Card>

  <Card title="List Processors" icon="list" color="#8b5cf6" href="/api-reference/processors/list">
    `GET /api/v1/processors`

    List all processors with pagination
  </Card>

  <Card title="Suspend Processor" icon="pause" color="#ef4444" href="/api-reference/processors/suspend">
    `POST /api/v1/processors/:id/suspend`

    Suspend processor from processing
  </Card>

  <Card title="Transfer Funds" icon="arrow-right" color="#f59e0b" href="/api-reference/processors/transfer">
    `POST /api/v1/processors/:id/transfer`

    Transfer to subscriber account
  </Card>

  <Card title="Transaction History" icon="history" color="#ec4899" href="/api-reference/processors/transactions">
    `GET /api/v1/processors/:id/transactions`

    View processor transaction history
  </Card>
</CardGroup>

<Card title="Request Reclaim" icon="undo" href="/api-reference/processors/reclaim">
  `POST /api/v1/processors/:id/reclaim` - Submit fund withdrawal request for admin review
</Card>

***

## API Credentials

When a processor is created, they receive:

<CardGroup cols={3}>
  <Card title="API Key" icon="key">
    `olive_pos_live_xxxxx`

    For POS terminal authentication
  </Card>

  <Card title="HMAC Secret" icon="lock">
    `secret_xxxxx`

    For signing requests
  </Card>

  <Card title="Dashboard Login" icon="user">
    Email + password for web dashboard
  </Card>
</CardGroup>

<Warning>
  API key and HMAC secret are only shown **once** at creation. Store them securely!
</Warning>

***

## Processor Status

<Tabs>
  <Tab title="Active">
    | Status                     | Description                   |
    | -------------------------- | ----------------------------- |
    | `active`                   | Can process payments normally |
    | Can login to dashboard     |                               |
    | Can transfer/reclaim funds |                               |
  </Tab>

  <Tab title="Suspended">
    | Status                           | Description               |
    | -------------------------------- | ------------------------- |
    | `suspended`                      | All transactions rejected |
    | Dashboard access blocked         |                           |
    | API key deactivated              |                           |
    | Must contact admin to reactivate |                           |
  </Tab>
</Tabs>

***

## Reclaim Flow

Processors can request to withdraw funds from their account:

<Steps>
  <Step title="Submit Request">
    Processor submits reclaim request with amount
  </Step>

  <Step title="Pending Review">
    Request status is `pending`
  </Step>

  <Step title="Admin Review">
    Admin approves or rejects request
  </Step>

  <Step title="Funds Transferred">
    On approval, funds transferred to designated account
  </Step>
</Steps>

***

## Response Examples

<Tabs>
  <Tab title="Create Processor">
    ```json theme={null}
    {
      "success": true,
      "processor_id": "proc_abc123",
      "message": "Processor created successfully",
      "api_key_id": "key_xyz789",
      "api_key": "olive_pos_live_xxxxxx",
      "hmac_secret": "secret_xxxxxx",
      "warning": "Save credentials - they won't be shown again!"
    }
    ```
  </Tab>

  <Tab title="Processor Details">
    ```json theme={null}
    {
      "processor": {
        "id": "proc_abc123",
        "name": "Smart PAY Merchant",
        "phone_number": "+23277123456",
        "email": "merchant@smartpay.sl",
        "account_id": "acc_xyz789",
        "status": "active",
        "created_at": "2025-01-15T10:30:00Z"
      }
    }
    ```
  </Tab>

  <Tab title="Transactions">
    ```json theme={null}
    {
      "success": true,
      "transactions": [
        {
          "id": "txn_abc123",
          "type": "pos_payment",
          "amount": "150.00 SLE",
          "fee": "1.50 SLE",
          "status": "completed",
          "created_at": "2025-01-15T10:30:00Z"
        }
      ],
      "total_count": 500
    }
    ```
  </Tab>
</Tabs>

***

## Integration

<CardGroup cols={2}>
  <Card title="POS Integration Guide" icon="store" href="/guides/pos-integration">
    Complete guide for integrating POS terminals
  </Card>

  <Card title="API Authentication" icon="key" href="/api-reference/authentication">
    Learn about API key and HMAC authentication
  </Card>
</CardGroup>