{
  "openapi": "3.1.0",
  "info": {
    "title": "Пополнение — Merchant API",
    "version": "1.7.1",
    "description": "Рублёвая оплата продавцу Stars; баланс мерчанта в XTR. Обычные платежи подтверждаются по квитанции автоматически. Для платежа с апелляцией callbacks подавлены до ручного решения модератора: только одобрение отправляет payment.paid. Ручное одобрение является отдельной учётной корректировкой и не выполняет перевод Stars. Выплаты оформляются заявками. Для рублёвых заказов amount_rub хранит неизменную исходную целую сумму от 100 до 50000 RUB. Базовый допустимый интервал: max(100, amount_rub - 1)..amount_rub + 0.99 включительно. Например, 310 допускает 309.00..310.99; запрос 100 — 100.00..100.99. При занятых количествах Stars подбирается следующее свободное целое количество Stars: N, N+1, N+2 и далее, в пределах количества и суммы, поддерживаемых методом; внутреннего ограничения десятью шагами нет. Фактическая сумма может быть выше запроса. effective_amount_rub равен целой части свежей котировки даже при quantity_adjustment=0 и может быть amount_rub - 1. Сумма провайдера строго проверяется в effective_amount_rub..effective_amount_rub + 0.99. payer_amount — полная фактическая сумма для оплаты, webhook и статистики. amount_adjustment_rub — разница с исходным запросом, в том числе отрицательная. Stars подбираются автоматически. Некоторые интервалы недоступны из-за целого количества Stars и меняющегося курса. Баланс и выплаты остаются XTR. Количество неоплаченного счёта занято на час от issued_at продавца; повторное использование допускается не раньше issued_at + 3600 при подтверждённом истечении и отсутствии поступления, перевода или неоднозначности. Поздно обнаруженное поступление по истёкшему счёту продолжает обычную автоматическую обработку только при однозначной связи аккаунта, количества и счёта и реальном received_at <= issued_at + 3600 из квитанции Telegram; время опроса не заменяет received_at. Успех и webhook требуют штатного подтверждения зачисления. Срок действия ссылки задаёт продавец, часовая бронь его не продлевает. Если счёт продавца остаётся действующим, обычная обработка поступления после часа не меняется. Поздние поступления по истёкшим счетам за пределами часа, неоднозначные связи и апелляции требуют ручной сверки. История сохраняется. Метод @stars СБП №2 принимает только количества, кратные 100; неподдерживаемые шаги +1 для него пропускаются в каскаде. Для новых платежей каскада payment_url может вести на страницу продавца kassa.ai, AuraPay или Wata: payment_url_kind=provider, payer_amount_is_estimate=true. Сумма payer_amount в этом режиме — предварительная котировка продавца, не доказательство списания рублей; итог отображается на странице провайдера. Для прямой НСПК payment_url_kind=nspk, payer_amount_is_estimate=false. После выдачи ссылки 55-секундный срок создания больше не отменяет заявку. payment.paid по-прежнему требует подтверждённого поступления и зачисления Stars. Krab.gg: запрошенная amount_rub сохраняется. Комиссия и округление СБП прибавляются сверху после проверки счета продавца. seller_amount_rub — стоимость Stars до доплаты; provider_surcharge_rub — доплата и округление; provider_surcharge_policy=added_on_top. payer_amount — итог счета, effective_amount_rub — его целые рубли; payer_amount_source=seller_checkout. Это подтверждённая цена счета, а не банковская квитанция: payer_amount_is_estimate=true сохраняется. Успех требует фактического поступления и зачисления Stars. Новые дополнительные поля также передаются в webhook. payment_url может вести на gate.antilopay.com. Клиент должен видеть итоговую сумму до перехода к оплате. Merchant API остаётся на https://bonbonus.fun/api/merchant/v1. Наша форма WILDER ORIGINAL расположена на https://bonbonus.fun/pay/…, отдельного мерчанта Wilder — на https://bn.softapi.org/pay/…. Оба получают форму сразу после создания. Для WILDER ORIGINAL в REST и обычных webhook при доступной форме без апелляции status=awaiting_payment, payment_url ведёт на форму bonbonus.fun, payment_url_kind=checkout; checkout_url и processing_status отсутствуют. Этот внешний status означает доступность формы и не доказывает готовность котировки или реквизитов провайдера: stars и payer_amount могут оставаться null. Форма и админка показывают реальный этап подготовки; кнопка оплаты появится только после реальной готовности реквизитов. Новое создание возвращает HTTP 202 без ожидания первичной подготовки, повтор — HTTP 200. В остальных статусах и при апелляции status остаётся реальным, ссылка скрыта. Исторические webhook-события не переписываются. У отдельного Wilder сохраняется форма bn.softapi.org с checkout_url и реальными queued/creating. Открывайте форму обычным переходом или в отдельном окне, без iframe. У остальных мерчантов без нашей формы сохраняется прямая выдача provider/nspk при awaiting_payment. Подтверждение оплаты и учёт не изменены: исполняйте заказ только после подтверждённого paid. Для WILDER ORIGINAL REST и обычные webhook сразу передают нашу форму bonbonus.fun в payment_url, payment_url_kind=checkout и status=awaiting_payment. Новый запрос получает HTTP 200 без ожидания котировки; реальный поиск и кнопка оплаты показаны внутри формы. Отдельный Wilder сохраняет HTTP 202 для нового запроса, реальные queued/creating и форму bn.softapi.org. Paradise, Horizon и Vault используют прежний порядок прямой выдачи: новый запрос возвращает HTTP 202, идемпотентный повтор — HTTP 200. На этапе queued/creating payment_url=null. После готовности возвращаются awaiting_payment, проверенная ссылка provider/nspk в payment_url и payer_amount. Ссылка на нашу форму вместо реквизитов не подставляется; checkout_url отсутствует. Оплата подтверждается только статусом paid."
  },
  "servers": [
    {
      "url": "https://bonbonus.fun/api/merchant/v1"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Payment": {
        "type": "object",
        "required": [
          "id",
          "external_id",
          "stars",
          "status",
          "currency",
          "amount_rub"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "external_id": {
            "type": "string"
          },
          "stars": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 50,
            "maximum": 35000,
            "description": "Количество Stars. В рублёвом режиме null до подбора; выбранное количество не обязано быть кратно 100. В прямом режиме равно запрошенным stars."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "creating",
              "awaiting_payment",
              "collecting",
              "paid",
              "expired",
              "review",
              "failed",
              "cancelled"
            ],
            "description": " Для WILDER ORIGINAL в REST и новых обычных webhook при доступной форме bonbonus.fun без апелляции внутренние queued/creating/awaiting_payment представлены как awaiting_payment. Здесь это только доступность нашей формы: stars и payer_amount могут оставаться null, котировка и реквизиты провайдера готовятся внутри формы. Реальный этап доступен в форме и админке. Терминальные статусы и апелляции не подменяются. Это представление не меняет базу, учёт или подтверждение paid. У Paradise, Horizon и Vault передаётся фактический статус queued/creating/awaiting_payment; доступность нашей формы не подменяет этап подготовки."
          },
          "currency": {
            "type": "string",
            "enum": [
              "XTR"
            ]
          },
          "payer_currency": {
            "type": "string",
            "enum": [
              "RUB"
            ]
          },
          "payer_amount": {
            "type": [
              "string",
              "null"
            ],
            "description": "Сумма в рублях. При payer_amount_is_estimate=true это предварительная котировка; окончательная сумма видна плательщику у провайдера. Баланс мерчанта учитывается в Stars."
          },
          "payment_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ссылка для покупателя. Для WILDER ORIGINAL в REST и обычных webhook сразу при доступной форме без апелляции возвращается адрес https://bonbonus.fun/pay/…, status=awaiting_payment и payment_url_kind=checkout, даже если котировка и реквизиты провайдера ещё не готовы; stars и payer_amount могут быть null. Откройте форму сразу: она покажет реальную подготовку, затем кнопку оплаты. checkout_url и processing_status отсутствуют. Для отдельного Wilder сохраняется форма https://bn.softapi.org/pay/… с payment_url_kind=checkout и checkout_url при реальных queued/creating/awaiting_payment. Открывайте форму обычным переходом или в отдельном окне; iframe не поддерживается. У остальных мерчантов сохраняется прямая выдача provider/nspk при awaiting_payment. В остальных статусах и при апелляции payment_url=null. Наличие ссылки не подтверждает оплату. У Paradise, Horizon и Vault на этапе queued/creating ссылка отсутствует; при awaiting_payment передаётся проверенная прямая ссылка provider/nspk вместе с payer_amount."
          },
          "checkout_path": {
            "type": "string",
            "description": "Относительный путь формы /pay/…, доступный сразу после постановки в очередь. Для мерчанта с включённой формой используйте абсолютный payment_url с типом checkout. Не является подтверждением готовности реквизитов или оплаты."
          },
          "paid_at": {
            "type": [
              "number",
              "null"
            ]
          },
          "created_at": {
            "type": "number"
          },
          "updated_at": {
            "type": "number"
          },
          "issue": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "description": {
            "type": "string"
          },
          "appeal": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Appeal"
              },
              {
                "type": "null"
              }
            ]
          },
          "can_appeal": {
            "type": "boolean",
            "description": "Можно ли подать новую апелляцию на этот платёж. false для оплаченных или уже имеющих апелляцию."
          },
          "approval": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ManualApproval"
              },
              {
                "type": "null"
              }
            ],
            "description": "Ручное одобрение апелляции, если применимо."
          },
          "amount_rub": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 100,
            "maximum": 50000,
            "description": "Неизменная исходная сумма в целых RUB от 100 до 50000; null для прямого запроса Stars. Базовый допустимый интервал: max(100, amount_rub - 1)..amount_rub + 0.99 включительно. Например, 310 допускает 309.00..310.99; 100 допускает 100.00..100.99. При занятых количествах Stars итог может увеличиться; используйте effective_amount_rub и payer_amount."
          },
          "creation_deadline_at": {
            "type": [
              "number",
              "null"
            ],
            "description": "Unix timestamp конца подготовки ссылки: created_at + 55 секунд для новых заявок. Включает очередь, Telegram и QR. null для исторических заявок. После выдачи ссылки этот срок не ограничивает время оплаты."
          },
          "cancellation_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "creation_timeout",
              null
            ],
            "description": "creation_timeout для отмены заявки по общему сроку подготовки; иначе null."
          },
          "effective_amount_rub": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 100,
            "description": "Целая часть свежей котировки выбранных Stars, включая quantity_adjustment=0. При quantity_adjustment=0 находится между max(100, amount_rub - 1) и amount_rub; может быть на 1 меньше исходного запроса. При quantity_adjustment>0 находится между amount_rub и 50000. null для прямого запроса Stars. Сумма провайдера payer_amount проверяется строго в интервале effective_amount_rub..effective_amount_rub + 0.99 включительно, а не во всём исходном диапазоне.",
            "maximum": 50000,
            "examples": [
              309,
              310,
              101,
              null
            ]
          },
          "quantity_adjustment": {
            "type": "integer",
            "minimum": 0,
            "maximum": 34950,
            "description": "Число Stars, добавленное к базовому количеству из-за занятых слотов. Это шаг Stars, а не рубли. Для прямого запроса Stars — 0."
          },
          "amount_adjustment_rub": {
            "type": [
              "string",
              "null"
            ],
            "description": "Фактическая payer_amount минус неизменный исходный amount_rub; десятичная строка с копейками и возможным знаком минус, например -0.44 для 309.56 при запросе 310. null до получения суммы или в прямом режиме Stars.",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "examples": [
              "-0.44",
              "0.00",
              "1.66",
              null
            ]
          },
          "routing": {
            "type": "object",
            "description": "Optional cascade diagnostics. Direct provider/nspk payment_url and payer_amount are payment instructions only at awaiting_payment. A checkout payment_url may be opened at queued/creating; the form waits for requisites itself. Neither routing nor a form URL confirms payment.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "auto"
                ]
              },
              "published": {
                "type": "boolean"
              },
              "selected_route_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "attempts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "route_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "issue": {
                      "type": "string"
                    },
                    "quantity": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "quoted_amount": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "estimated": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "payment_url_kind": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "provider",
              "nspk",
              "checkout",
              null
            ],
            "description": "Тип назначения ссылки. Для WILDER ORIGINAL checkout означает доступную сразу форму bonbonus.fun: внешний status=awaiting_payment, но котировка и реквизиты провайдера могут ещё готовиться, stars и payer_amount могут быть null. Для отдельного Wilder checkout означает форму bn.softapi.org, доступную при реальных queued/creating/awaiting_payment. У остальных мерчантов provider — страница продавца/провайдера, nspk — НСПК при awaiting_payment; null — ссылка скрыта или не готова. Тип не подтверждает оплату. У Paradise, Horizon и Vault значение provider/nspk появляется только вместе с готовыми реквизитами; checkout не подставляется."
          },
          "payer_amount_is_estimate": {
            "type": "boolean",
            "description": "true для котировки kassa.ai / AuraPay / Wata; не является подтверждённой суммой банковского списания, в том числе в payment.paid."
          },
          "seller_amount_rub": {
            "type": "string",
            "description": "Стоимость Stars до комиссии и округления Krab."
          },
          "provider_surcharge_rub": {
            "type": "string",
            "description": "Комиссия и округление поверх стоимости Stars, RUB."
          },
          "provider_surcharge_policy": {
            "type": "string",
            "enum": [
              "added_on_top"
            ]
          },
          "payer_amount_source": {
            "type": "string",
            "enum": [
              "seller_checkout"
            ],
            "description": "Итог подтверждён счетом продавца, не банковской квитанцией."
          },
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "Дополнительная ссылка на форму только для отдельного Wilder: https://bn.softapi.org/pay/…. У WILDER ORIGINAL, Paradise, Horizon и Vault поле отсутствует. У WILDER ORIGINAL форма bonbonus.fun передаётся сразу в payment_url с payment_url_kind=checkout. Paradise, Horizon и Vault передают готовую прямую ссылку провайдера в payment_url. Наличие ссылки не подтверждает оплату."
          },
          "user_id": {
            "type": "string",
            "nullable": true,
            "description": "Необязательный ID покупателя из metadata.user_id. В callbacks доступен в data.metadata.user_id."
          },
          "user_stats": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "description": "Необязательная статистика пользователя по истории мерчанта на момент создания заявки. Дневные показатели — текущий день по Москве, до текущей заявки. Оборот за всё время в RUB. Любые поля можно пропустить или передать null. Нули сохраняются. Снимок неизменяем при идемпотентном повторе; хранится в metadata.user_stats, в webhook — data.metadata.user_stats. Не меняет учёт и правила выдачи.",
            "properties": {
              "unpaid_orders_today": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "maximum": 2147483647,
                "description": "Неоплаченные заявки пользователя, созданные за текущий день."
              },
              "stars_purchase_turnover_total_rub": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^[0-9]{1,12}\\.[0-9]{2}$",
                "description": "Общий оборот пользователя на покупку Stars за всё время в RUB."
              },
              "stars_sale_turnover_total_rub": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^[0-9]{1,12}\\.[0-9]{2}$",
                "description": "Общий оборот пользователя на продажу Stars за всё время в RUB."
              },
              "successful_topups_today": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "maximum": 2147483647,
                "description": "Количество успешных пополнений пользователя за текущий день."
              }
            },
            "example": {
              "unpaid_orders_today": 3,
              "stars_purchase_turnover_total_rub": "12500.50",
              "stars_sale_turnover_total_rub": "3200.00",
              "successful_topups_today": 2
            }
          }
        },
        "examples": [
          {
            "id": "payment-example",
            "external_id": "flowers-1042",
            "amount_rub": 310,
            "stars": 204,
            "status": "awaiting_payment",
            "currency": "XTR",
            "payer_currency": "RUB",
            "payer_amount": "309.56",
            "payment_url": "https://qr.nspk.ru/example",
            "effective_amount_rub": 309,
            "quantity_adjustment": 0,
            "amount_adjustment_rub": "-0.44"
          }
        ]
      },
      "Appeal": {
        "type": "object",
        "required": [
          "id",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "created_at": {
            "type": "number",
            "description": "Unix timestamp в секундах"
          },
          "decided_at": {
            "type": [
              "number",
              "null"
            ],
            "description": "Unix timestamp решения в секундах"
          },
          "decision_comment": {
            "type": "string"
          }
        },
        "description": "Решение доступно через GET платежа. Подача и отклонение не отправляют webhook; одобрение отправляет payment.paid."
      },
      "ManualApproval": {
        "type": "object",
        "required": [
          "mode",
          "appeal_id",
          "moderator_id",
          "decided_at"
        ],
        "properties": {
          "mode": {
            "const": "manual",
            "type": "string"
          },
          "appeal_id": {
            "type": "string"
          },
          "moderator_id": {
            "type": "integer",
            "description": "Telegram ID модератора"
          },
          "decided_at": {
            "type": "number",
            "description": "Unix timestamp решения в секундах"
          }
        },
        "description": "Ручное учётное подтверждение после апелляции; не является подтверждением технической квитанции или переводом Stars."
      },
      "AppealRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 5,
            "maxLength": 1000
          },
          "evidence": {
            "type": "string",
            "maxLength": 1000,
            "description": "Номер операции, сумма, время или иные сведения для сверки. Не указывать банковские секреты."
          }
        }
      },
      "AppealResult": {
        "type": "object",
        "required": [
          "appeal",
          "created"
        ],
        "properties": {
          "appeal": {
            "$ref": "#/components/schemas/Appeal"
          },
          "created": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "paths": {
    "/payments": {
      "post": {
        "summary": "Создать платёж",
        "responses": {
          "200": {
            "description": "Для WILDER ORIGINAL — новый запрос принят сразу: status=awaiting_payment, payment_url ведёт на нашу форму bonbonus.fun, payment_url_kind=checkout. Котировка и реквизиты готовятся внутри формы; stars и payer_amount могут быть null. Также HTTP 200 используется для идемпотентного повтора любого мерчанта. Оплата этим ответом не подтверждается.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "202": {
            "description": "Новый платёж остальных мерчантов принят; оплата не подтверждена. Для отдельного Wilder наша форма доступна сразу при реальных queued/creating. Для мерчантов без нашей формы прямая ссылка появляется после получения реквизитов. Повтор того же запроса возвращает HTTP 200.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "issuance_paused: выдача новых реквизитов остановлена после ошибок или задержек подтверждения у 3 разных платежей за 15 минут. Старые выданные счета и webhooks продолжают обрабатываться. Повтор с прежним Idempotency-Key возвращает существующую заявку. Возобновляет администратор."
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_id"
                ],
                "properties": {
                  "external_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "stars": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 35000,
                    "multipleOf": 100,
                    "description": "Прямой запрос количества Stars; нельзя передавать вместе с amount_rub."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "metadata": {
                    "type": "object"
                  },
                  "amount_rub": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 50000,
                    "description": "Неизменный запрос в целых RUB от 100 до 50000. Базовый допустимый интервал: max(100, amount_rub - 1)..amount_rub + 0.99. Например, 310 означает 309.00..310.99, а 100 — 100.00..100.99. При занятом количестве подбирается следующее свободное количество Stars (N, N+1, N+2 и далее) в допустимом диапазоне метода с возможным повышением суммы. Показывайте фактическую payer_amount."
                  },
                  "callback_url": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 2048
                      },
                      {
                        "type": "null"
                      },
                      {
                        "const": ""
                      }
                    ],
                    "description": "Необязательный webhook для этого заказа. Непустой публичный HTTPS URL на 443 имеет приоритет над webhook мерчанта. Отсутствие, null или пустая строка используют настройки мерчанта. Адрес неизменяем; смена при повторе исходного ключа или external_id даёт 409 idempotency_conflict. Подпись прежним webhook_secret мерчанта.",
                    "example": "https://shop.example.com/hooks/payments"
                  },
                  "user_id": {
                    "oneOf": [
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 9223372036854775807
                      }
                    ],
                    "nullable": true,
                    "description": "Необязательный ID покупателя у мерчанта. Сохраняется в metadata.user_id как строка. Не связан с Telegram-аккаунтом исполнителя."
                  },
                  "user_stats": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": false,
                    "description": "Необязательная статистика пользователя по истории мерчанта на момент создания заявки. Дневные показатели — текущий день по Москве, до текущей заявки. Оборот за всё время в RUB. Любые поля можно пропустить или передать null. Нули сохраняются. Снимок неизменяем при идемпотентном повторе; хранится в metadata.user_stats, в webhook — data.metadata.user_stats. Не меняет учёт и правила выдачи.",
                    "properties": {
                      "unpaid_orders_today": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "minimum": 0,
                        "maximum": 2147483647,
                        "description": "Неоплаченные заявки пользователя, созданные за текущий день."
                      },
                      "stars_purchase_turnover_total_rub": {
                        "oneOf": [
                          {
                            "type": "string",
                            "pattern": "^[0-9]{1,12}(\\.[0-9]{1,2})?$"
                          },
                          {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 999999999999.99,
                            "multipleOf": 0.01
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Общий оборот пользователя на покупку Stars за всё время в RUB."
                      },
                      "stars_sale_turnover_total_rub": {
                        "oneOf": [
                          {
                            "type": "string",
                            "pattern": "^[0-9]{1,12}(\\.[0-9]{1,2})?$"
                          },
                          {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 999999999999.99,
                            "multipleOf": 0.01
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Общий оборот пользователя на продажу Stars за всё время в RUB."
                      },
                      "successful_topups_today": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "minimum": 0,
                        "maximum": 2147483647,
                        "description": "Количество успешных пополнений пользователя за текущий день."
                      }
                    },
                    "example": {
                      "unpaid_orders_today": 3,
                      "stars_purchase_turnover_total_rub": "12500.50",
                      "stars_sale_turnover_total_rub": "3200.00",
                      "successful_topups_today": 2
                    }
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "amount_rub"
                    ],
                    "not": {
                      "required": [
                        "stars"
                      ]
                    }
                  },
                  {
                    "required": [
                      "stars"
                    ],
                    "not": {
                      "required": [
                        "amount_rub"
                      ]
                    }
                  }
                ]
              },
              "examples": {
                "rubles": {
                  "summary": "Заказ цветов в рублях",
                  "value": {
                    "external_id": "flowers-1042",
                    "amount_rub": 100,
                    "description": "Заказ цветов №1042",
                    "metadata": {
                      "order_id": "1042"
                    }
                  }
                },
                "stars": {
                  "summary": "Совместимый прямой запрос Stars",
                  "value": {
                    "external_id": "stars-1043",
                    "stars": 100
                  }
                },
                "user_stats": {
                  "summary": "Необязательная статистика покупателя",
                  "value": {
                    "external_id": "stars-order-1042",
                    "amount_rub": 150,
                    "user_id": "customer-42",
                    "user_stats": {
                      "unpaid_orders_today": 3,
                      "stars_purchase_turnover_total_rub": "12500.50",
                      "stars_sale_turnover_total_rub": "3200.00",
                      "successful_topups_today": 2
                    }
                  }
                }
              },
              "example": {
                "external_id": "shop-order-1042",
                "amount_rub": 100,
                "callback_url": "https://shop.example.com/hooks/payments"
              }
            }
          }
        },
        "description": "Передайте ровно одно из amount_rub или stars. amount_rub — неизменные целые рубли 100..50000: сначала подбирается сумма в диапазоне max(100, amount_rub - 1)..amount_rub + 0.99. Например, запрос 310 допускает 309.00..310.99; запрос 100 — 100.00..100.99. effective_amount_rub всегда равен целой части свежей котировки, включая quantity_adjustment=0, и без добавления Stars может быть amount_rub - 1. Если количество занято, добавляем по 1 Stars до ближайшего свободного количества; в этом режиме effective_amount_rub не ниже amount_rub. Для @stars СБП №2 допустимы только количества, кратные 100: неподдерживаемый шаг не отправляется, рассматриваются другие подходящие методы. Сумма провайдера проверяется строго в effective_amount_rub..effective_amount_rub + 0.99. Возвращаем полную payer_amount, используем её для webhook и статистики; amount_adjustment_rub может быть отрицательной. Исходный amount_rub не меняется. На свободные аккаунты распределяем в первую очередь, затем допускаются отдельные счета на одном аккаунте с разными количествами (до 10 резервов). stars — прежний режим, целое число 100..35000, кратное 100. При новом запросе создаётся очередь; код ответа — 200 для WILDER ORIGINAL, 202 для остальных мерчантов. В рублёвом режиме stars сначала null. Некоторые интервалы недостижимы: failed без платёжной ссылки. Несовпадение суммы готового счёта: review без платёжной ссылки. При сетевой неопределённости повторяйте те же тело, external_id и Idempotency-Key; не создавайте дубликат. Изменённый запрос с прежним идентификатором возвращает 409. Ответ нового запроса — HTTP 200 для WILDER ORIGINAL; HTTP 202 для остальных мерчантов. Повтор исходного запроса любого мерчанта возвращает 200 и существующий платёж. Для Wilder и WILDER ORIGINAL ответ возвращается сразу. Для WILDER ORIGINAL при доступной форме без апелляции возвращается внешний status=awaiting_payment, payment_url=https://bonbonus.fun/pay/…, payment_url_kind=checkout, даже пока котировка и реквизиты провайдера готовятся; stars и payer_amount могут быть null. Поля checkout_url и processing_status отсутствуют. Откройте форму сразу: реальный этап подготовки показан внутри неё и в админке, а кнопка оплаты появляется после реальной готовности. Этот status не подтверждает реквизиты провайдера, оплату или зачисление. У Wilder форма находится на https://bn.softapi.org/pay/…, payment_url_kind=checkout, checkout_url содержит тот же адрес. В рублёвом режиме stars и payer_amount могут быть null до подбора и котировки. Форму можно открыть до готовности реквизитов обычным переходом или в отдельном окне, без iframe; она сама опрашивает состояние и затем показывает кнопку «Открыть страницу оплаты». Для остальных мерчантов создание по-прежнему ожидает готовую ссылку до 8 секунд: awaiting_payment содержит прямую ссылку provider/nspk, а queued/creating — payment_url=null. Merchant API остаётся на https://bonbonus.fun/api/merchant/v1; форма WILDER ORIGINAL — на bonbonus.fun, отдельного мерчанта Wilder — на bn.softapi.org. При status queued/creating опрашивайте GET /payments/{id} раз в секунду; при awaiting_payment или collecting — раз в 5 секунд. Общий лимит 120 запросов в минуту на мерчанта включает другие методы: увеличивайте интервалы при нескольких активных платежах, централизуйте опрос на сервере магазина и соблюдайте Retry-After при HTTP 429. HTTP 200/202 в ответе создания не подтверждает готовность реквизитов или оплату; статусы queued/creating и тип checkout не подменяются. После сетевой ошибки повторите исходное тело с тем же Idempotency-Key; новый платёж не создаётся. Предварительная подготовка частых сумм управляется владельцем в панели; целевое время 5–10 секунд при готовности зависит от Telegram и провайдера и не гарантируется. Общий срок подготовки новой заявки — 55 секунд от created_at, включая очередь, Telegram и обе QR-попытки. Если пригодная ссылка не готова, status=cancelled, payment_url=null, cancellation_reason=creation_timeout; отправляется payment.cancelled. Отмена подготовки не означает отмену счёта у внешнего провайдера. Старую ссылку не оплачивать. Повтор с тем же ключом возвращает ту же отменённую заявку и не продлевает срок; для новой заявки нужны новые external_id и Idempotency-Key. Для awaiting_payment срок оплаты определяется действием счёта провайдера, а не этим таймером. Неоплаченное количество Stars удерживается на час от issued_at продавца; освобождение после issued_at + 3600 требует подтверждённого истечения и отсутствия поступления, перевода или неоднозначности. Для истёкшего счёта поздно обнаруженная квитанция с реальным received_at <= issued_at + 3600 может продолжить штатную автоматическую обработку при однозначной связи аккаунта, количества и счёта; успех и webhook требуют подтверждения зачисления. Часовая бронь не продлевает срок ссылки продавца. Если счёт продавца остаётся действующим, обычная обработка поступления после часа не меняется. Поздние поступления по истёкшим счетам за пределами часа и неоднозначные связи требуют ручной сверки. Апелляции сохраняют ручную обработку. Для WILDER ORIGINAL одинаковое представление действует в REST создания, списка и получения платежа и в новых обычных webhook: при доступной форме без апелляции status=awaiting_payment, payment_url ведёт на bonbonus.fun, payment_url_kind=checkout. Обычное событие имеет тип payment.awaiting_payment; фактическая готовность позже может создать новое событие того же типа с другим event.id. Не считайте это подтверждением оплаты, дедуплицируйте по event.id. В остальных статусах и при апелляции сохраняется реальный status без платёжной ссылки. Исторические webhook-события не переписываются. Учёт и подтверждение paid не меняются. У Wilder форма сохраняется с payment_url_kind=checkout и checkout_url в REST и обычных webhook. Реальные статусы и суммы не меняются. Отдельный Wilder сохраняет HTTP 202 для нового запроса, реальные queued/creating и форму bn.softapi.org. Paradise, Horizon и Vault используют прежний порядок прямой выдачи: новый запрос возвращает HTTP 202, идемпотентный повтор — HTTP 200. На этапе queued/creating payment_url=null. После готовности возвращаются awaiting_payment, проверенная ссылка provider/nspk в payment_url и payer_amount. Ссылка на нашу форму вместо реквизитов не подставляется; checkout_url отсутствует. Оплата подтверждается только статусом paid."
      },
      "get": {
        "summary": "Список платежей",
        "responses": {
          "200": {
            "description": "Успех"
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "external_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/payments/{id}": {
      "get": {
        "summary": "Получить платёж",
        "responses": {
          "200": {
            "description": "Успех",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": " Пока статус queued/creating, опрашивайте раз в секунду; при awaiting_payment или collecting — раз в 5 секунд. Не создавайте новый платёж вместо ожидания существующего. Общий лимит 120 запросов в минуту на мерчанта включает все API-методы: при нескольких заказах увеличивайте интервалы и централизуйте опрос на сервере магазина. На HTTP 429 соблюдайте Retry-After."
      }
    },
    "/balance": {
      "get": {
        "summary": "Баланс XTR",
        "responses": {
          "200": {
            "description": "Успех"
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        }
      }
    },
    "/statistics": {
      "get": {
        "summary": "Статистика за 30 дней",
        "responses": {
          "200": {
            "description": "Успех"
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        }
      }
    },
    "/payouts": {
      "get": {
        "summary": "Список выплат",
        "responses": {
          "200": {
            "description": "Успех"
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ]
      },
      "post": {
        "summary": "Зарезервировать Stars для выплаты",
        "responses": {
          "200": {
            "description": "Успех"
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Конфликт"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "stars",
                  "destination"
                ],
                "properties": {
                  "stars": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "destination": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300
                  }
                }
              }
            }
          }
        }
      }
    },
    "/payments/{id}/issues": {
      "post": {
        "summary": "Подать апелляцию (совместимый алиас)",
        "responses": {
          "200": {
            "description": "Апелляция создана или уже существует",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppealResult"
                }
              }
            }
          },
          "201": {
            "description": "Апелляция создана",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppealResult"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Платёж уже оплачен или недоступен для апелляции"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppealRequest"
              }
            }
          }
        },
        "description": "Алиас POST /payments/{id}/appeals с теми же правилами. Используйте /appeals для новых интеграций. Доступен только платёж текущего мерчанта. Одна апелляция на платёж; повтор возвращает существующую, Idempotency-Key не требуется. Оплаченный платёж без апелляции отклоняется с 409. Платёж уходит на ручную проверку. С момента обращения все callbacks по этому платежу подавлены, кроме payment.paid после ручного одобрения модератором в отдельном Telegram-боте. Подача и отклонение не отправляют webhook. Обычные оплаты без апелляции продолжают подтверждаться автоматически.",
        "deprecated": true
      }
    },
    "/payments/{id}/appeals": {
      "post": {
        "summary": "Подать апелляцию на платёж",
        "responses": {
          "200": {
            "description": "Апелляция создана или уже существует",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppealResult"
                }
              }
            }
          },
          "201": {
            "description": "Апелляция создана",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppealResult"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос"
          },
          "401": {
            "description": "Не авторизован"
          },
          "404": {
            "description": "Не найден"
          },
          "409": {
            "description": "Платёж уже оплачен или недоступен для апелляции"
          },
          "429": {
            "description": "Лимит запросов"
          },
          "503": {
            "description": "Недоступно"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppealRequest"
              }
            }
          }
        },
        "description": "Доступен только платёж текущего мерчанта. Одна апелляция на платёж; повтор возвращает существующую, Idempotency-Key не требуется. Оплаченный платёж без апелляции отклоняется с 409. Платёж уходит на ручную проверку. С момента обращения все callbacks по этому платежу подавлены, кроме payment.paid после ручного одобрения модератором в отдельном Telegram-боте. Подача и отклонение не отправляют webhook. Обычные оплаты без апелляции продолжают подтверждаться автоматически."
      }
    },
    "/smerch/payments": {
      "get": {
        "summary": "Список платежей Smerch · RUB",
        "tags": [
          "Smerch"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ"
          }
        }
      },
      "post": {
        "summary": "Создать платёж Smerch · СБП (10–299 ₽)",
        "tags": [
          "Smerch"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ"
          },
          "201": {
            "description": "Счёт создан"
          },
          "202": {
            "description": "Создание уточняется; повтор с тем же ключом безопасен"
          },
          "409": {
            "description": "Конфликт идентификатора"
          },
          "422": {
            "description": "Недопустимая сумма"
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "external_id",
                  "amount_rub",
                  "metadata"
                ],
                "properties": {
                  "external_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "amount_rub": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 299
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "metadata": {
                    "type": "object",
                    "required": [
                      "userId"
                    ],
                    "properties": {
                      "userId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100,
                        "description": "Постоянный ID плательщика из вашей системы"
                      }
                    }
                  },
                  "callback_url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/smerch/payments/{id}": {
      "get": {
        "summary": "Статус платежа Smerch",
        "tags": [
          "Smerch"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/smerch/statistics": {
      "get": {
        "summary": "Отдельная статистика Smerch",
        "tags": [
          "Smerch"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ"
          }
        }
      }
    },
    "/smerch/balance": {
      "get": {
        "summary": "Учтённая чистая сумма Smerch, копейки",
        "tags": [
          "Smerch"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ"
          }
        }
      }
    }
  }
}
