treasurer/openapi.yaml

openapi: 3.0.1
info:
  title: Сервис-аггрегатор платёжных решений
  description: |-
    Область отвественности сервиса - получить на вход сумму, которуб надо запросить, и список действий, который надо выполнить, в зависимости от события оплаты
  version: 1.0.0

tags:
  - name: pay

paths:

  /available:
    get:
      operationId: getAvailablePayments
      description: метод для получения списка доступных вариантов для оплаты
      tags:
        - pay
      responses:
        '200':
          description: список доступных вариантов оплаты
          content:
            application/json:
              schema:
                type: array
                example: ["qiwi", "visa", "tinkoff"]
                items:
                  type: string
  
  /yandex/payment/status/waiting:
    post:
      operationId: setYandexPaymentStatusWaiting
      description: Метод для установки статуса платежа "Ожидание"
      tags:
        - pay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPaymentStatusRequest'
      responses:
        '200':
          description: Успешная установка статуса
        '500':
          description: Внутренняя ошибка

  /yandex/payment/status/succeeded:
    post:
      operationId: setYandexPaymentStatusSucceeded
      description: Метод для установки статуса платежа "Успешно"
      tags:
        - pay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPaymentStatusRequest'
      responses:
        '200':
          description: Успешная установка статуса
        '500':
          description: Внутренняя ошибка

  /yandex/payment/status/canceled:
    post:
      operationId: setYandexPaymentStatusCanceled
      description: Метод для установки статуса платежа "Отменён"
      tags:
        - pay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPaymentStatusRequest'
      responses:
        '200':
          description: Успешная установка статуса
        '500':
          description: Внутренняя ошибка

  /yandex/refund/status/succeeded:
    post:
      operationId: setYandexRefundStatusSucceeded
      description: Метод для установки статуса возврата "Успешно"
      tags:
        - pay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPaymentStatusRequest'
      responses:
        '200':
          description: Успешная установка статуса
        '500':
          description: Внутренняя ошибка

components:
  schemas:

    SetPaymentStatusRequest:
      type: object
      required: [type, event, object]
      properties:
        type:
          type: string
          description: Тип объекта. Фиксированное значение — notification (уведомление)
          example: "notification"
        event:
          $ref: '#/components/schemas/Event'
        object:
          $ref: '#/components/schemas/YandexPayment'

    YandexPayment:
      type: object
      required: [id, status, amount, recipient, created_at, test, paid, refundable]
      properties:
        id:
          type: string
          description: Идентификатор платежа в ЮKassa
          example: "asdf7as6df7a5f5asdf"
        status:
          $ref: '#/components/schemas/PaymentStatus'
        amount:
          $ref: '#/components/schemas/Amount'
        income_amount:
          $ref: '#/components/schemas/Amount'
        recipient:
          $ref: '#/components/schemas/Recipient'
        description:
          type: string
          description: Описание
          example: "Описание"
        payment_method:
          type: object
          description: Структура метода платежа (может отличаться от способа платежа)
        captured_at:
          type: string
          description: Время подтверждения платежа
        expires_at:
          type: string
          description: Время, до которого вы можете бесплатно отменить или подтвердить платеж
        created_at:
          type: string
          description: Время создания заказа
        confirmation:
          type: object
          description: Выбранный способ подтверждения платежа
        test:
          type: boolean
          description: Признак тестовой операции
        refunded_amount:
          $ref: '#/components/schemas/Amount'
        paid:
          type: boolean
          description: Признак оплаты заказа
        refundable:
          type: boolean
          description: Возможность провести возврат по API

    Amount:
      type: object
      required: [value, currency]
      properties:
        value:
          type: string
          description: Сумма в выбранной валюте
          example: "10.00"
        currency:
          type: string
          description: Трехбуквенный код валюты в формате ISO-4217
          example: "RUB"

    Recipient:
      type: object
      required: [account_id, gateway_id]
      properties:
        account_id:
          type: string
          description: Идентификатор магазина в ЮKassa
        gateway_id:
          type: string
          description: Идентификатор субаккаунта

    PaymentStatus:
      type: string
      enum: ["waiting_for_capture", "pending", "succeeded", "canceled"]

    Event:
      type: string
      enum: ["payment.waiting_for_capture", "payment.succeeded", "payment.canceled", "refund.succeeded"]