openapi: 3.0.3
info:
  title: Vality Disputes
  version: 0.0.1
  description: |

    ## Описание
    Vality Disputes предоставляет операции для заявок в системе для открытия спора и предназначен для мерчантов.

    ### Тип содержимого и кодировка

    Система принимает данные либо в формате JSON и возвращает данные в формате JSON и кодировке UTF-8:

    ```
      Content-Type: application/json; charset=utf-8
    ```
  termsOfService: https://vality.dev
  contact:
    name: Команда техподдержки
    email: support@vality.dev
servers:
  - url: https://api.vality.dev/disputes
security:
  - bearerAuth: []
tags:
  - name: disputes
    x-displayName: Disputes
    description: |
      Диспуты - это открытые споры по платежам.
  - name: notifications
    x-displayName: Notifications
    description: |
      Спецификация определяет протокол для доставки уведомлений о изменении статуса диспута в вашей организации. Уведомления доставляются системой в виде HTTP-запросов, содержащий сообщение JSON на URL-адрес, указанный при создании диспута. Обработчики таких запросов должны быть реализованы на стороне вашего серверного кода в соответствии со спецификацией.
paths:
  /create:
    post:
      operationId: create
      summary: Создать диспут
      tags:
        - disputes
      requestBody:
        description: Параметры диспута
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - invoiceId
                - paymentId
                - attachments
              properties:
                invoiceId:
                  $ref: '#/components/schemas/InvoiceID'
                paymentId:
                  $ref: '#/components/schemas/PaymentID'
                attachments:
                  type: array
                  items:
                    type: object
                    required:
                      - data
                      - mimeType
                    properties:
                      data:
                        type: string
                        format: byte
                        description: base64-encoded file contents
                        example: U3dhZ2dlciByb2Nrcw==
                      mimeType:
                        type: string
                        description: Тип файла
                        example: application/pdf
                amount:
                  description: Сумма платежа в минорных единицах, которая будет оспариваться в диспуте
                  type: integer
                  format: int64
                  minimum: 1
                reason:
                  type: string
                  description: Причина открытия диспута
                notificationUrl:
                  type: string
                  format: http-url
                  maxLength: 1000
                  description: URL-адрес, на который будут приходить уведомления о изменении статуса диспута
                  example: https://my.site/order/cb
      responses:
        '200':
          description: Диспут создан
          content:
            application/json:
              schema:
                type: object
                required:
                  - disputeId
                properties:
                  disputeId:
                    $ref: '#/components/schemas/DisputeId'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /status:
    get:
      operationId: status
      summary: Получить статус диспута
      tags:
        - disputes
      parameters:
        - name: disputeId
          description: Идентификатор диспута
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/DisputeId'
      responses:
        '200':
          description: Получен статус диспута
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    description: Статус диспута
                    type: string
                    enum:
                      - pending
                      - succeeded
                      - failed
                  reason:
                    description: Причина фейла
                    $ref: '#/components/schemas/GeneralError'
                  changedAmount:
                    description: Измененная сумма платежа в минорных единицах
                    type: integer
                    format: int64
                    minimum: 1
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /notify:
    servers:
      - url: https://merchant.site
    post:
      security: []
      operationId: notify
      summary: Уведомление об изменении статуса диспута
      tags:
        - notifications
      requestBody:
        description: Параметры диспута
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - disputeId
                - invoiceId
                - paymentId
                - status
              properties:
                disputeId:
                  $ref: '#/components/schemas/DisputeId'
                invoiceId:
                  $ref: '#/components/schemas/InvoiceID'
                paymentId:
                  $ref: '#/components/schemas/PaymentID'
                status:
                  description: Статус диспута
                  type: string
                  enum:
                    - succeeded
                    - failed
                reason:
                  description: Причина фейла
                  $ref: '#/components/schemas/GeneralError'
                changedAmount:
                    description: Измененная сумма платежа в минорных единицах
                    type: integer
                    format: int64
                    minimum: 1
      responses:
        '200':
          description: Уведомление обработано
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Взаимодействие между мерчантом и [системой](https://vality.dev/) осуществляется по защищенному протоколу (HTTPS). HTTP-запросы по нешифрованному каналу не поддерживаются.

        Ознакомиться с деталями авторизации запросов к API можно в [данной](https://developer.vality.dev/docs/payments/overview/#api) статье.

        Управлять API-ключами можно в [личном кабинете](https://dashboard.vality.dev/). Значение ключа следует передать в заголовке `Authorization`:

        ```
        Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M...
        ```

        Ключи не разделяются на тестовые и боевые. Для проведения тестовых транзакций используйте идентификатор тестового магазина.

        **Важно! Не передавайте API-ключ третьим лицам!**
  responses:
    NotFound:
      description: Target resource not found
    Unauthorized:
      description: Authorization error
    InvalidRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  schemas:
    InvoiceID:
      description: Идентификатор инвоиса, на основе которого был создан платёж
      type: string
      maxLength: 40
      minLength: 1
    PaymentID:
      description: Идентификатор платежа
      type: string
      maxLength: 40
      minLength: 1
    DisputeId:
      description: Идентификатор диспута
      type: string
      maxLength: 40
      minLength: 1
    GeneralError:
      type: object
      required:
        - message
      properties:
        message:
          description: Человекочитаемое описание ошибки
          type: string