vitanovaPackages/docs/BACKEND-CONTRACT.md

Backend contract for @marketplaces/auth and @marketplaces/payment

These packages call two independent central services, never the tenant API:

• provideMarketplacesAuth({ apiUrl }) points to the central Auth API.
• provideMarketplacesPayment({ apiUrl }) points to the central Payment API.

Every request carries X-Marketplace-Domain with the full page hostname. Example: both example.com and store1.example.com are sent verbatim. The central backend resolves both aliases through its domain registry to the same project. This header is untrusted routing context, not authorization.

Both services must allow X-Marketplace-Domain in CORS preflight and reject unknown/disabled domains.

Auth API

Telegram QR:

• POST /users/sessions
• GET /users/sessions/:id
• DELETE /users/sessions/:id

Credentials:

POST /auth/credentials/login
X-Marketplace-Domain: store1.example.com
Content-Type: application/json

{ "login": "admin", "password": "...", "mode": "admin" }

Return { method, mode, session, accessToken?, refreshToken? }. Invalid credentials return 401.

Yandex OAuth is backend-owned:

• POST /auth/yandex/sessions with { provider: "yandex", mode, returnUrl } returns { attemptId, authorizationUrl }.
• GET /auth/yandex/sessions/:attemptId returns 202/404 while pending and the same auth result when complete.

Yandex client secrets never enter the browser. For mode=admin, the Auth API enforces admin authorization.

Payment API

• POST /api/v1/payments with { checkoutSessionId, method, returnUrl?, metadata? }.
• GET /api/v1/payments/:paymentId.
• POST /api/v1/payments/:paymentId/cancel.

The Payment API uses X-Marketplace-Domain to resolve the project/payment point. The browser sends no amount or currency; it sends only the central checkout session id. Server resolves and freezes amount, currency, inventory, project, provider and idempotency.

Methods: qr, card, sbp, yandex-pay. Response action is { type: "qr" | "redirect", url }. Provider secrets, card data and callbacks stay server-side.