openapi: 3.1.0
info:
  title: Robokassa API
  version: 1.0.0
  description: |
    OpenAPI-спецификация платежных интерфейсов Robokassa. Она описывает запуск
    платежей, выставление счетов, проверку состояния операций, возвраты,
    холдирование, рекуррентные платежи, SMS-уведомления и обработку callback-запросов.

    Правила формирования подписи, фискализации, настройки уведомлений и подключения
    отдельных возможностей приведены в документации Robokassa.
  contact:
    name: Robokassa
    url: https://docs.robokassa.ru/
x-robokassa-contract-verification:
  date: 2026-07-23
  environment: production
  verifiedOperations:
    - createPayment
    - createPaymentPost
    - createInvoice
    - deactivateInvoice
    - listInvoices
    - getCurrencies
    - getOperationState
  partiallyVerifiedOperations:
    - operation: createRefund
      result: Получен HTTP 401 — API возвратов не подключен магазину или Password3 не активирован.
    - operation: getRefundState
      result: Подтвержден HTTP 400 для несуществующего requestId; успешная заявка не создавалась.
    - operation: paymentSuccessRedirectGet
      result: Контракт описан по документации; завершенный платеж для проверки редиректа не выполнялся.
    - operation: paymentSuccessRedirectPost
      result: Контракт описан по документации; завершенный платеж для проверки редиректа не выполнялся.
    - operation: paymentFailRedirectGet
      result: Контракт описан по документации; прерванный платеж для проверки редиректа не выполнялся.
    - operation: paymentFailRedirectPost
      result: Контракт описан по документации; прерванный платеж для проверки редиректа не выполнялся.
    - operation: confirmHold
      result: Запрос подтвержден официальным WordPress-плагином; реальное списание не выполнялось.
    - operation: cancelHold
      result: Запрос подтвержден официальным WordPress-плагином; реальная отмена холда не выполнялась.
    - operation: createRecurringPayment
      result: Запрос подтвержден официальным WordPress-плагином; повторное списание не выполнялось.
    - operation: sendSmsGet
      result: Запрос подтвержден официальным WordPress-плагином; SMS не отправлялось.
    - operation: sendSmsPost
      result: POST описан документацией; плагин использует GET-вариант.
    - operation: paymentResult2Notification
      result: Обработчик JWS подтвержден официальным WordPress-плагином; уведомление не получалось в ходе проверки.
  notes:
    - Запуск оплаты проверен до отображения платежной страницы, без проведения платежа.
    - Успешный OpStateExt проверен на существующей завершенной операции; чувствительные значения не сохранялись.
    - Реальный возврат средств не выполнялся.
x-robokassa-implementation-reference:
  repository: https://github.com/robokassa/cms-wordpress
  commit: 92c8c6aceffe283f89319ac41ead78bc573bb361
  files:
    - classes/Robokassa/Payment/RobokassaPayAPI.php
    - classes/Robokassa/Payment/WC_WP_robokassa.php
    - wp_robokassa.php
externalDocs:
  description: Документация Robokassa
  url: https://docs.robokassa.ru/ru/
tags:
  - name: Payments
    description: Запуск оплаты через платежную страницу.
  - name: Invoices
    description: Выставление счетов через Invoice API.
  - name: Operations
    description: Получение состояния операций.
  - name: Reference
    description: Справочные методы Robokassa.
  - name: Refunds
    description: Создание возвратов и получение их состояния.
  - name: Holding
    description: Подтверждение и отмена двухстадийных платежей.
  - name: Recurring
    description: Повторные списания по рекуррентным платежам.
  - name: Messaging
    description: Отправка SMS через дополнительный сервис Robokassa.
paths:
  /Merchant/Index.aspx:
    get:
      tags:
        - Payments
      summary: Открыть платежную страницу
      description: |
        Создает операцию оплаты и открывает платежную страницу Robokassa.
        Для тестового платежа передайте `IsTest=1`.

        Значение `SignatureValue` рассчитывается на стороне магазина. Базовая
        строка имеет вид
        `MerchantLogin:OutSum:InvId:модификаторы:Пароль#1:Shp_*`.

        Дополнительные параметры с префиксом `Shp_` разрешены. Их необходимо
        включать в подпись в алфавитном порядке.
      operationId: createPayment
      servers:
        - url: https://auth.robokassa.ru
      parameters:
        - $ref: "#/components/parameters/MerchantLogin"
        - $ref: "#/components/parameters/OutSum"
        - $ref: "#/components/parameters/SignatureValue"
        - $ref: "#/components/parameters/InvId"
        - name: Description
          in: query
          description: Название товара или услуги, без специальных символов.
          schema:
            type: string
            maxLength: 100
        - name: Email
          in: query
          description: Email покупателя для чеков и уведомлений.
          schema:
            type: string
            format: email
        - name: IncCurrLabel
          in: query
          description: Предлагаемый способ оплаты из интерфейса GetCurrencies.
          schema:
            type: string
        - name: Culture
          in: query
          description: Язык платежной страницы.
          schema:
            type: string
            enum:
              - ru
              - en
        - name: Encoding
          in: query
          description: Кодировка передаваемых данных.
          schema:
            type: string
            default: UTF-8
        - name: IsTest
          in: query
          description: Признак тестового режима.
          schema:
            type: integer
            enum:
              - 0
              - 1
        - name: ExpirationDate
          in: query
          description: Крайний срок оплаты в формате `YYYY-MM-DDThh:mm`.
          schema:
            type: string
            example: 2026-07-22T18:30
        - name: Receipt
          in: query
          description: Фискальные данные — минимизированный JSON в URL-кодировке.
          schema:
            type: string
        - name: StepByStep
          in: query
          description: Признак двухстадийной оплаты.
          schema:
            type: boolean
        - name: PaymentMethods
          in: query
          description: Разрешенные способы оплаты. Параметр можно повторять.
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: ResultUrl2
          in: query
          description: Дополнительный адрес серверного уведомления.
          schema:
            type: string
            format: uri
        - name: SuccessUrl2
          in: query
          description: Дополнительный адрес возврата после успешной оплаты.
          schema:
            type: string
            format: uri
        - name: SuccessUrl2Method
          in: query
          description: Метод запроса к SuccessUrl2.
          schema:
            $ref: "#/components/schemas/RedirectMethod"
        - name: FailUrl2
          in: query
          description: Дополнительный адрес возврата после ошибки оплаты.
          schema:
            type: string
            format: uri
        - name: FailUrl2Method
          in: query
          description: Метод запроса к FailUrl2.
          schema:
            $ref: "#/components/schemas/RedirectMethod"
        - name: Token
          in: query
          description: Токен сохраненной карты.
          schema:
            type: string
        - name: Recurring
          in: query
          description: Признак периодического платежа.
          schema:
            type: boolean
      responses:
        "200":
          description: |
            HTML-страница с сообщением об ошибке параметров. Например, при
            неверной подписи страница возвращается с HTTP 200, а код ошибки `29`
            передается внутри контекста страницы.
          content:
            text/html:
              schema:
                type: string
        "302":
          description: Платеж создан. Клиент перенаправляется на платежную страницу.
          headers:
            Location:
              description: Относительный URL созданной платежной страницы.
              required: true
              schema:
                type: string
                format: uri-reference
                example: /Merchant/Index/01234567-89ab-4cde-8f01-23456789abcd
        default:
          description: Транспортная ошибка запуска платежа.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры возвращаются в уведомлениях без изменений.
      x-robokassa-signature:
        parameter: SignatureValue
        password: Пароль#1
        documentation: https://docs.robokassa.ru/ru/pay-interface#signature
    post:
      tags:
        - Payments
      summary: Открыть платежную страницу через HTML-форму
      description: |
        POST-вариант запуска обычного платежа. Параметры передаются как
        `application/x-www-form-urlencoded`. Формирование `SignatureValue` и
        обработка ответа совпадают с GET-вариантом.
      operationId: createPaymentPost
      servers:
        - url: https://auth.robokassa.ru
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PaymentStartRequest"
      responses:
        "200":
          description: |
            HTML-страница с сообщением об ошибке параметров. Код прикладной
            ошибки передается внутри контекста страницы.
          content:
            text/html:
              schema:
                type: string
        "302":
          description: Платеж создан. Клиент перенаправляется на платежную страницу.
          headers:
            Location:
              description: Относительный URL созданной платежной страницы.
              required: true
              schema:
                type: string
                format: uri-reference
                example: /Merchant/Index/01234567-89ab-4cde-8f01-23456789abcd
        default:
          description: Транспортная ошибка запуска платежа.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры возвращаются в уведомлениях без изменений.
      x-robokassa-signature:
        parameter: SignatureValue
        password: Пароль#1
        documentation: https://docs.robokassa.ru/ru/pay-interface#signature

  /InvoiceServiceWebApi/api/CreateInvoice:
    post:
      tags:
        - Invoices
      summary: Создать счет
      description: |
        Создает одноразовую или многоразовую ссылку на оплату. Тело запроса —
        подписанный JWT в виде строки. JWT состоит из Header, Payload и Signature.

        Для подписи используется HMAC с выбранным алгоритмом. Секретный ключ
        составляется как `MerchantLogin:Пароль#1`.
      operationId: createInvoice
      servers:
        - url: https://services.robokassa.ru
      requestBody:
        $ref: "#/components/requestBodies/InvoiceJwt"
      responses:
        "200":
          description: |
            Результат обработки запроса. Invoice API возвращает HTTP 200 как при
            успешном создании счета, так и при прикладной ошибке. Результат нужно
            определять по полю `isSuccess`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/InvoiceCreateSuccess"
                  - $ref: "#/components/schemas/InvoiceError"
              examples:
                success:
                  summary: Счет создан
                  value:
                    id: 01234567-89ab-4cde-8f01-23456789abcd
                    invId: 1234567890
                    url: https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv
                    isSuccess: true
                malformedRequest:
                  summary: Некорректный JWT
                  value:
                    isSuccess: false
                    message: Некорректно составлен запрос
        default:
          description: Транспортная ошибка Invoice API.
      x-robokassa-jwt:
        payloadSchema: "#/components/schemas/InvoiceCreatePayload"
        documentation: https://docs.robokassa.ru/ru/invoice-api#create

  /InvoiceServiceWebApi/api/DeactivateInvoice:
    post:
      tags:
        - Invoices
      summary: Деактивировать счет
      description: |
        Деактивирует созданный счет или ссылку. В Payload необходимо передать
        `MerchantLogin` и один из идентификаторов: `EncodedId`, `Id` или `InvId`.
      operationId: deactivateInvoice
      servers:
        - url: https://services.robokassa.ru
      requestBody:
        $ref: "#/components/requestBodies/InvoiceJwt"
      responses:
        "200":
          description: |
            Результат обработки запроса. Прикладная ошибка, как и успешный
            результат, возвращается с HTTP 200 и определяется по `isSuccess`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/InvoiceActionSuccess"
                  - $ref: "#/components/schemas/InvoiceError"
              examples:
                success:
                  value:
                    isSuccess: true
        default:
          description: Транспортная ошибка Invoice API.
      x-robokassa-jwt:
        payloadSchema: "#/components/schemas/InvoiceDeactivatePayload"
        documentation: https://docs.robokassa.ru/ru/invoice-api#deactivate

  /InvoiceServiceWebApi/api/GetInvoiceInformationList:
    post:
      tags:
        - Invoices
      summary: Получить список счетов
      description: |
        Возвращает счета, соответствующие фильтрам из JWT Payload. Ответ содержит
        массив `invoiceInformationList`, общее количество `total` и признак
        `isSuccess`.
      operationId: listInvoices
      servers:
        - url: https://services.robokassa.ru
      requestBody:
        $ref: "#/components/requestBodies/InvoiceJwt"
      responses:
        "200":
          description: |
            Результат обработки запроса. Успешный список и прикладная ошибка
            возвращаются с HTTP 200 и различаются по `isSuccess`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/InvoiceInformationListResponse"
                  - $ref: "#/components/schemas/InvoiceError"
              examples:
                success:
                  value:
                    invoiceInformationList:
                      - id: 01234567-89ab-4cde-8f01-23456789abcd
                        invId: 1234567890
                        invoiceType: OneTime
                        created: 2026-07-23T09:54:27.010856+00:00
                        modified: 2026-07-23T09:56:54.907627+00:00
                        culture: ru
                        outSum: 1
                        expirationDate: 2026-07-23T09:56:54.907627+00:00
                        description: OpenAPI contract verification
                        invoiceItems: []
                        isCustomerNotificationEmailSent: false
                        invoiceStatus: Expired
                        invoicePaymentUrl: https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv
                        shortInvoicePaymentUrl: https://auth.robokassa.ru/Merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv
                        aliases: []
                        userFields: {}
                        payments: []
                        isWithoutFreeSale: false
                    total: 1
                    isSuccess: true
        default:
          description: Транспортная ошибка Invoice API.
      x-robokassa-jwt:
        payloadSchema: "#/components/schemas/InvoiceInformationFilter"
        documentation: https://docs.robokassa.ru/ru/invoice-api#status

  /Merchant/WebService/Service.asmx/OpStateExt:
    get:
      tags:
        - Operations
      summary: Получить расширенную информацию об операции
      description: |
        Возвращает состояние оплаты и реквизиты операции. Метод работает только
        в основном режиме и не возвращает тестовые платежи с `IsTest=1`.

        Подпись рассчитывается по формуле
        `MerchantLogin:InvoiceID:Пароль#2`.
      operationId: getOperationState
      servers:
        - url: https://auth.robokassa.ru
      parameters:
        - $ref: "#/components/parameters/MerchantLogin"
        - name: InvoiceID
          in: query
          required: true
          description: Номер счета магазина.
          schema:
            type: integer
            format: int64
        - name: Signature
          in: query
          required: true
          description: Контрольная сумма в шестнадцатеричном формате.
          schema:
            type: string
            pattern: "^[0-9A-Fa-f]+$"
      responses:
        "200":
          description: |
            Результат запроса. Прикладные ошибки передаются с HTTP 200 в
            `Result.Code` и `Result.Description`.
          content:
            text/xml:
              schema:
                $ref: "#/components/schemas/OperationStateResponse"
              examples:
                success:
                  summary: Структура успешного ответа
                  value: |
                    <OperationStateResponse>
                      <Result><Code>0</Code></Result>
                      <State>
                        <Code>100</Code>
                        <RequestDate>2026-07-22T10:00:00+03:00</RequestDate>
                        <StateDate>2026-07-22T09:59:00+03:00</StateDate>
                      </State>
                    </OperationStateResponse>
                operationNotFound:
                  summary: Операция не найдена
                  value: |
                    <OperationStateResponse xmlns="http://merchant.roboxchange.com/WebService/">
                      <Result>
                        <Code>3</Code>
                        <Description>Не удалось найти операцию</Description>
                      </Result>
                    </OperationStateResponse>
        default:
          description: Транспортная ошибка XML-интерфейса.

  /Merchant/WebService/Service.asmx/GetCurrencies:
    get:
      tags:
        - Reference
      summary: Получить доступные способы оплаты
      description: |
        Возвращает способы оплаты, доступные магазину. Список и ограничения
        зависят от настроек конкретного магазина.
      operationId: getCurrencies
      servers:
        - url: https://auth.robokassa.ru
      parameters:
        - $ref: "#/components/parameters/MerchantLogin"
        - name: Language
          in: query
          required: true
          description: Язык названий способов оплаты.
          schema:
            type: string
            enum:
              - ru
              - en
      responses:
        "200":
          description: |
            Результат запроса. Прикладные ошибки передаются с HTTP 200 в
            `Result.Code` и `Result.Description`.
          content:
            text/xml:
              schema:
                $ref: "#/components/schemas/CurrenciesList"
              examples:
                success:
                  value: |
                    <CurrenciesList xmlns="http://merchant.roboxchange.com/WebService/">
                      <Result><Code>0</Code></Result>
                      <Groups>
                        <Group Code="BankCard" Description="Банковской картой">
                          <Items>
                            <Currency Label="BankCardPSR" Alias="BankCard" Name="Банковская карта" />
                          </Items>
                        </Group>
                      </Groups>
                    </CurrenciesList>
        default:
          description: Транспортная ошибка XML-интерфейса.

  /RefundService/Refund/Create:
    post:
      tags:
        - Refunds
      summary: Создать заявку на возврат
      description: |
        Создает полный или частичный возврат по завершенной операции. Тело — JWT,
        подписанный `Password3` алгоритмом HS256, HS384 или HS512.

        Метод требует предварительного подключения API возвратов для магазина.
        Реальный успешный возврат в рамках проверки спецификации не выполнялся.
      operationId: createRefund
      servers:
        - url: https://services.robokassa.ru
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              contentMediaType: application/jwt
              description: Подписанный JWT, переданный как JSON-строка.
              pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$'
      responses:
        "200":
          description: Документированный результат создания заявки.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundCreateResponse"
        "401":
          description: Неверный Password3 или API возвратов не подключен магазину.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundCreateResponse"
              example:
                success: false
                message: Signature key is not exists or partner have not access to API
                requestId: null
        default:
          description: Транспортная ошибка Refund API.
      x-robokassa-jwt:
        payloadSchema: "#/components/schemas/RefundPayload"
        password: Password3
        documentation: https://docs.robokassa.ru/ru/refund-api#refund-initiation

  /RefundService/Refund/GetState:
    get:
      tags:
        - Refunds
      summary: Получить состояние возврата
      operationId: getRefundState
      servers:
        - url: https://services.robokassa.ru
      parameters:
        - name: id
          in: query
          required: true
          description: "`requestId`, полученный при создании возврата."
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Документированное состояние возврата.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundState"
        "400":
          description: Идентификатор некорректен или заявка не существует.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageError"
              example:
                message: Id is invalid or request id does not exist
        default:
          description: Транспортная ошибка Refund API.

  /Merchant/Payment/Confirm:
    post:
      tags:
        - Holding
      summary: Подтвердить списание удержанных средств
      description: |
        Завершает двухстадийный платеж в состоянии HOLD. Запрос можно выполнить
        только один раз. Если передан новый `Receipt`, сумма и состав корзины могут
        быть изменены только в меньшую сторону.

        Вызов изменяет состояние платежа и приводит к списанию средств.
      operationId: confirmHold
      servers:
        - url: https://auth.robokassa.ru
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/HoldConfirmRequest"
      responses:
        default:
          description: |
            Ответ интерфейса не проверен. Результат списания необходимо
            подтверждать через ResultURL, ResultUrl2 или OpStateExt.
      x-robokassa-signature:
        password: Пароль#1
        formulaWithoutReceipt: MerchantLogin:OutSum:InvoiceID:Пароль#1
        formulaWithReceipt: MerchantLogin:OutSum:InvoiceID:Receipt:Пароль#1
        implementation: https://github.com/robokassa/cms-wordpress/blob/92c8c6aceffe283f89319ac41ead78bc573bb361/wp_robokassa.php#L1555

  /Merchant/Payment/Cancel:
    post:
      tags:
        - Holding
      summary: Отменить холдирование
      description: |
        Отменяет двухстадийный платеж в состоянии HOLD. `OutSum` передается в
        запросе, но в строке подписи вместо суммы используется пустой сегмент.

        Вызов изменяет состояние платежа и отменяет авторизацию средств.
      operationId: cancelHold
      servers:
        - url: https://auth.robokassa.ru
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/HoldCancelRequest"
      responses:
        default:
          description: |
            Ответ интерфейса не проверен. Состояние операции необходимо
            подтверждать через ResultUrl2 или OpStateExt.
      x-robokassa-signature:
        password: Пароль#1
        formula: "MerchantLogin::InvoiceID:Пароль#1"
        implementation: https://github.com/robokassa/cms-wordpress/blob/92c8c6aceffe283f89319ac41ead78bc573bb361/wp_robokassa.php#L1579

  /Merchant/Recurring:
    post:
      tags:
        - Recurring
      summary: Создать повторный платеж
      description: |
        Инициирует дочерний платеж после успешной материнской операции с
        `Recurring=true`. `PreviousInvoiceID` обязателен, но не включается в
        расчет `SignatureValue`.

        Вызов может привести к повторному списанию средств без участия покупателя.
      operationId: createRecurringPayment
      servers:
        - url: https://auth.robokassa.ru
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/RecurringPaymentRequest"
      responses:
        "200":
          description: |
            Ответ означает создание операции, но не гарантирует успешное списание.
            Итог проверяется по уведомлениям или OpStateExt.
          content:
            text/plain:
              schema:
                type: string
              example: OK156
        default:
          description: Транспортная ошибка запуска рекуррентного платежа.
      x-robokassa-signature:
        password: Пароль#1
        note: PreviousInvoiceID не включается в подпись.
        documentation: https://docs.robokassa.ru/ru/recurring-payments#request-parameters
        implementation: https://github.com/robokassa/cms-wordpress/blob/92c8c6aceffe283f89319ac41ead78bc573bb361/classes/Robokassa/Payment/RobokassaPayAPI.php#L742

  /SMS/:
    get:
      tags:
        - Messaging
      summary: Отправить SMS методом GET
      operationId: sendSmsGet
      servers:
        - url: https://services.robokassa.ru
      parameters:
        - $ref: "#/components/parameters/SmsLogin"
        - $ref: "#/components/parameters/SmsPhone"
        - $ref: "#/components/parameters/SmsMessage"
        - $ref: "#/components/parameters/SmsSignature"
      responses:
        "200":
          description: Результат обработки запроса.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmsResponse"
        default:
          description: Транспортная ошибка SMS-сервиса.
      x-robokassa-signature:
        password: Пароль#1
        formula: login:phone:message:Пароль#1
        implementation: https://github.com/robokassa/cms-wordpress/blob/92c8c6aceffe283f89319ac41ead78bc573bb361/classes/Robokassa/Payment/RobokassaPayAPI.php#L690
    post:
      tags:
        - Messaging
      summary: Отправить SMS методом POST
      operationId: sendSmsPost
      servers:
        - url: https://services.robokassa.ru
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SmsRequest"
      responses:
        "200":
          description: Результат обработки запроса.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmsResponse"
        default:
          description: Транспортная ошибка SMS-сервиса.
      x-robokassa-signature:
        password: Пароль#1
        formula: login:phone:message:Пароль#1
        documentation: https://docs.robokassa.ru/ru/sms-notifications#request-parameters

webhooks:
  paymentResult:
    post:
      summary: Уведомление об успешной оплате на ResultURL
      description: |
        Robokassa отправляет данные на ResultURL магазина. Получатель обязан
        проверить `SignatureValue` по формуле
        `OutSum:InvId:Пароль#2:Shp_*` и только после этого изменить состояние заказа.
      operationId: paymentResultNotification
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PaymentResult"
      responses:
        "200":
          $ref: "#/components/responses/ResultUrlAccepted"
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Все переданные при запуске платежа параметры Shp_*.
    get:
      summary: Уведомление об успешной оплате на ResultURL методом GET
      description: |
        GET используется, если этот метод выбран в технических настройках магазина.
        Проверка подписи и формат ответа совпадают с POST-уведомлением.
      operationId: paymentResultNotificationGet
      parameters:
        - $ref: "#/components/parameters/ResultOutSum"
        - $ref: "#/components/parameters/ResultInvId"
        - $ref: "#/components/parameters/ResultSignatureValue"
        - name: Fee
          in: query
          description: Комиссия Robokassa.
          schema:
            type: string
        - name: EMail
          in: query
          description: Email покупателя.
          schema:
            type: string
            format: email
        - name: PaymentMethod
          in: query
          description: Использованный способ оплаты.
          schema:
            type: string
        - name: IncCurrLabel
          in: query
          description: Валюта оплаты.
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/ResultUrlAccepted"
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Все переданные при запуске платежа параметры Shp_*.

  paymentResult2:
    post:
      summary: Дополнительное уведомление на ResultUrl2
      description: |
        Серверное уведомление в формате JWS Compact Serialization. Для холдов это
        единственный способ получить состояние `HOLD`. Уведомление всегда
        отправляется методом POST.

        Подпись JWS рекомендуется проверять сертификатом Robokassa до обработки
        полей `data`.
      operationId: paymentResult2Notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              contentMediaType: application/jose
              pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$'
              description: JWS в компактном представлении.
      responses:
        "200":
          description: Уведомление принято магазином.
        "400":
          description: Некорректный формат JWS.
      x-jws-decoded-schema: "#/components/schemas/ResultUrl2Notification"
      x-jws-certificate: https://docs.robokassa.ru/media/files/jwtsign.cer
      x-implementation: https://github.com/robokassa/cms-wordpress/blob/92c8c6aceffe283f89319ac41ead78bc573bb361/wp_robokassa.php#L840

  paymentSuccessRedirect:
    get:
      summary: Возврат покупателя на SuccessURL методом GET
      description: |
        Браузерный редирект после успешной оплаты. Не используйте его как
        единственное подтверждение платежа — состояние заказа меняйте по ResultURL.
      operationId: paymentSuccessRedirectGet
      parameters:
        - $ref: "#/components/parameters/ResultOutSum"
        - $ref: "#/components/parameters/ResultInvId"
        - $ref: "#/components/parameters/SuccessSignatureValue"
        - $ref: "#/components/parameters/RedirectCulture"
      responses:
        "200":
          description: Страница магазина, отображаемая покупателю.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры, переданные при запуске платежа.
    post:
      summary: Возврат покупателя на SuccessURL методом POST
      description: |
        Браузерный редирект после успешной оплаты. Параметры передаются как
        `application/x-www-form-urlencoded`. Основное подтверждение приходит на ResultURL.
      operationId: paymentSuccessRedirectPost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PaymentSuccessRedirect"
      responses:
        "200":
          description: Страница магазина, отображаемая покупателю.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры, переданные при запуске платежа.

  paymentFailRedirect:
    get:
      summary: Возврат покупателя на FailURL методом GET
      description: |
        Браузерный редирект после отказа или прерывания оплаты. Он не означает
        окончательную отмену операции; актуальное состояние проверяйте отдельно.
      operationId: paymentFailRedirectGet
      parameters:
        - $ref: "#/components/parameters/ResultOutSum"
        - $ref: "#/components/parameters/ResultInvId"
        - $ref: "#/components/parameters/RedirectCulture"
      responses:
        "200":
          description: Страница магазина, отображаемая покупателю.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры, переданные при запуске платежа.
    post:
      summary: Возврат покупателя на FailURL методом POST
      description: |
        Браузерный редирект после отказа или прерывания оплаты. Параметры
        передаются как `application/x-www-form-urlencoded`.
      operationId: paymentFailRedirectPost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PaymentFailRedirect"
      responses:
        "200":
          description: Страница магазина, отображаемая покупателю.
      x-robokassa-custom-parameters:
        prefix: Shp_
        description: Пользовательские параметры, переданные при запуске платежа.

components:
  requestBodies:
    InvoiceJwt:
      required: true
      description: Подписанный JWT, переданный в теле как JSON-строка.
      content:
        application/json:
          schema:
            type: string
            contentMediaType: application/jwt
            description: Подписанный JWT в формате `header.payload.signature`.
            pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$'
          examples:
            token:
              summary: Структура JSON-строки
              value: header.payload.signature

  parameters:
    MerchantLogin:
      name: MerchantLogin
      in: query
      required: true
      description: Идентификатор магазина.
      schema:
        type: string
    OutSum:
      name: OutSum
      in: query
      required: true
      description: Сумма к оплате с точкой в качестве десятичного разделителя.
      schema:
        type: string
        pattern: '^\d+(\.\d+)?$'
        example: "100.00"
    InvId:
      name: InvId
      in: query
      required: false
      description: Уникальный номер счета магазина.
      schema:
        type: integer
        format: int64
        minimum: 1
        maximum: 9223372036854775807
    SignatureValue:
      name: SignatureValue
      in: query
      required: true
      description: Подпись запроса, рассчитанная с использованием Пароля#1.
      schema:
        type: string
    ResultOutSum:
      name: OutSum
      in: query
      required: true
      description: Сумма платежа в точном формате из уведомления.
      schema:
        type: string
        example: "100.000000"
    ResultInvId:
      name: InvId
      in: query
      required: true
      description: Номер счета магазина.
      schema:
        type: string
        example: "450009"
    ResultSignatureValue:
      name: SignatureValue
      in: query
      required: true
      description: Подпись уведомления, рассчитанная с использованием Пароля#2.
      schema:
        type: string
    SuccessSignatureValue:
      name: SignatureValue
      in: query
      required: true
      description: Подпись SuccessURL, рассчитанная с использованием Пароля#1.
      schema:
        type: string
    RedirectCulture:
      name: Culture
      in: query
      required: false
      description: Язык платежной страницы.
      schema:
        type: string
        enum:
          - ru
          - en
    SmsLogin:
      name: login
      in: query
      required: true
      description: Идентификатор магазина.
      schema:
        type: string
    SmsPhone:
      name: phone
      in: query
      required: true
      description: Номер телефона в международном формате без символа `+`.
      schema:
        type: string
        pattern: '^\d+$'
        example: "79999999999"
    SmsMessage:
      name: message
      in: query
      required: true
      description: Текст сообщения в UTF-8, не более 128 символов.
      schema:
        type: string
        maxLength: 128
    SmsSignature:
      name: signature
      in: query
      required: true
      description: Подпись `login:phone:message:Пароль#1`.
      schema:
        type: string

  responses:
    ResultUrlAccepted:
      description: Уведомление принято.
      content:
        text/plain:
          schema:
            type: string
            pattern: '^OK\d+$'
            example: OK450009

  schemas:
    PaymentStartRequest:
      type: object
      required:
        - MerchantLogin
        - OutSum
        - SignatureValue
      properties:
        MerchantLogin:
          type: string
        OutSum:
          type: string
          pattern: '^\d+(\.\d+)?$'
          example: "100.00"
        SignatureValue:
          type: string
        InvId:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854775807
        Description:
          type: string
          maxLength: 100
        Email:
          type: string
          format: email
        IncCurrLabel:
          type: string
        Culture:
          type: string
          enum:
            - ru
            - en
        Encoding:
          type: string
          default: UTF-8
        IsTest:
          type: integer
          enum:
            - 0
            - 1
        ExpirationDate:
          type: string
        Receipt:
          type: string
        StepByStep:
          type: boolean
        PaymentMethods:
          type: array
          items:
            type: string
        ResultUrl2:
          type: string
          format: uri
        SuccessUrl2:
          type: string
          format: uri
        SuccessUrl2Method:
          $ref: "#/components/schemas/RedirectMethod"
        FailUrl2:
          type: string
          format: uri
        FailUrl2Method:
          $ref: "#/components/schemas/RedirectMethod"
        Token:
          type: string
        Recurring:
          type: boolean
      additionalProperties:
        type: string
      description: Дополнительные поля допускаются только для параметров с префиксом `Shp_`.

    PaymentSuccessRedirect:
      type: object
      required:
        - OutSum
        - InvId
        - SignatureValue
      properties:
        OutSum:
          type: string
        InvId:
          type: string
        SignatureValue:
          type: string
          description: Подпись с использованием Пароля#1.
        Culture:
          type: string
          enum:
            - ru
            - en
      additionalProperties:
        type: string

    PaymentFailRedirect:
      type: object
      required:
        - OutSum
        - InvId
      properties:
        OutSum:
          type: string
        InvId:
          type: string
        Culture:
          type: string
          enum:
            - ru
            - en
      additionalProperties:
        type: string

    HoldConfirmRequest:
      type: object
      required:
        - MerchantLogin
        - InvoiceID
        - OutSum
        - SignatureValue
      properties:
        MerchantLogin:
          type: string
        InvoiceID:
          type: integer
          format: int64
        OutSum:
          type: string
          pattern: '^\d+(\.\d+)?$'
        Receipt:
          type: string
          description: Обновленный JSON чека в URL-кодировке.
        SignatureValue:
          type: string

    HoldCancelRequest:
      type: object
      required:
        - MerchantLogin
        - InvoiceID
        - OutSum
        - SignatureValue
      properties:
        MerchantLogin:
          type: string
        InvoiceID:
          type: integer
          format: int64
        OutSum:
          type: string
          description: Передается в запросе, но не включается в подпись.
        SignatureValue:
          type: string

    RecurringPaymentRequest:
      type: object
      required:
        - MerchantLogin
        - InvoiceID
        - PreviousInvoiceID
        - OutSum
        - SignatureValue
      properties:
        MerchantLogin:
          type: string
        InvoiceID:
          type: integer
          format: int64
          minimum: 1
        PreviousInvoiceID:
          type: integer
          format: int64
          minimum: 1
          description: Номер успешно оплаченной материнской операции.
        OutSum:
          type: string
          pattern: '^\d+(\.\d+)?$'
        Description:
          type: string
        Receipt:
          type: string
          description: JSON чека в URL-кодировке.
        IsTest:
          type: integer
          enum:
            - 1
        SignatureValue:
          type: string
      additionalProperties:
        type: string
      description: Дополнительные поля допускаются только для параметров с префиксом `Shp_`.

    SmsRequest:
      type: object
      required:
        - login
        - phone
        - message
        - signature
      properties:
        login:
          type: string
        phone:
          type: string
          pattern: '^\d+$'
        message:
          type: string
          maxLength: 128
        signature:
          type: string

    SmsResponse:
      type: object
      required:
        - result
      properties:
        result:
          oneOf:
            - type: boolean
            - type: integer
              enum:
                - 0
                - 1
        count:
          type: integer
          minimum: 0
        errorCode:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 1000
            - 9999
        errorMessage:
          type:
            - string
            - "null"

    ResultUrl2Notification:
      type: object
      required:
        - header
        - data
      properties:
        header:
          type: object
          required:
            - type
            - version
            - timestamp
          properties:
            type:
              type: string
              example: PaymentStateNotification
            version:
              type: string
              example: 1.0.0
            timestamp:
              type: string
              description: Unix timestamp в виде строки.
        data:
          type: object
          required:
            - shop
            - opKey
            - invId
            - paymentMethod
            - incSum
            - state
          properties:
            shop:
              type: string
            opKey:
              type: string
            invId:
              type: string
            paymentMethod:
              type: string
            incSum:
              type: string
            state:
              type: string
              examples:
                - HOLD
                - OK

    RedirectMethod:
      type: string
      enum:
        - GET
        - POST

    InvoiceCreatePayload:
      type: object
      description: Payload до Base64Url-кодирования и подписания JWT.
      required:
        - MerchantLogin
        - InvoiceType
        - OutSum
      properties:
        MerchantLogin:
          type: string
          description: Логин магазина.
        InvoiceType:
          type: string
          enum:
            - OneTime
            - Reusable
        Culture:
          type: string
          enum:
            - ru
            - en
        InvId:
          type:
            - integer
            - "null"
          format: int64
        OutSum:
          type: number
          exclusiveMinimum: 0
        Description:
          type: string
        MerchantComments:
          type: string
        UserFields:
          type: object
          additionalProperties:
            type: string
        InvoiceItems:
          type: array
          items:
            $ref: "#/components/schemas/InvoiceItem"
        SuccessUrl2Data:
          $ref: "#/components/schemas/RedirectData"
        FailUrl2Data:
          $ref: "#/components/schemas/RedirectData"

    InvoiceDeactivatePayload:
      type: object
      required:
        - MerchantLogin
      properties:
        MerchantLogin:
          type: string
          description: Логин магазина.
        EncodedId:
          type: string
          description: Последний сегмент ссылки на оплату счета.
        Id:
          type: string
          format: uuid
          description: Внутренний идентификатор счета Invoice API.
        InvId:
          type: integer
          format: int64
          description: Номер счета магазина.
      oneOf:
        - required:
            - EncodedId
        - required:
            - Id
        - required:
            - InvId

    InvoiceInformationFilter:
      type: object
      required:
        - MerchantLogin
        - CurrentPage
        - PageSize
        - InvoiceStatuses
        - DateFrom
        - DateTo
        - InvoiceTypes
      properties:
        MerchantLogin:
          type: string
          description: Логин магазина.
        CurrentPage:
          type: integer
          minimum: 1
        PageSize:
          type: integer
          minimum: 1
        InvoiceStatuses:
          type: array
          items:
            type: string
            enum:
              - Paid
              - Expired
              - Notpaid
        Keywords:
          type: string
          description: Поиск по сумме, идентификатору, описанию или email.
        DateFrom:
          type: string
          format: date-time
        DateTo:
          type: string
          format: date-time
        IsAscending:
          type: boolean
        InvoiceTypes:
          type: array
          items:
            type: string
            enum:
              - OneTime
              - Reusable
        PaymentAliases:
          type: array
          items:
            type: string
        SumFrom:
          type: number
        SumTo:
          type: number

    InvoiceItem:
      type: object
      required:
        - Name
        - Quantity
        - Cost
        - Tax
      properties:
        Name:
          type: string
        Quantity:
          type: number
          exclusiveMinimum: 0
        Cost:
          type: number
          minimum: 0
        Tax:
          type: string
          description: Ставка НДС из документации по фискализации.
        PaymentMethod:
          type: string
          description: Признак способа расчета.
        PaymentObject:
          type: string
          description: Признак предмета расчета.
        NomenclatureCode:
          type: string

    InvoiceCreateSuccess:
      type: object
      required:
        - id
        - invId
        - url
        - isSuccess
      properties:
        id:
          type: string
          format: uuid
          description: Внутренний идентификатор счета Invoice API.
        invId:
          type: integer
          format: int64
          description: Номер счета магазина.
        url:
          type: string
          format: uri
          description: Ссылка на оплату счета.
        isSuccess:
          type: boolean
          const: true

    InvoiceActionSuccess:
      type: object
      required:
        - isSuccess
      properties:
        isSuccess:
          type: boolean
          const: true

    InvoiceError:
      type: object
      required:
        - isSuccess
        - message
      properties:
        isSuccess:
          type: boolean
          const: false
        message:
          type: string
          description: Описание прикладной ошибки Invoice API.

    InvoiceInformationListResponse:
      type: object
      required:
        - invoiceInformationList
        - total
        - isSuccess
      properties:
        invoiceInformationList:
          type: array
          items:
            $ref: "#/components/schemas/InvoiceInformation"
        total:
          type: integer
          minimum: 0
        isSuccess:
          type: boolean
          const: true

    InvoiceInformation:
      type: object
      required:
        - id
        - invId
        - invoiceType
        - created
        - modified
        - outSum
        - invoiceItems
        - isCustomerNotificationEmailSent
        - invoiceStatus
        - aliases
        - userFields
        - payments
        - isWithoutFreeSale
      properties:
        id:
          type: string
          format: uuid
        invId:
          type: integer
          format: int64
        invoiceType:
          type: string
          enum:
            - OneTime
            - Reusable
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        culture:
          type:
            - string
            - "null"
        outSum:
          type: number
        expirationDate:
          type:
            - string
            - "null"
          format: date-time
        description:
          type:
            - string
            - "null"
        invoiceItems:
          type: array
          items:
            type: object
            additionalProperties: true
        isCustomerNotificationEmailSent:
          type: boolean
        opId:
          type:
            - string
            - "null"
          description: Идентификатор связанной платежной операции.
        paymentMethod:
          type:
            - string
            - "null"
          description: Использованный способ оплаты.
        invoiceStatus:
          type: string
          enum:
            - Paid
            - Expired
            - Notpaid
        invoicePaymentUrl:
          type:
            - string
            - "null"
          format: uri
        shortInvoicePaymentUrl:
          type:
            - string
            - "null"
          format: uri
        aliases:
          type: array
          items:
            type: string
        paymentAlias:
          type:
            - string
            - "null"
        paymentCardNumber:
          type:
            - string
            - "null"
          description: Маскированный номер карты, если применимо.
        userFields:
          type: object
          additionalProperties:
            type: string
        payments:
          type: array
          items:
            type: object
            additionalProperties: true
        isWithoutFreeSale:
          type: boolean

    RedirectData:
      type: object
      required:
        - Url
        - Method
      properties:
        Url:
          type: string
          format: uri
        Method:
          $ref: "#/components/schemas/RedirectMethod"

    PaymentResult:
      type: object
      required:
        - OutSum
        - InvId
        - SignatureValue
      properties:
        OutSum:
          type: string
          description: Сумма платежа в точном формате из уведомления.
          example: "100.000000"
        InvId:
          type: string
          description: Номер счета магазина.
          example: "450009"
        Fee:
          type: string
          description: Комиссия Robokassa.
        EMail:
          type: string
          format: email
        SignatureValue:
          type: string
          description: Подпись уведомления с использованием Пароля#2.
        PaymentMethod:
          type: string
        IncCurrLabel:
          type: string

    OperationStateResponse:
      type: object
      xml:
        name: OperationStateResponse
        namespace: http://merchant.roboxchange.com/WebService/
      required:
        - Result
      properties:
        Result:
          $ref: "#/components/schemas/OperationResult"
        State:
          $ref: "#/components/schemas/OperationState"
        Info:
          $ref: "#/components/schemas/OperationInfo"
        UserFields:
          $ref: "#/components/schemas/OperationUserFields"

    OperationResult:
      type: object
      required:
        - Code
      properties:
        Code:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 1000
        Description:
          type: string

    OperationState:
      type: object
      properties:
        Code:
          type: integer
          enum:
            - 5
            - 10
            - 20
            - 50
            - 60
            - 80
            - 100
        RequestDate:
          type: string
          format: date-time
        StateDate:
          type: string
          format: date-time

    OperationInfo:
      type: object
      properties:
        IncCurrLabel:
          type: string
        IncSum:
          type: string
        IncAccount:
          type: string
        PaymentMethod:
          type: object
          properties:
            Code:
              type: string
            Description:
              type: string
        OutCurrLabel:
          type: string
        OutSum:
          type: string
        OpKey:
          type: string
        BankCardRRN:
          type: string

    OperationUserFields:
      type: object
      properties:
        Field:
          type: array
          items:
            type: object
            properties:
              Name:
                type: string
              Value:
                type: string

    CurrenciesList:
      type: object
      xml:
        name: CurrenciesList
        namespace: http://merchant.roboxchange.com/WebService/
      required:
        - Result
      properties:
        Result:
          $ref: "#/components/schemas/OperationResult"
        Groups:
          type: object
          properties:
            Group:
              type: array
              items:
                $ref: "#/components/schemas/CurrencyGroup"

    CurrencyGroup:
      type: object
      properties:
        Code:
          type: string
          xml:
            attribute: true
        Description:
          type: string
          xml:
            attribute: true
        Items:
          type: object
          properties:
            Currency:
              type: array
              items:
                $ref: "#/components/schemas/Currency"

    Currency:
      type: object
      properties:
        Label:
          type: string
          xml:
            attribute: true
        Alias:
          type: string
          xml:
            attribute: true
        Name:
          type: string
          xml:
            attribute: true
        MinValue:
          type: string
          xml:
            attribute: true
        MaxValue:
          type: string
          xml:
            attribute: true

    RefundPayload:
      type: object
      required:
        - OpKey
      properties:
        OpKey:
          type: string
          description: Идентификатор завершенной платежной операции.
        RefundSum:
          type: number
          exclusiveMinimum: 0
          description: Сумма частичного возврата. Для полного возврата не передается.
        InvoiceItems:
          type: array
          description: Позиции для формирования чека возврата прихода.
          items:
            $ref: "#/components/schemas/InvoiceItem"

    RefundCreateResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
        message:
          type:
            - string
            - "null"
        requestId:
          type:
            - string
            - "null"
          format: uuid

    RefundState:
      type: object
      required:
        - requestId
        - amount
        - label
      properties:
        requestId:
          type: string
          format: uuid
        amount:
          type: number
        label:
          type: string
          description: Состояние заявки на возврат.

    MessageError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
