Authentication

The VioPay API uses different authentication mechanisms depending on the endpoint group.

Method	Used By	Description
Bearer Token	Backoffice, Merchant, Reseller APIs	Keycloak JWT token
Client session	Machine-to-machine integrations	Exchange client_id / client_secret for an access token and cached session
POS Headers	POS device activation & payment APIs	Multiple auth levels — see POS Headers Reference

Bearer Token (Keycloak JWT)

Used by most backoffice, merchant, and reseller endpoints. Obtain a token via Keycloak and pass it in the Authorization header.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Session Initiation

After obtaining a Bearer token, you must call the session endpoint to initialize your session context:

POST /session/initiate

{
  "host": "merchant.viopay.io"
}

This resolves your user, merchant, reseller, channel, and application context for subsequent requests.

---

Client session (machine-to-machine)

For integrations using a merchant API client (client_id / client_secret). This endpoint validates credentials, obtains a Keycloak access token, and creates the server-side session cache used by subsequent Bearer requests.

POST /client/session

Legacy path

POST /auth/token is still supported for the same request body and behavior. Prefer /client/session on api.viopay.io so traffic is not confused with Keycloak paths under /auth/… on other hosts.

Backoffice API vs Keycloak

Keycloak (e.g. https://auth.viopay.io) is an OAuth2/OpenID server. Its token endpoint is:

POST …/realms/{realm}/protocol/openid-connect/token with application/x-www-form-urlencoded body (grant_type, client_id, client_secret, etc.).

The VioPay Backoffice API (e.g. https://api.viopay.io) exposes:

POST /client/session with JSON body (below). That handler validates your merchant API client in the database, calls Keycloak for you, and creates the API session cache.

Verify traffic reaches the Go API

GET https://api.viopay.io/health/live should return JSON including "service":"vi-backoffice-api". If public requests never hit that response, fix DNS / ingress routing for api.viopay.io.

---

Request

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials"
}

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

The returned access token expires in 5 minutes. Use it in subsequent requests as a Bearer token. A session is automatically created and cached.

cURL

curl -s -X POST 'https://api.viopay.io/client/session' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "mrc_your_client_id_here",
    "client_secret": "your-client-secret-here",
    "grant_type": "client_credentials"
  }'

---

POS Authentication

POS devices use a multi-level authentication system that progresses through the activation flow. For full details on all POS headers, formats, and signature construction, see the POS Headers Reference and End-to-End Example.

MSK payload encryption (TR31-DATA)

After POST /pos/keys, the terminal holds an MSK for API payload encryption. These endpoints wrap JSON in an AES-256-CBC envelope:

Endpoint	MSK on request	MSK on response
POST /pos/config	—	✅
POST /pos/terminal-parameters	—	✅ (gzip, chunked)
POST /pos/activate	✅	✅
POST /pos/charge	✅	✅
POST /pos/charge/:id/refund	✅	✅
POST /pos/charge/:id/cancel	—	✅

Envelope shape:

{
  "format": "TR31-DATA",
  "ciphertext": "<hexBinary>",
  "initialization_vector": "<hexBinary>",
  "mode": "CBC"
}

For charge APIs, HMAC is computed over the encrypted envelope body, not the plaintext JSON. See Create POS Charge.