# PA Secure Fields SDK — интеграция для казино

Руководство по подключению приёма карточных депозитов через PA.
Контракт API — гайд [SDK + Webhooks](pa-secure-fields.md) (тот же документ
отрисован внутри Redocly-референса `/docs` в секции Guides); capture-контур
и его security-модель управляются Оператором и мерчанту не требуются.

## 0. Как это работает (30 секунд)

1. Игрок вводит карту в **iframe-виджет** (PA Secure Fields SDK) — значения полей недоступны
   JS казино.
2. Карта уходит **напрямую** в capture-поверхность PA (PSP vault); казино-фронтенд и
   casino backend получают **только single-use vault token**.
3. Casino backend регистрирует инструмент: `POST /v1/payment-instruments {vault_token}` →
   получает `pin_...` (PA token, маскированные метаданные `****1111`, brand).
4. Casino backend создаёт платёж: `POST /v1/payments {payment_instrument_id, amount, currency}` →
   cascade → финальный статус.
5. PA доставляет **подписанный webhook** на endpoint казино: `payment.authorized` —
   зачисляем депозит игроку.

PAN/CVV никогда не касаются casino backend и PA: нет ни БД-колонок, ни логов, ни аудита.

## 1. Что нужно казино

| Компонент | Что делает |
|---|---|
| `pa-sdk/secure-fields.js` | drop-in SDK: рисует iframe-виджет, отдаёт `onToken(vaultToken)` |
| `pa-sdk/secure-fields-frame.html` | страница iframe (форма карты + отправка в capture-поверхность). Размещается на origin PA/мерчанта; НЕ меняйте её логику самостоятельно |
| ваш backend | 3 вызова PA API + приём webhook (раздел 3) |

SDK не требует сборки: подключите оба файла статикой (в проде — с origin PA и HTTPS).

## 2. Frontend: виджет депозита

Production-пример (реальный capture):

```html
<script src="https://<pa-origin>/pa-sdk/secure-fields.js"></script>
<div id="pa-card"></div>
<script>
  const fields = PASecureFields.mount({
    container: '#pa-card',
    frameUrl: 'https://<pa-origin>/pa-sdk/secure-fields-frame.html',
    // Реальная capture-поверхность PA: iframe шлёт PAN/CVV напрямую
    // на POST /v1/sdk/capture и получает single-use vault token:
    captureUrl: 'https://<pa-origin>/v1/sdk/capture',
    // Publishable key мерчанта (PUBLIC — не секрет, вставляется в страницу;
    // выдаётся в ответе POST /v1/merchants и GET /v1/merchants/{id}):
    publishableKey: 'pk_018f3a2b-...-<16 hex>',
    onToken: (r) => {
      // r.vaultToken — single-use vault token; отправьте на СВОЙ backend:
      fetch('/my/api/deposit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ vault_token: r.vaultToken, amount_cents: 1500 })
      });
    },
    onError: (e) => showError(e.code, e.message),
  });
</script>
```

Коды ошибок capture-шага (`onError`): `invalid_publishable_key` (401 — ключ не тот),
`origin_not_allowed` (403 — origin не в allowlist PA), `invalid_card` (422 — карта
отклонена), `rate_limited` (429 — превышен лимит, повторите позже),
`capture_unavailable` (502 — capture-поверхность недоступна).

Правила:
- `publishableKey` — публичный: он не секрет и не даёт прав, кроме токенизации карт;
  храните его прямо во фронтенде, как Stripe `pk_`;
- не встраивайте `vault_token` в URL/логи; это одноразовый credential;
- токен живёт до регистрации инструмента; повторно зарегистрировать его нельзя
  (409 `vault_token_already_registered`);
- не храните токен в localStorage — передавайте сразу на backend.

## 3. Backend: три вызова PA + webhook

Все вызовы — `Authorization: Bearer <API-ключ>`: merchant-scoped ключ казино
(`mer_sk_…` — выдаёт оператор, работает только с вашим `merchant_id`)
или tenant-ключ оператора. На POST обязателен `Idempotency-Key` (uuid).
Ошибки — RFC 7807 (`code` — машинный дискриминатор).

### 3.1 Регистрация инструмента

```http
POST /v1/payment-instruments
Idempotency-Key: <uuid>
{
  "merchant_id": "mer_...",
  "vault_token": "<vaultToken из onToken>",
  "customer_reference": "usr_123"
}
```

`201` → `{"instrument_id": "pin_...", "card_meta": {"masked_pan": "****1111", "brand": "VISA", ...}, "status": "ACTIVE"}`.
Сохраните у себя пару `(customer_reference, instrument_id)`.

Коды: `vault_token_unknown` (токен потрачен/невалиден — запросите у игрока карту заново),
`vault_unavailable` (capture-поверхность недоступна — повторите с НОВЫМ Idempotency-Key),
`vault_token_already_registered` (409).

### 3.2 Создание платежа

```http
POST /v1/payments
Idempotency-Key: <uuid>
{
  "merchant_id": "mer_...",
  "amount": 1500,                    // минорные единицы
  "currency": "EUR",
  "payment_method": {"type": "card", "instrument_id": "pin_..."},
  "capture_method": "automatic"
}
```

`201` → `{"payment_id": "pay_...", "status": "AUTHORIZED"|"PENDING"|"FAILED"|...,
"attempts_summary": [...]}`. Инструмент **одноразовый**: повторный платёж по тому же
`pin_` → 422 `instrument_not_active`. При `PENDING` — опрашивайте
`GET /v1/payments/{id}` (`Retry-After`); финал — webhook и/или polling.

### 3.3 Webhook

Однократно зарегистрируйте endpoint (секрет покажется в ответе ровно один раз):

```http
POST /v1/merchants/{id}/webhook
{"url": "https://casino.example/pa/webhook"}
```

Сменить URL позже можно из портала мерчанта (`/portal` → Profile) или тем же
PATCH-вызовом; ротация секрета — `POST /v1/merchants/{id}/rotate-webhook-secret`
(новый секрет показывается один раз) или кнопка **Rotate secret** во
вкладке Profile портала.

Обработка на вашей стороне (обязательно):

1. проверить подпись: `PA-Webhook-Signature: v1=<hex(HMAC-SHA256(raw_body, webhook_secret))>`
   над **сырым телом запроса**;
2. дедуп по `event_id`;
3. `payment.authorized` / `payment.captured` → зачисление игроку;
4. ответить 2xx (иначе PA посчитает доставку неуспешной).

Типы событий: `payment.authorized`, `payment.captured`, `payment.refunded`, `payment.failed`.
Доставка — at-least-once: ретраи до `DELIVERED`, после
исчерпания — `DEAD`; журнал доставок — вкладка Integration портала); статус
платежа — источник истины через polling.

## 4. Onboarding казино (один раз)

Через PA API tenant-ключом оператора (merchant-scoped `mer_sk_…` казино
онбординг не выполняет — только собственные платежи):

```http
POST /v1/merchants                     {"name": "My Casino", "country": "CY", "currencies": ["EUR"]}
POST /v1/merchants/{id}/providers      {"provider_code": "payadmit", "mid": "mid_1", "credentials_ref": "mca_1", "currencies": ["EUR"]}
POST /v1/merchants/{id}/route-targets  {"provider_account_id": "mid_...", "priority": 1, "filters": {"currency": ["EUR"], "method": ["automatic"]}}
POST /v1/merchants/{id}/webhook        {"url": "https://casino.example/pa/webhook"}
```

Ответ `POST /v1/merchants` содержит **`publishable_key`** (`pk_<merchant-uuid>_<digest>`) — публичный ключ для `PASecureFields.mount({publishableKey})`. Он детерминированный:
`GET /v1/merchants/{id}` возвращает тот же ключ (потерять его нельзя, ротация не нужна).
Сменить привязку/отозвать ключ можно перенастройкой pepper на стороне PA (все ключи
мерчанта меняются одномоментно).

## 5. Локальный smoke (demo)

Тестовое казино целиком (frontend + backend + webhook receiver) — `pa-sdk/demo/server.js`:

```bash
# 1. Поднять PA (mock engine, mock vault) на disposable PG
# (из каталога развёртывания PA Core)
PA_DATABASE_URL=postgres://pa:pa@127.0.0.1:5432/pa?sslmode=disable \
PA_ENGINE=mock PA_BIND=127.0.0.1:8080 cargo run --bin pa-api

# 2. Создать tenant-ключ (seed) и запустить демо-казино
PA_SEED_TENANT_API_KEY=pa_sk_demo_0000000000000000000000000000000000000000000000000000000000 \
PA_DATABASE_URL=postgres://pa:pa@127.0.0.1:5432/pa?sslmode=disable cargo run --bin pa-seed
#   → stdout: tenant_id=... merchant_id=...

cd pa-sdk/demo
PA_BASE_URL=http://127.0.0.1:8080 \
PA_TENANT_KEY=pa_sk_demo_0000000000000000000000000000000000000000000000000000000000 \
node server.js
#   → demo casino running at http://127.0.0.1:8090/demo/
```

Откройте `http://127.0.0.1:8090/demo/`:

1. **Onboard казино** — merchant/provider/route-target/webhook через PA API;
2. введите тестовую карту `4111 1111 1111 1111`, 12/30, CVC `123` → **Tokenize card** —
   в demo-режиме capture-поверхности токен mintится внутри iframe (без сети);
3. **Создать платёж по инструменту** → статус `AUTHORIZED` в логе шага 3;
4. через ~3 с — подписанный `payment.authorized` в журнале шага 4.

PCI-наблюдение: в логах демо-сервера и PA нет ни PAN, ни CVC, ни vault token — только
`pin_...`, `pay_...` и метаданные `****1111`.

## 6. Тестовый режим capture ('demo') и прод

Два режима `captureUrl`:

| Режим | `captureUrl` | Что происходит |
|---|---|---|
| demo (CI/E2E/dev) | `'demo'` | Токен `vtok_<brand>_<last4>-<uuid>` mintится в iframe **без сети**, PAN/CVV умирают в iframe. Publishable key не нужен. |
| прод (capture через PA) | `https://<pa-origin>/v1/sdk/capture` | iframe шлёт PAN/CVV на capture-endpoint PA → PA токенизирует карту в PSP vault → `vault_token` + маскированные метаданные. Требуется `publishableKey`. |

Прод-требования на стороне PA (обеспечивает Оператор): HTTPS-only на публичных адресах
(fail-fast в production), жёсткий rate limit на publishable key (по умолчанию 30/мин) +
per-IP окно; при необходимости — origin allowlist.
