Skip to main content

​
API Key Authentication

All API requests must be authenticated using your API key. You can find your API keys in the Payviox Dashboard under the Developer section.
Keep your API keys secure! Never share your Secret API Key in publicly accessible areas such as GitHub, client-side code, and so forth.

​
API Key Types

Payviox provides two types of API keys for different integration scenarios:

Public API Key

For client-side / SDK integration
  • Used in browser via JavaScript SDK
  • Client IP is automatically captured from the request
  • Safe to expose in frontend code
  • Ideal for: websites, single-page apps

Secret API Key

For server-side integration
  • Used from your backend server
  • Allows providing client IP manually via ip parameter
  • Must NEVER be exposed in client-side code
  • Ideal for: APIs, mobile backends, server apps

​
When to use which key?

Use CaseKey TypeIP Handling
JavaScript SDK in browserPublic KeyAuto-captured
Direct API call from frontendPublic KeyAuto-captured
Backend creates session for userSecret KeyProvide via ip param
Mobile app via backendSecret KeyProvide via ip param
Server-to-server integrationSecret KeyOptional ip param
When using the Secret API Key, you can optionally provide the end-user’s IP address using the ip parameter in the Create Session request. If provided, this IP will be validated when the user completes payment to prevent fraud.

​
Using the API Playground

Each endpoint in this documentation includes an interactive playground where you can test API calls directly from your browser.
1

Get Your API Key

Copy your API key from the Payviox Dashboard
2

Open an Endpoint

Navigate to any endpoint page (e.g., Create Session)
3

Enter Your API Key

In the playground on the right, paste your API key in the Authorization field
4

Fill Request Body

Complete the required parameters in the request body
5

Send Request

Click Send to test the API call in real-time
The playground automatically adds “Bearer ” prefix to your API key in the Authorization header.

​
How to Authenticate

Include your API key in the Authorization header of each request: 
Authorization: Bearer pk_live_xxxxxxxxxxxx
Public keys typically start with pk_ and Secret keys with sk_. Both work with the same endpoints, but Secret keys unlock additional parameters like ip.

​
Example Request

curl https://api.payviox.com/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "customer": "customer_abc123",
    "order_id": "order_123",
    "items": [
      {
        "name": "Product 1",
        "quantity": 1,
        "price": 10000
      }
    ]
  }'

​
API Key Management

​
Getting Your API Keys

  1. Log in to your Payviox Dashboard
  2. Navigate to Developer > API Keys
  3. Copy your keys:
    • Public API Key: For frontend/SDK integration
    • Secret API Key: For backend/server-side integration

​
Regenerating API Keys

If your API key has been compromised, you can regenerate it from the dashboard:
1

Access Developer Settings

Go to Developer > API Keys in your dashboard
2

Regenerate Key

Click Regenerate API Key
3

Update Your Integration

Update your integration with the new API key
When you regenerate an API key, the old key will stop working immediately. Make sure to update your integration before regenerating.

​
Error Responses

If authentication fails, you’ll receive one of the following responses:

​
Missing Authorization Header

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

​
Invalid API Key

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

​
Expired API Key

{
  "error": "Unauthorized",
  "message": "API key has expired"
}

​
Best Practices

Use Environment Variables

Store your API keys in environment variables, never hardcode them

Different Keys for Different Environments

Use separate API keys for development, staging, and production

Rotate Keys Regularly

Periodically regenerate your API keys for enhanced security

Monitor Usage

Keep track of your API usage in the dashboard