Skip to main content

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.

​
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: 
Authorization: Bearer YOUR_API_KEY

​
Getting Your API Key

1

Log In to Dashboard

Access your Payviox Dashboard
2

Navigate to Developer Section

Go to Developer > API Keys
3

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": "user@example.com",
    "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 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)
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

  • 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: 
{
  "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

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

​
Next Steps

Create Payout User

Learn how to create payout users and allocate funds

Dashboard

Manage your API keys and monitor usage