PDV — overview

:::info Current state Today the PDV only has authentication. Operational sessions (opening/closing a terminal), orders, QR-based charging, and refunds don't exist yet — they're part of a future phase (payment intents + dynamic QR) that depends on the Regional Foundation (wallets, ledger) being complete. This page will grow once those endpoints exist. :::

What exists today

PDV is an operational account (operator_type=pdv), created by management and scoped to a specific workspace. See Management → Operators (PDV and cashier) for how the account is provisioned.

Endpoint	What it does
POST /v1/auth/pdv/login	Login with the username/password generated by management. Sets wallet_pdv_access_token, wallet_pdv_refresh_token, wallet_pdv_csrf_token.
POST /v1/auth/pdv/refresh	Rotates the refresh token.
POST /v1/auth/pdv/logout	Revokes the session and clears the wallet_pdv_* cookies.

Example: login

curl

curl -X POST http://127.0.0.1:8787/v1/auth/pdv/login \
  -H "Content-Type: application/json" \
  -d '{ "username": "PDV-00184723", "password": "<password generated by management>" }'

JavaScript

const response = await fetch("http://127.0.0.1:8787/v1/auth/pdv/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "PDV-00184723", password: "<password generated by management>" }),
});
const session = await response.json();

Python

import requests

response = requests.post(
    "http://127.0.0.1:8787/v1/auth/pdv/login",
    json={"username": "PDV-00184723", "password": "<password generated by management>"},
)
session = response.json()

What the PDV JWT contains

{
  "sub": "supabase-auth-operator-id",
  "principal_type": "operator",
  "operator_account_id": "operator-uuid",
  "operator_type": "pdv",
  "event_id": "event-uuid",
  "operator_username": "PDV-00184723",
  "operator_description": "Entrada Principal",
  "session_id": "global-session-id",
  "exp": 1784000000
}

operator_description comes back null when the account has no description set. Both claims travel along so wallet-api can record who performed each operation (recharge, sale) without a call back to the global database — see Cashier → statement.

event_id already comes in the token — a PDV doesn't pick/switch events after logging in; the account is immutable in that respect (provisioning a PDV account for another workspace means creating a new account, not moving the existing one).

Planned (not implemented yet)

• Terminal operational session (open/close).
• Order and payment intent creation.
• Dynamic QR for the participant to approve the payment.
• Full/partial refund of a charge.
• Viewing the PDV's own sales/refunds.