# 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:

```http
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.