Authentication

The POS API uses Personal Access Token authentication with Bearer token scheme. This simple yet secure method ensures that only authorized applications can access your POS system data and operations.

Personal Access Token

Personal Access Tokens provide secure, long-lived authentication for API access without requiring username/password credentials in your applications.

Generating a Token

To generate a Personal Access Token:

Log in to your Paysera POS system at pos.paysera.com
Navigate to User Settings (/user/settings)
Find the API Access or Personal Access Tokens section
Click Generate New Token
Give your token a descriptive name (e.g., "Production API Integration")
Copy the generated token immediately (it won't be shown again)
Store the token securely (see Security best practices)

warning

Save Your Token

The token is only displayed once during generation. If you lose it, you'll need to generate a new token and update your application.

Token Format

Personal Access Tokens are long alphanumeric strings:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Using the Token

Include your Personal Access Token in the Authorization header using the Bearer scheme for all API requests:

GET /eapi/v1/cash-registers/123/status HTTP/1.1
Host: pos.paysera.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Authentication Examples

cURL

curl -X GET https://pos.paysera.com/eapi/v1/orders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

PHP

<?php
$accessToken = getenv('POS_ACCESS_TOKEN');
$baseUrl = 'https://pos.paysera.com/eapi/v1';

$ch = curl_init($baseUrl . '/orders');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Accept: application/json'
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: HTTP $httpCode\n";
}
?>

JavaScript (Node.js)

const axios = require('axios');

const accessToken = process.env.POS_ACCESS_TOKEN;
const baseUrl = 'https://pos.paysera.com/eapi/v1';

async function getOrders() {
  try {
    const response = await axios.get(`${baseUrl}/orders`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getOrders();

Python

import os
import requests

access_token = os.getenv('POS_ACCESS_TOKEN')
base_url = 'https://pos.paysera.com/eapi/v1'

response = requests.get(
    f'{base_url}/orders',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: HTTP {response.status_code}")
    print(response.text)

Authentication Errors

Missing Authorization Header

If the Authorization header is missing, the API returns:

HTTP 401 Unauthorized

{
  "error": "unauthorized",
  "error_description": "Missing authorization header",
  "error_code": "AUTH001"
}

Solution: Include the Authorization header with Bearer token.

Invalid Token

If the token is invalid, malformed, or expired:

HTTP 401 Unauthorized

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has been revoked",
  "error_code": "AUTH002"
}

Solution: Generate a new token and update your application.

Insufficient Permissions

If your token lacks permissions for a specific resource:

HTTP 403 Forbidden

{
  "error": "forbidden",
  "error_description": "Access to this resource is not allowed",
  "error_code": "AUTH003"
}

Solution: Verify your account has the necessary permissions or contact support.

Token Management

Token Security

Personal Access Tokens provide full access to your POS system. Protect them carefully:

Never commit tokens to version control (Git, SVN, etc.)
Store tokens in environment variables or secure vaults
Never expose tokens in client-side code (browsers, mobile apps)
Use HTTPS only for all API communication
Rotate tokens regularly (recommended: every 90 days)
Revoke compromised tokens immediately

Storing Tokens Securely

Environment Variables (.env file):

# .env file (add to .gitignore)
POS_ACCESS_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Docker Secrets:

version: '3.8'
services:
  app:
    image: myapp
    secrets:
      - pos_access_token

secrets:
  pos_access_token:
    external: true

AWS Secrets Manager (Node.js):

const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

async function getAccessToken() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'pos/access_token'
  }).promise();

  return JSON.parse(secret.SecretString).access_token;
}

Token Rotation

Best practice is to rotate tokens regularly:

Generate a new token in POS settings
Update your application configuration with the new token
Test the new token in a staging environment
Deploy the update to production
Revoke the old token after confirming the new one works
Update any documentation or runbooks

Recommended rotation schedule: Every 90 days

Multiple Tokens

You can generate multiple tokens for different purposes:

Production application: prod-api-token
Staging environment: staging-api-token
Development environment: dev-api-token
Partner integrations: partner-xyz-token
Monitoring/analytics: monitoring-token

Benefits:

Isolate token usage by environment
Revoke specific tokens without affecting others
Track API usage by token
Implement different access patterns

Revoking Tokens

To revoke a token:

Log in to POS settings at pos.paysera.com/user/settings
Find the token in your token list
Click Revoke or Delete
Confirm the revocation

When to revoke tokens:

Token is compromised or exposed
Application is decommissioned
Employee leaves the organization
Integration is no longer used
Security audit requires token rotation

Demo Environment

For testing, use the demo environment with a demo account token:

Base URL: https://pos-demo.paysera.com/eapi/v1

Generate a demo token:

Create a demo account at pos-demo.paysera.com
Navigate to User Settings
Generate a demo token

Demo tokens only work with the demo environment and use simulated data.

Token Permissions

Personal Access Tokens inherit the permissions of the user who generated them. Ensure your user account has appropriate access:

Permission	Description
Read Orders	View order information
Create Orders	Generate new orders
Update Orders	Modify existing orders
Read Invoices	Access invoice data
Read Cash Registers	View cash register status and documents
Read Financial Documents	Access receipts and fiscal reports

Contact your POS administrator if you need additional permissions.

Testing Authentication

Test your token with a simple request:

curl -X GET https://pos.paysera.com/eapi/v1/orders?page=1&per_page=1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Success (200 OK):

{
  "data": [
    {
      "id": 123,
      "number": "ORD-001",
      "status": "completed"
    }
  ],
  "itemsTotal": 250,
  "pagesTotal": 250,
  "links": { ... }
}

Authentication Failed (401):

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has been revoked"
}

Troubleshooting

Common Issues

1. 401 Unauthorized despite correct token

Check:

Token is not expired
Using correct environment URL (production vs demo)
No extra spaces or newlines in token
Bearer keyword is included

2. Token works in cURL but not in application

Verify:

Headers are properly formatted in your HTTP client
Token is correctly read from environment variable
No URL encoding issues with the token

3. Intermittent authentication failures

Possible causes:

Network issues causing token truncation
Load balancer issues
Token approaching expiration

Next Steps

Review Security best practices for token protection
Explore POS API Endpoints for available operations
See Examples for complete integration patterns

Personal Access Token​

Generating a Token​

Token Format​

Using the Token​

Authentication Examples​

cURL​

PHP​

JavaScript (Node.js)​

Python​

Authentication Errors​

Missing Authorization Header​

Invalid Token​

Insufficient Permissions​

Token Management​

Token Security​

Storing Tokens Securely​

Token Rotation​

Multiple Tokens​

Revoking Tokens​

Demo Environment​

Token Permissions​

Testing Authentication​

Troubleshooting​

Common Issues​