# PA Payments API — контракт

Краткий контракт публичного Payments API платформы PA для казино-разработчика:
поверхность ресурсов, аутентификация, идемпотентность и модель ошибок.
Машиночитаемый контракт — [`openapi.json`](openapi.json) (`GET /docs/openapi.json`);
поля запроса создания платежа — [Field Reference](pa-payment-fields.md);
токенизация карты и инструменты — [SDK + Webhooks](pa-secure-fields.md);
модели интеграции и PCI scope — [Integration models](/docs/onboarding/pa-integration-models.md).

## 1. Поверхность ресурсов

Публичная поверхность мерчанта (полный список — в [`openapi.json`](openapi.json)):

| Ресурс | Методы | Назначение |
|---|---|---|
| `/v1/payments` | `POST` / `GET …/{id}` | создать платёж / прочитать состояние |
| `/v1/refunds` | `POST` | возврат авторизованного/захваченного платежа |
| `/v1/payment-instruments` | `POST` / `GET …/{id}` | регистрация инструмента из single-use vault token / masked view |
| `/v1/sdk/capture` | `POST` | браузерная токенизация PAN/CVV (вызывается ТОЛЬКО SDK-iframe, не бэкендом) |
| `/v1/merchants/{id}/payouts*` | `POST` / `GET` / `GET …/{id}` / `…/cancel` / `…/approve` / `…/decline` | выплаты мерчанта (см. [Payouts Guide](/docs/onboarding/pa-payouts-guide.md)) |
| `/v1/merchants/{id}/…` | `GET`/`PATCH`/`POST` | self-service мерчанта: статистика, список платежей, CSV, журнал доставок, ротации (см. `/docs`) |
| `/v1/tenants/{id}/…` | `POST …/rotate-key` / `DELETE …/keys/{key_id}` | жизненный цикл tenant API key (см. §5) |

Важные следствия из текущего контракта:

- **Захват (`capture`) в публичном API не экспонирован.** Единственный
  поддерживаемый метод — `capture_method: "automatic"` (sale-модель: авторизация
  и захват одним вызовом). `POST /v1/payments/{id}/capture` и
  `POST /v1/payments/{id}/cancel` в текущую поверхность **не входят**; запрос
  `manual` без способного Route Target отвечает `422 no_eligible_route`.
- **Инструмент регистрируется из vault token, а не из PAN.** Эндпоинты
  `/v1/payment-instruments/tokenize`, `…/verify`, `…/deactivate` отсутствуют:
  карту вводит игрок в Secure Fields SDK → capture-поверхность выдаёт
  `vault_token` → `POST /v1/payment-instruments {vault_token}` → `pin_…`
  (см. [SDK + Webhooks](pa-secure-fields.md) §2).
- **Возврат — только создание:** `POST /v1/refunds {payment_id, amount, reason}`;
  чтение отдельного возврата `/v1/refunds/{id}` не экспонировано — состояние
  возврата отражается в статусе платежа (`PARTIALLY_REFUNDED` / `REFUNDED`).

## 2. Аутентификация

| Контур | Ключ | Заголовок |
|---|---|---|
| Backend API (`/v1/*`) | tenant API key (`pay_sk_…`) | `Authorization: Bearer <key>` |
| Browser capture (`/v1/sdk/capture`) | publishable key (`pk_…`, PUBLIC) | `X-Publishable-Key` |

- Tenant API key выдаётся Оператором и показывается **ровно один раз**; хранится
  в PA только как SHA-256. Для self-service мерчанта Оператор выдаёт
  merchant-scoped ключ `mer_sk_…` (`POST /v1/merchants/{id}/api-key`), который
  действует только на своего мерчанта.
- Publishable key — derived-публичный идентификатор: привязывает capture к
  мерчанту и его rate-limit-бюджету, прав на деньги не даёт.

## 3. Идемпотентность

| Аспект | Контракт |
|---|---|
| Заголовок | `Idempotency-Key: <uuid>` — обязателен для каждого mutating POST |
| Скоуп | `(tenant, endpoint, key)`; ключи изолированы по тенантам |
| Повтор | тот же ключ + то же тело → реплей сохранённого результата (`Idempotent-Replayed: true`), новый платёж НЕ создаётся |
| In-flight | оригинал ещё выполняется → `409 Conflict` + `Retry-After` |
| Коллизия | тот же ключ + другое тело → `422 idempotency_key_reuse` |
| TTL | ключ переиспользуем по истечении (заголовок `Idempotency-Expires`); повтор после TTL = новый ресурс |
| Порядок | идемпотентность применяется ДО выбора Route Target и внешних вызовов |
| Детерминизм | в снапшот сохраняются только детерминированные результаты (2xx и детерминированные ошибки); транзиентные отказы (`vault_unavailable` 502) НЕ сохраняются — повтор начинает новую попытку |

## 4. Модель ошибок

Каждый ответ с ошибкой — RFC 7807 `application/problem+json`:

```json
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "no_eligible_route",
  "message": "no eligible route target for this payment",
  "payment_id": "pay_…"
}
```

Машинный дискриминатор — поле `code` (стабильные значения PA); на текст
`message` опираться нельзя, значения карт в нём не эхоятся. Полный реестр кодов
и decline-таксономия — раздел **Errors** справочника `/docs` и
[Field Reference §9](pa-payment-fields.md).

Граница **400 vs 422**:

- **400 `invalid_request`** — ошибки схемы тела: невалидный JSON, неверные типы,
  отсутствующие обязательные поля, неизвестные top-level поля (в т.ч. `pan`/`cvv`
  на верхнем уровне). Текст ошибки serde наружу не эхоится.
- **422** — семантические/доменные ошибки (`unknown_merchant`,
  `no_eligible_route`, `idempotency_key_reuse`, …), включая PCI-подозрительные
  ключи и PAN-пробу во вложенных свободных полях (`customer`, `risk_context`,
  `session_context`, `metadata`). `unknown_merchant` возвращается и тогда, когда
  мерчант удалён КОНКУРЕНТНО между проверкой тенанта и вставкой платежа
  (`DELETE /v1/merchants/{id}`, PA-140): платёж не создаётся, `500` в этой
  ситуации не бывает — клиент получает тот же стабильный `422`.

## 5. Жизненный цикл tenant API key

- **Ротация** `POST /v1/tenants/{id}/rotate-key`: новый ключ валиден немедленно,
  старый остаётся рабочим 24 ч (grace), затем `401`. `new_key` показывается ровно
  один раз.
- **Отзыв** `DELETE /v1/tenants/{id}/keys/{key_id}`: немедленный `401` со
  следующего запроса; повторный вызов идемпотентен (`204`).
- `{id}` в пути обязан совпадать с аутентифицированным тенантом; чужой — `404`
  без утечки существования.

## 6. Связанные материалы

- [Field Reference](pa-payment-fields.md) — поля `POST /v1/payments` и `next_action`;
- [SDK + Webhooks](pa-secure-fields.md) — токенизация, инструменты, webhook-контракт;
- [Integration models](/docs/onboarding/pa-integration-models.md) — SDK / HPP / H2H и PCI scope;
- [Handover Package](/docs/onboarding/handover-package.md) — ключи и 6 шагов интеграции;
- [Payouts Guide](/docs/onboarding/pa-payouts-guide.md) — модель выплат.
