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

# Payout API Authentication

> Learn how to authenticate Payout API requests

## Overview

The Payout API uses two different authentication methods depending on the operation:

1. **API Key Authentication** (Bearer Token) - For business operations
2. **Hash Authentication** - For user payout operations

## API Key Authentication

### When to Use

API Key authentication is used for **business operations** such as:

* Creating payout users
* Adding funds to existing users
* Managing payout balances
* Viewing payout user information (for business accounts)

### How It Works

Include your API key in the `Authorization` header of each request:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Getting Your API Key

<Steps>
  <Step title="Log In to Dashboard">
    Access your [Payviox Dashboard](https://dash.payviox.com)
  </Step>

  <Step title="Navigate to Developer Section">
    Go to **Developer** > **API Keys**
  </Step>

  <Step title="Copy Your API Key">
    Copy your production API key (keep it secure!)
  </Step>
</Steps>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.payviox.com/payout/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "email": "user@example.com",
      "amount": 10000
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.payviox.com/payout/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'user@example.com',
      amount: 10000
    })
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  data = {
      'email': 'user@example.com',
      'amount': 10000
  }

  response = requests.post(
      'https://api.payviox.com/payout/create',
      headers=headers,
      json=data
  )
  ```
</CodeGroup>

## Hash Authentication

### When to Use

Hash authentication is used by **payout users** to access their funds and perform operations such as:

* Viewing their payout balance
* Making withdrawals (gift cards, crypto, etc.)
* Accessing payout history

### How It Works

When you create a payout user, the API returns a unique secure hash. This hash is used to authenticate the user's requests.

### Using the Hash

The hash can be provided in three ways (in order of preference):

1. **Header** (Most Secure): `X-Payout-Hash: YOUR_HASH`
2. **Request Body**: `{"payout_hash": "YOUR_HASH"}`
3. **Query Parameter**: `?payout_hash=YOUR_HASH` (for backward compatibility)

<Warning>
  **Security Best Practice**: Always use the header method (`X-Payout-Hash`) when possible, as it's the most secure and doesn't expose the hash in URLs or request bodies.
</Warning>

### Example Request with Hash

<CodeGroup>
  ```bash cURL (Header Method - Recommended) theme={null}
  curl https://api.payviox.com/payout/operations \
    -H "X-Payout-Hash: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
    -H "Content-Type: application/json"
  ```

  ```bash cURL (Body Method) theme={null}
  curl https://api.payviox.com/payout/operations \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "payout_hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    }'
  ```

  ```bash cURL (Query Parameter - Legacy) theme={null}
  curl "https://api.payviox.com/payout/operations?payout_hash=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  ```

  ```javascript JavaScript (Header Method - Recommended) theme={null}
  const response = await fetch('https://api.payviox.com/payout/operations', {
    headers: {
      'X-Payout-Hash': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python (Header Method - Recommended) theme={null}
  import requests

  headers = {
      'X-Payout-Hash': 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://api.payviox.com/payout/operations',
      headers=headers
  )
  ```
</CodeGroup>

## Hash Characteristics

* The hash is **unique per business**: the same email for different businesses will have different hashes
* The hash is generated **server-side** and cannot be computed by the client
* Hashes are validated against active payout users only
* Expired or inactive users cannot use their hash

## Error Responses

All authentication errors return the same generic response to avoid leaking information about the cause of the failure:

```json theme={null}
{
  "error": "Unauthorized"
}
```

This error is returned when:

* The `Authorization` header or payout hash is missing
* The API key or payout hash is invalid
* The payout user is inactive

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store API Keys Securely" icon="lock">
    Never commit API keys to version control. Use environment variables or secure secret management.
  </Card>

  <Card title="Use HTTPS Only" icon="shield">
    Always make API requests over HTTPS to protect your credentials in transit.
  </Card>

  <Card title="Rotate Keys Regularly" icon="rotate">
    Periodically regenerate your API keys for enhanced security.
  </Card>

  <Card title="Protect Hash Values" icon="key">
    Treat payout hashes as sensitive credentials. Don't expose them in URLs or logs.
  </Card>

  <Card title="Use Header Authentication" icon="arrow-up">
    Prefer header-based hash authentication over query parameters or body parameters.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly check your API usage and payout operations in the dashboard.
  </Card>
</CardGroup>

## Authentication Flow

### For Business Operations

```
1. Get API Key from Dashboard
   ↓
2. Include in Authorization Header: Bearer YOUR_API_KEY
   ↓
3. Make API Request
   ↓
4. Receive Response
```

### For User Operations

```
1. Create Payout User (using API Key)
   ↓
2. Receive Hash in Response
   ↓
3. Provide Hash to User (securely)
   ↓
4. User Includes Hash in Requests (X-Payout-Hash header)
   ↓
5. User Accesses Their Funds
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Payout User" icon="user-plus" href="/api/payout/create-payout-user">
    Learn how to create payout users and allocate funds
  </Card>

  <Card title="Dashboard" icon="chart-line" href="https://dash.payviox.com">
    Manage your API keys and monitor usage
  </Card>
</CardGroup>