Payout API Authentication

Overview

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

API Key Authentication (Bearer Token) - For business operations
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:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Access your Payviox Dashboard

Navigate to Developer Section

Go to Developer > API Keys

Copy Your API Key

Copy your production API key (keep it secure!)

Example Request

curl https://api.payviox.com/payout/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "email": "[email protected]",
    "amount": 10000
  }'

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 SHA256 HMAC 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):

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

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.

Example Request with Hash

curl https://api.payviox.com/payout/operations \
  -H "X-Payout-Hash: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json"

Hash Characteristics

Consistency

The hash is deterministic: the same email address always generates the same hash
The hash is unique per business: same email for different businesses will have different hashes
The hash cannot be reverse-engineered: you cannot determine the email from the hash

Security

Hash generation uses a server-side secret key that is never exposed
Hashes are validated against active payout users only
Expired or inactive users cannot use their hash

Error Responses

Missing Authentication

{
  "error": "Unauthorized",
  "message": "Missing authorization header"
}

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Invalid or Inactive Hash

{
  "error": "Unauthorized",
  "message": "Payout hash not found or inactive"
}

Payouts Disabled

{
  "error": "Payouts are currently disabled. Please enable them in Settings."
}

Security Best Practices

Store API Keys Securely

Never commit API keys to version control. Use environment variables or secure secret management.

Use HTTPS Only

Always make API requests over HTTPS to protect your credentials in transit.

Rotate Keys Regularly

Periodically regenerate your API keys for enhanced security.

Protect Hash Values

Treat payout hashes as sensitive credentials. Don’t expose them in URLs or logs.

Use Header Authentication

Prefer header-based hash authentication over query parameters or body parameters.

Monitor Usage

Regularly check your API usage and payout operations in the dashboard.

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

API Payout - Getting Started

API Payout - Endpoints

Overview

API Key Authentication

When to Use

How It Works

Getting Your API Key

Example Request

Hash Authentication

When to Use

How It Works

Using the Hash

Example Request with Hash

Hash Characteristics

Consistency

Security

Error Responses

Missing Authentication

Invalid API Key

Invalid or Inactive Hash

Payouts Disabled

Security Best Practices

Store API Keys Securely

Use HTTPS Only

Rotate Keys Regularly

Protect Hash Values

Use Header Authentication

Monitor Usage

Authentication Flow

For Business Operations

For User Operations

Next Steps

Create Payout User

Dashboard

API Payout - Getting Started

API Payout - Endpoints

​Overview

​API Key Authentication

​When to Use

​How It Works

​Getting Your API Key

​Example Request

​Hash Authentication

​When to Use

​How It Works

​Using the Hash

​Example Request with Hash

​Hash Characteristics

​Consistency

​Security

​Error Responses

​Missing Authentication

​Invalid API Key

​Invalid or Inactive Hash

​Payouts Disabled

​Security Best Practices

Store API Keys Securely

Use HTTPS Only

Rotate Keys Regularly

Protect Hash Values

Use Header Authentication

Monitor Usage

​Authentication Flow

​For Business Operations

​For User Operations

​Next Steps

Create Payout User

Dashboard

Overview

API Key Authentication

When to Use

How It Works

Getting Your API Key

Example Request

Hash Authentication

When to Use

How It Works

Using the Hash

Example Request with Hash

Hash Characteristics

Consistency

Security

Error Responses

Missing Authentication

Invalid API Key

Invalid or Inactive Hash

Payouts Disabled

Security Best Practices

Authentication Flow

For Business Operations

For User Operations

Next Steps