# Pike SBP Demo — API приёма платежей

> Публичное API приёма платежей для клиентов (мерчантов) демо-стенда СБП.
> Заказы создаются в центах USD, оплата проходит в рублях через Систему
> быстрых платежей (СБП). Файл следует конвенции llms.txt и зеркалит
> человекочитаемую страницу https://<host>/docs.

Базовый URL: `https://<домен-стенда>`
Авторизация: `Authorization: Bearer <client_uuid>.<secret>` — ключ выдаётся на каждого клиента.
Все запросы и ответы — JSON (UTF-8). Максимальный размер тела запроса: 1 МиБ.
Деньги: целые числа в минорных единицах — центы USD (`10000` = $100.00), копейки RUB (`8476000` = 84 760,00 ₽).

## Жизненный цикл статусов

`pending → created | processing | action_required | awaiting_confirm | awaiting_capture → succeeded | canceled | failed | refunded | partially_refunded`

Финальные статусы «липкие»: запоздавший вебхук с промежуточным статусом их не затирает.
`refunded` / `partially_refunded` вычисляются по сумме принятых СБП возвратов.

## POST /api/v1/orders — создание заказа

Тело: `{ "amount": int>0 (центы USD, обязательное), "currency": "usd" (необязательное, только usd),
"return_url": string (обязательное), "customer_ref": string, "payment_description": string,
"sender_ipv4": "1.2.3.4", "idempotency_key": string }`

Успех `201`:
```json
{
  "order_id": "uuid",
  "status": "processing",
  "amount": 10000, "currency": "usd",
  "rate_used": 81.5, "rub_amount": 8476000,
  "return_url": "https://…",
  "sbp_deeplink": "https://qr.nspk.ru/…",
  "qr_image_base64": "…",
  "created_at": "RFC3339", "updated_at": "RFC3339"
}
```
- `rate_used` — курс USD/RUB, зафиксированный в заказе при создании; `rub_amount` — копейки к оплате (= amount/100 × курс × (1 + наценка клиента), округление).
- `sbp_deeplink` — ссылка на оплату (содержимое QR); `qr_image_base64` — картинка QR.

Ошибки: `400` валидация/лимиты; `401` авторизация; `503` нет свежего курса или создание заказов приостановлено; `502` СБП недоступна (заказ сохраняется со статусом `failed`).

## GET /api/v1/orders — список своих заказов

Query: `id` (префикс UUID), `status`, `amount_min`, `amount_max` (USD), `from`, `to` (`YYYY-MM-DD`, по МСК), `limit` (≤500). Возвращаются только заказы вызывающего клиента.

## GET /api/v1/orders/{id} — карточка заказа

Публичные поля: статус (локальный), суммы, зафиксированный курс, QR/ссылка на оплату. Чужой заказ → `403`. Данные платёжного провайдера клиенту не отдаются.

## POST /api/v1/orders/{id}/confirm — подтверждение операции
## POST /api/v1/orders/{id}/cancel — отмена неоплаченного заказа

## POST /api/v1/orders/{id}/refund — возврат

Тело: `{"amount": <копейки RUB>}` — частичный возврат, `{}` — полный возврат списанного.
Необязательное `reason` (≤500 символов) — причина возврата, видна оператору.
Если возвраты клиента проходят модерацию: `202 {"status":"pending_review"}`, иначе `200 {"status":"refunded"}`.

## Вебхуки (исходящие, клиенту)

Если клиенту задан `webhook_url`, при каждой РЕАЛЬНОЙ смене статуса сервис отправляет POST:

```json
{
  "type": "order.status_changed",
  "order": {
    "order_id": "uuid", "status": "processing",
    "amount": 10000, "currency": "usd",
    "rub_amount": 8476000, "rate_used": 81.5,
    "return_url": "https://…",
    "created_at": "RFC3339", "updated_at": "RFC3339"
  },
  "payment": {
    "sbp_deeplink": "https://qr.nspk.ru/…",
    "qr_image_base64": "…",
    "redirect_url": ""
  },
  "timestamp": "RFC3339"
}
```

Заголовки: `X-Webhook-Event: order.status_changed`, `X-Webhook-Signature: Base64(RSA-SHA256(body))` — проверяйте выданным публичным ключом. Отвечайте `2xx`; при таймауте/5xx/429 — до 3 попыток сразу, затем фоновые повторы каждые 5 минут (≤20 доставок на заказ в сутки). Дублей нет: вебхук уходит только при реальном изменении статуса. Вебхук не содержит данных платёжного провайдера — только локальный статус заказа и реквизиты оплаты СБП.

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

Передавайте `idempotency_key` при создании заказа: повторный запрос с тем же ключом вернёт ТОТ ЖЕ заказ без повторного списания. Ключ глобально уникален, но привязан к вашему клиенту — совпадение с чужим ключом даёт `400 idempotency_key is already used`, а не чужой заказ.

## Формат ошибок

`{"error": "человекочитаемое сообщение"}`

| HTTP | Значение |
|------|----------|
| 400 | невалидный запрос, лимиты клиента, чужой ключ идемпотентности |
| 401 | нет/неверный токен, клиент на паузе |
| 403 | заказ принадлежит другому клиенту |
| 503 | нет свежего курса USD/RUB; создание заказов приостановлено |
| 502 | СБП недоступна |

## Заметки для LLM-агентов

- Никогда не выдумывайте суммы в ответах: используйте целые числа в минорных единицах строго как указано.
- Ссылка на оплату для плательщика — `sbp_deeplink` (она же зашита в `qr_image_base64`).
- Считайте вебхук `order.status_changed` источником истины о состоянии заказа; для восстановления состояния опрашивайте `GET /api/v1/orders/{id}`.
- Админские эндпоинты (`/api/v1/admin/*`) — только для операторов и требуют сессии администратора; не используйте их в клиентских интеграциях.