HTTP API & integration

The VirtuOZ platform exposes a versioned JSON API under /api/v1/…, designed for the same expectations as institutional payment and custody workflows: explicit contracts, authenticated sessions, and auditable actions. Replace YOUR_HOST with your deployment hostname. The authoritative route table is the server router; OpenAPI documents a large subset of operations for tooling and review.

Support, helpdesk & automation

For integration questions, production access, webhooks, or bespoke automation, please contact us through the helpdesk: open a case from the Help center or write to support@evopay.biz. Authenticated clients may also create tickets via POST /api/v1/helpdesk/tickets.

We are ready to automate integration into your back-office, ERP, or marketplace: our team can assist with sandbox access, test data, error-handling patterns, and review of your compliance profile (AML/KYC) where required for go-live.

Documentation & discovery

• Interactive UI: /docs (Swagger UI) when enabled in deployment configuration.
• Machine-readable schema: GET /api/v1/openapi.json. The interactive UI at /docs loads the same OpenAPI document via /api/v1/openapi-ui.json when documentation is enabled.
• Health: GET /health, GET /readiness, GET /api/v1/status; GET /metrics exposes Prometheus metrics (often restricted at the edge).

Conventions

• Transport: HTTPS/TLS in production; do not send secrets over plain HTTP.
• Format: Content-Type: application/json on bodies unless uploading dispute evidence (multipart).
• Authentication: after POST /api/v1/auth/login, use the issued access JWT via session cookie and/or Authorization: Bearer … per your integration pattern; refresh with POST /api/v1/auth/refresh.
• Authorization: many routes require an authenticated user and appropriate RBAC role (customer, operator, admin, compliance, etc.). Denials return structured error JSON.
• Idempotency: sensitive financial operations may honor Idempotency-Key where implemented—see OpenAPI per operation.

Operational & streaming

Method	Path	Notes
GET	/health	Process liveness.
GET	/readiness	Dependency readiness.
GET	/metrics	Prometheus metrics (often IP-restricted).
GET	/api/v1/status	API status payload (JSON).
GET	/api/v1/openapi.json	OpenAPI document.
GET	/api/v1/notifications/stream	SSE stream of platform notifications (auth as per deployment policy).

Authentication & session

Method	Path	Notes
POST	/api/v1/auth/register	Create account.
POST	/api/v1/auth/login	Obtain session / tokens.
POST	/api/v1/auth/refresh	Rotate access token.
POST	/api/v1/auth/logout	End current session.
POST	/api/v1/auth/logout-all	Revoke all sessions for user.
GET	/api/v1/auth/sessions	List active sessions.
POST	/api/v1/auth/sessions/{session_id}/revoke	Revoke one session.
POST	/api/v1/auth/mfa/enroll	TOTP enrollment.
POST	/api/v1/auth/mfa/verify	Verify TOTP.
POST	/api/v1/auth/mfa/disable	Disable TOTP.
POST	/api/v1/auth/rbac-cache/invalidate	Invalidate RBAC cache (privileged).
POST	/api/v1/auth/i18n/reload	Reload locale bundles (signed operator payload).
POST	/api/v1/auth/readiness-policy/reload	Reload readiness policy (signed).

Profile & wallet

Method	Path	Notes
GET	/api/v1/me	Current user profile.
GET	/api/v1/wallet/balances	Balances by currency.
GET	/api/v1/wallet/activity	Ledger activity (query params for pagination).

Escrow & disputes

Method	Path	Notes
POST	/api/v1/escrow	Create escrow contract.
GET	/api/v1/escrow/contracts	List contracts for caller.
GET	/api/v1/escrow/contracts/{escrow_id}	Contract detail.
GET	/api/v1/escrow/contracts/{escrow_id}/history	History / timeline.
POST	/api/v1/escrow/{escrow_id}/fund	Fund escrow.
POST	/api/v1/escrow/{escrow_id}/release	Release funds.
POST	/api/v1/escrow/{escrow_id}/dispute	Open dispute.
POST	/api/v1/escrow/{escrow_id}/dispute/evidence	Upload evidence (multipart).
GET	/api/v1/escrow/{escrow_id}/dispute/evidence	List evidence files.
GET	/api/v1/escrow/{escrow_id}/dispute/evidence/{file_id}	Download evidence.
POST	/api/v1/escrow/{escrow_id}/dispute/evidence/{file_id}/delete	Delete evidence file.
POST	/api/v1/escrow/{escrow_id}/dispute/resolve	Resolve dispute.
POST	/api/v1/escrow/{escrow_id}/dispute/reject	Reject dispute.

Compliance

Method	Path	Notes
POST	/api/v1/compliance/reports	Create compliance report.
GET	/api/v1/compliance/reports/{jurisdiction}	List reports for jurisdiction.
POST	/api/v1/compliance/travel-rule	Travel Rule transfer upsert.
GET	/api/v1/compliance/travel-rule/recent	Recent Travel Rule transfers.

Published content (read)

Method	Path	Notes
GET	/api/v1/cms/legal/{slug}	Published legal document JSON/HTML payload.
GET	/api/v1/cms/help	List published help articles.
GET	/api/v1/cms/help/{slug}	Single help article.
GET	/api/v1/cms/landing/{slug}	Published landing page bundle.

Email templates (preview & test)

Method	Path	Notes
POST	/api/v1/cms/email/{slug}/preview	Render preview (privileged).
POST	/api/v1/cms/email/{slug}/test-send	Send test message (privileged).

Helpdesk

Method	Path	Notes
POST	/api/v1/helpdesk/tickets	Create ticket.
GET	/api/v1/helpdesk/tickets	List tickets (scoped to caller).
GET	/api/v1/helpdesk/tickets/{ticket_id}	Ticket detail.
POST	/api/v1/helpdesk/tickets/{ticket_id}/internal-notes	Add internal note (staff).
POST	/api/v1/helpdesk/tickets/{ticket_id}/context-links	Attach context link (staff).

Platform utilities

Method	Path	Notes
POST	/api/v1/platform/storage/shard-path	Storage path preview (operator tooling).
POST	/api/v1/platform/cms/workflow/next-status	CMS workflow transition preview.
POST	/api/v1/platform/helpdesk/sla	SLA preview for tickets.
POST	/api/v1/platform/i18n/message	i18n message resolution preview.

Crypto custody (platform)

Method	Path	Notes
POST	/api/v1/platform/crypto/scanner/ingest	Ingest scanner event.
POST	/api/v1/platform/crypto/address/allocate	Allocate deposit address.
POST	/api/v1/platform/crypto/withdrawals/request	Create withdrawal request.
POST	/api/v1/platform/crypto/withdrawals/{withdrawal_id}/sign	Sign withdrawal.
POST	/api/v1/platform/crypto/withdrawals/{withdrawal_id}/rollback	Rollback withdrawal.

Administration (RBAC)

The following prefixes are used for operator and back-office automation. All require appropriate administrative roles; do not expose these keys to end-user mobile clients.

Prefix / pattern	Capabilities
/api/v1/admin/events/replay/{aggregate_type}/{aggregate_id}	POST — replay event projections.
/api/v1/admin/events/export/{aggregate_type}/{aggregate_id}	GET — export audit event stream.
/api/v1/admin/users … /api/v1/admin/users/{user_id} … /role, /status	User directory and lifecycle.
/api/v1/admin/kyc/queue, /api/v1/admin/kyc/{user_id}/decision	KYC queue and decisions.
/api/v1/admin/transactions … /{tx_id} … /flag, /resolve, /reconcile	Transaction review.
/api/v1/admin/compliance/reports	Compliance reports (admin view).
/api/v1/admin/escrow/contracts	Escrow contract oversight.
/api/v1/admin/cms/legal (+ /draft, /publish, /transition, /rollback)	Legal CMS workflow.
/api/v1/admin/cms/help (+ /draft, /publish, /transition, /rollback)	Help CMS workflow.
/api/v1/admin/cms/email (+ /draft, /publish, /transition, /rollback)	Email template CMS.
/api/v1/admin/cms/landing (+ /draft, /publish, /transition, /rollback)	Landing page CMS.

Examples

Register and login with cookie jar; then call authenticated routes.

{
  "email": "user@example.com",
  "password": "YourStrongPassw0rd!",
  "display_name": "Demo User"
}

curl -sS -X POST "https://YOUR_HOST/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "YourStrongPassw0rd!",
    "display_name": "Demo User"
  }'

curl -sS -X POST "https://YOUR_HOST/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "user@example.com",
    "password": "YourStrongPassw0rd!"
  }'

curl -sS "https://YOUR_HOST/api/v1/me" -b cookies.txt

curl -sS "https://YOUR_HOST/api/v1/wallet/balances" -b cookies.txt

curl -sS "https://YOUR_HOST/api/v1/wallet/activity?limit=20" -b cookies.txt

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "title": "Equipment delivery",
    "description": "Servers per specification",
    "amount": "8000.00",
    "currency": "USD"
  }'

Then replace ESCROW_ID:

curl -sS "https://YOUR_HOST/api/v1/escrow/contracts/ESCROW_ID" -b cookies.txt

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow/ESCROW_ID/fund" \
  -H "Content-Type: application/json" -b cookies.txt -d '{}'

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow/ESCROW_ID/release" \
  -H "Content-Type: application/json" -b cookies.txt -d '{}'

curl -sS "https://YOUR_HOST/api/v1/status"
curl -sS "https://YOUR_HOST/readiness"