Introduction

Welcome to the VioPay Backoffice API documentation. This API powers the VioPay payment platform, providing endpoints for POS device management, payment processing, merchant operations, and more.

POS integration

New to POS? Start with the End-to-End Example — activation, MSK key install, config/activate, and charge in one walkthrough.

Base URL

https://api.viopay.io

Authentication

The API supports multiple authentication methods depending on the endpoint group:

Method	Used By	Description
Bearer Token	Backoffice, Merchant, Reseller APIs	Keycloak JWT token passed in Authorization: Bearer <token> header
Client session	Machine-to-machine integrations	Exchange client_id / client_secret via POST /client/session (legacy: POST /auth/token)
POS Activation	POS device bootstrap & pairing	Lightweight header-based auth using X-Device-Id, User-Agent, X-Client-Type
POS Attestation	POS keys, config, activation	Attestation token passed as Authorization: Attestation <token>
POS HMAC	POS charge operations	HMAC-SHA256 signature over the MSK-encrypted HTTP body
MSK (TR31-DATA)	Config, activate, charge APIs	AES-256-CBC payload encryption using the terminal MSK from /pos/keys

See the Authentication page for full details.

API Groups

POS Device APIs

Complete device lifecycle from bootstrap to activation and payment processing. The keys step delivers TMK, KEK, MSK, TPK, TDK, MAC for TR-31 installation. Config, activate, and charge payloads are MSK-encrypted (TR31-DATA). See End-to-End Example and POS Overview.

Charges

Create, retrieve, refund, and cancel payment charges via the payment gateway.

Merchant

Manage merchants, locations, devices, users, transactions, and more.

Reseller

Manage resellers, fee templates, branding, domain configuration, and hierarchy.

Common Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "4000",
    "message": "Description of the error",
    "details": {},
    "trace_id": "abc123..."
  }
}

HTTP Status	Meaning
200	Success
400	Bad request / validation error
401	Unauthorized / invalid credentials
403	Forbidden / insufficient permissions
404	Resource not found
500	Internal server error
502	Gateway error (payment processor)