openapi: 3.0.3
info:
  title: 'Документация API Zenpayments'
  description: 'Документация для автоматизации работы с заказами Zenpayments'
  version: 1.0.0
servers:
  -
    url: 'https://zenpayments.ru'
tags:
  -
    name: Заказы
    description: ''
  -
    name: Инвойсы
    description: ''
  -
    name: Возвраты
    description: "  Для оформления возврата вам нужно знать номер платежа и id позиций в чеке. Номер платежа\n  вы можете узнать в ЛК, либо поймав вебхук `payment.accepted`.\n\n  Список позиций в чеке (и их id) вы можете узнать, выполнив запрос методом \"Список возвратов\n  по платежу\". См. поле `receipt_positions`.\n\n  Обратите внимание, что оформление возвратов сейчас работает только для платёжного метода «Эквайринг» и только по платежам, прошедшим менее года назад.\n\n  При успешном возврате, покупатель получит средства на карту в течение нескольких дней. Также будет выбит чек возврата прихода."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Создать токен можно в личном кабинете, кликнув по выпадающему меню в левом нижнем углу и перейдя в раздел <b>API токены</b>.'
security:
  -
    default: []
paths:
  '/api/v1/orders/{order_number}':
    get:
      summary: 'Статус заказа'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: 'Объект "Заказ"'
          content:
            application/json:
              schema:
                type: object
                example:
                  order_number: ZP-1-19320990123163648
                  order_id_client: null
                  checkout_url: 'https://zenpayments.ru/orders/ZP-1-19320990123163648/checkout?signature=abcdef123456'
                  created_at: '27.05.2025 10:34'
                  payment_amount: 10000
                  payment_amount_paid: 0
                  payment_amount_refunded: 0
                  currency_code: RUB
                  customer_last_name: Пушкин
                  customer_first_name: Александр
                  customer_middle_name: null
                  customer_email: alex@example.org
                  customer_phone: null
                  return_url: null
                  success_url: null
                  fail_url: null
                  callback_url: null
                  status: 1
                  is_subscription: false
                  is_deletable: false
                  team_requisite_id: 1
                properties:
                  order_number:
                    type: string
                    example: ZP-1-19320990123163648
                    description: 'ID заказа'
                    enum: []
                  order_id_client:
                    type: string
                    example: null
                    description: 'ID заказа в вашей системе, если был указан при создании'
                    enum: []
                  checkout_url:
                    type: string
                    example: 'https://zenpayments.ru/orders/ZP-1-19320990123163648/checkout?signature=abcdef123456'
                    description: 'Ссылка на оплату. Её следует передать покупателю'
                    enum: []
                  created_at:
                    type: string
                    example: '27.05.2025 10:34'
                    description: 'Дата и время создания заказа (часовой пояс МСК)'
                    enum: []
                  payment_amount:
                    type: integer
                    example: 10000
                    description: 'Сумма заказа (всего)'
                    enum: []
                  payment_amount_paid:
                    type: integer
                    example: 0
                    description: 'Сумма заказа (оплачено). Для внутренних рассрочек может быть меньше суммы заказа. Для подписок может быть больше суммы заказа.'
                    enum: []
                  payment_amount_refunded:
                    type: integer
                    example: 0
                    description: 'Сумма возвратов по заказу. Не может превысить сумму оплат.'
                    enum: []
                  currency_code:
                    type: string
                    example: RUB
                    description: 'Валюта заказа. На данный момент, поддерживается только RUB'
                    enum: []
                  customer_last_name:
                    type: string
                    example: Пушкин
                    description: 'Фамилия покупателя'
                    enum: []
                  customer_first_name:
                    type: string
                    example: Александр
                    description: 'Имя покупателя'
                    enum: []
                  customer_middle_name:
                    type: string
                    example: null
                    description: 'Отчество покупателя'
                    enum: []
                  customer_email:
                    type: string
                    example: alex@example.org
                    description: 'Email покупателя. Не обязателен, если указан телефон.'
                    enum: []
                  customer_phone:
                    type: string
                    example: null
                    description: 'Телефон покупателя. Не обязателен, если указан email.'
                    enum: []
                  return_url:
                    type: string
                    example: null
                    description: 'Ссылка для возврата в случае отказа от оплаты'
                    enum: []
                  success_url:
                    type: string
                    example: null
                    description: 'Ссылка для возврата в случае успешной оплаты'
                    enum: []
                  fail_url:
                    type: string
                    example: null
                    description: 'Ссылка для возврата в случае неуспешной оплаты'
                    enum: []
                  callback_url:
                    type: string
                    example: null
                    description: 'Ссылка для отправки вебхуков по данному заказу'
                    enum: []
                  status:
                    type: integer
                    example: 1
                    description: 'Статус заказа. 1 = новый, 2 = ожидает оплаты, 3 = есть оплата, 4 = отменено'
                    enum: []
                  is_subscription:
                    type: boolean
                    example: false
                    description: 'Является ли подпиской'
                    enum: []
                  is_deletable:
                    type: boolean
                    example: false
                    description: 'Можно ли удалить заказ. Заказ можно удалить только до тех пор, пока никто не переходил по ссылке для его оплаты'
                    enum: []
                  team_requisite_id:
                    type: integer
                    example: 1
                    description: 'ID компании, к которой относится заказ'
                    enum: []
                required:
                  - order_number
                  - order_id_client
                  - checkout_url
                  - created_at
                  - payment_amount
                  - payment_amount_paid
                  - payment_amount_refunded
                  - currency_code
                  - customer_last_name
                  - customer_first_name
                  - customer_middle_name
                  - customer_email
                  - customer_phone
                  - return_url
                  - success_url
                  - fail_url
                  - callback_url
                  - status
                  - is_subscription
                  - is_deletable
                  - team_requisite_id
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Заказы
    put:
      summary: 'Редактировать заказ'
      operationId: ''
      description: " Метод позволяет отредактировать все, либо некоторые поля заказа. Если заказ\n находится в статусе \"Новый\", можно редактировать любые поля. Если заказ\n находится в статусе \"Ожидает оплаты\", можно отредактировать только следующие\n поля: return_url, success_url, fail_url, callback_url. Если заказ уже оплачен,\n его редактирование недоступно."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Заказ был успешно отредактирован'
                    type: object
                    example:
                      is_updated: true
                    properties:
                      is_updated:
                        type: boolean
                        example: true
                  -
                    description: 'Заказ не был отредактирован'
                    type: object
                    example:
                      is_updated: false
                    properties:
                      is_updated:
                        type: boolean
                        example: false
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Поле customer last name обязательно. (and 1 more error)'
                  errors:
                    customer_last_name:
                      - 'Поле customer last name обязательно.'
                    customer_first_name:
                      - 'Поле customer first name обязательно.'
                properties:
                  message:
                    type: string
                    example: 'Поле customer last name обязательно. (and 1 more error)'
                  errors:
                    type: object
                    properties:
                      customer_last_name:
                        type: array
                        example:
                          - 'Поле customer last name обязательно.'
                        items:
                          type: string
                      customer_first_name:
                        type: array
                        example:
                          - 'Поле customer first name обязательно.'
                        items:
                          type: string
      tags:
        - Заказы
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                order_id_client:
                  type: string
                  description: 'ID заказа в вашей системе. Если указан, должен быть уникален в рамках аккаунта. От 1 до 64 символов.'
                  example: '123'
                  nullable: true
                customer_last_name:
                  type: string
                  description: 'Фамилия покупателя. От 2 до 255 символов.'
                  example: Пушкин
                customer_first_name:
                  type: string
                  description: 'Имя покупателя. От 2 до 255 символов.'
                  example: Александр
                customer_middle_name:
                  type: string
                  description: 'Отчество покупателя. От 2 до 255 символов.'
                  example: Сергеевич
                customer_email:
                  type: string
                  description: 'Email покупателя. До 128 символов. Не обязательно указывать, если указан телефон.'
                  example: alex@example.org
                customer_phone:
                  type: string
                  description: 'Телефон покупателя. До 32 символов. Не обязательно указывать, если указан email.'
                  example: '+79991111111'
                is_subscription:
                  type: boolean
                  description: 'Является ли подпиской'
                  example: true
                team_requisite_id:
                  type: integer
                  description: 'ID компании, к которой относится заказ'
                  example: 1
                methods:
                  type: array
                  description: 'Список доступных платёжных методов. Если is_subscription = true, максимум 1 метод. Иначе максимум 16 методов.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: 'Название платёжного метода. Видно покупателю на странице оплаты. От 3 до 128 символов.'
                        example: 'Оплата картой'
                      method:
                        type: integer
                        description: 'Код платёжного метода. 1 = эквайринг (карта, СБП, MirPay и т.п.), 2 = банковская рассрочка, 3 = банковский кредит, 4 = BNPL.'
                        example: 1
                      gateway:
                        type: integer
                        description: 'Код платёжного шлюза. Актуально только для банковского кредитования, рассрочек и BNPL. 4 = Т-Банк; 5 = +7Pay; 6 = Сбер; 7 = Plait.'
                        example: null
                        nullable: true
                      terms:
                        type: integer
                        description: 'Код дополнительных условий платёжного шлюза. Актуально только для банковского кредитования и рассрочек. 0 = Кредит, 1 = Рассрочка (3 месяца), 2 = Рассрочка (6 месяцев), 3 = Рассрочка (10 месяцев), 4 = Рассрочка (12 месяцев), 5 = Рассрочка (18 месяцев), 6 = Рассрочка (24 месяца), 7 = Рассрочка (36 месяцев).'
                        example: null
                        nullable: true
                      is_recurring:
                        type: boolean
                        description: 'Является ли рекуррентным (регулярным) платежом. Значение true можно прислать только для метода "Эквайринг"'
                        example: null
                      is_subscription:
                        type: boolean
                        description: 'Является ли подпиской. Значение true можно прислать только для метода "Эквайринг". Если is_recurring = true, а is_subscription = false, будет создан метод "Внутренняя рассрочка". Если оба параметра равны true, то подписка.'
                        example: null
                      custom_first_payment_amount:
                        type: number
                        description: 'Сумма первого платежа. Актуально только когда is_recurring = true. От 10 до 5000000. Можно указать до двух знаков после запятой.'
                        example: null
                        nullable: true
                      period:
                        type: integer
                        description: 'Через сколько дней/недель/месяцев списывать следующий платёж. Актуально только когда is_recurring = true.'
                        example: null
                      interval:
                        type: integer
                        description: 'Интервал работает в связке с period. Актуально только когда is_recurring = true. Указывает, какой промежуток использовать для следующего платежа. 3 = день, 4 = неделя, 5 = месяц, 6 = год.'
                        example: null
                      max_payments:
                        type: integer
                        description: 'Максимальное количество платежей по внутренней рассрочке. Актуально только когда is_recurring = true и is_subscription = false. От 2 до 12.'
                        example: null
                    required:
                      - name
                      - method
                return_url:
                  type: string
                  description: 'Ссылка для возврата в случае отказа от оплаты'
                  example: 'https://example.org/return'
                  nullable: true
                success_url:
                  type: string
                  description: 'Ссылка для возврата в случае успешной оплаты'
                  example: 'https://example.org/success'
                  nullable: true
                fail_url:
                  type: string
                  description: 'Ссылка для возврата в случае неуспешной оплаты'
                  example: 'https://example.org/fail'
                  nullable: true
                callback_url:
                  type: string
                  description: 'Ссылка для отправки вебхуков по данному заказу.'
                  example: 'https://example.org/callback'
                  nullable: true
                positions:
                  type: array
                  description: 'Список позиций заказа. От 1 до 200 элементов.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: 'Содержимое позиции. От 3 до 128 символов.'
                        example: 'Оплата доступа к курсу'
                      price:
                        type: number
                        description: 'Стоимость позиции (в рублях). От 10 до 5000000. Можно указать до двух знаков после запятой.'
                        example: 1999.99
                      quantity:
                        type: integer
                        description: 'Количество позиций. От 1 до 100. Итоговая стоимость заказа будет содержать стоимость позиции, помноженную на количество.'
                        example: 1
                      vat_code_id:
                        type: integer
                        description: 'Код ставки НДС. 1 = Без НДС, 2 = НДС по ставке 0%, 3 = НДС по ставке 10%, 4 = НДС по ставке 20% (с 2026 года 22%), 5 = НДС по расчётной ставке 10/110, 6 = НДС по расчётной ставке 20/120 (с 2026 года 22/122), 7 = НДС по ставке 5%, 8 = НДС по ставке 7%, 9 = НДС по расчётной ставке 5/105, 10 = НДС по расчётной ставке 7/107.'
                        example: 1
                    required:
                      - content
                      - price
                      - quantity
                      - vat_code_id
              required:
                - customer_last_name
                - customer_first_name
                - customer_email
                - customer_phone
                - is_subscription
                - team_requisite_id
                - methods
                - positions
    delete:
      summary: 'Удалить заказ'
      operationId: ''
      description: ' Удаление доступно только для заказов в статусе "Новый".'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Заказ был успешно удалён'
                    type: object
                    example:
                      is_deleted: true
                    properties:
                      is_deleted:
                        type: boolean
                        example: true
                  -
                    description: 'Заказ не был удалён'
                    type: object
                    example:
                      is_deleted: false
                    properties:
                      is_deleted:
                        type: boolean
                        example: false
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Заказы
    parameters:
      -
        in: path
        name: order_number
        description: 'ID заказа'
        example: ZP-1-17875508976943104
        required: true
        schema:
          type: string
  /api/v1/orders/store:
    post:
      summary: 'Создать заказ'
      operationId: ''
      description: 'В случае успеха, в ответе вы получите такой же объект, как при просмотре статуса заказа.'
      parameters: []
      responses:
        201:
          description: 'Объект "Заказ"'
          content:
            application/json:
              schema:
                type: object
                example:
                  order_number: ZP-1-19320990123163648
                  order_id_client: null
                  checkout_url: 'https://zenpayments.ru/orders/ZP-1-19320990123163648/checkout?signature=abcdef123456'
                  created_at: '27.05.2025 10:34'
                  payment_amount: 10000
                  payment_amount_paid: 0
                  payment_amount_refunded: 0
                  currency_code: RUB
                  customer_last_name: Пушкин
                  customer_first_name: Александр
                  customer_middle_name: null
                  customer_email: alex@example.org
                  customer_phone: null
                  return_url: null
                  success_url: null
                  fail_url: null
                  callback_url: null
                  status: 1
                  is_subscription: false
                  is_deletable: false
                  team_requisite_id: 1
                properties:
                  order_number:
                    type: string
                    example: ZP-1-19320990123163648
                  order_id_client:
                    type: string
                    example: null
                  checkout_url:
                    type: string
                    example: 'https://zenpayments.ru/orders/ZP-1-19320990123163648/checkout?signature=abcdef123456'
                  created_at:
                    type: string
                    example: '27.05.2025 10:34'
                  payment_amount:
                    type: integer
                    example: 10000
                  payment_amount_paid:
                    type: integer
                    example: 0
                  payment_amount_refunded:
                    type: integer
                    example: 0
                  currency_code:
                    type: string
                    example: RUB
                  customer_last_name:
                    type: string
                    example: Пушкин
                  customer_first_name:
                    type: string
                    example: Александр
                  customer_middle_name:
                    type: string
                    example: null
                  customer_email:
                    type: string
                    example: alex@example.org
                  customer_phone:
                    type: string
                    example: null
                  return_url:
                    type: string
                    example: null
                  success_url:
                    type: string
                    example: null
                  fail_url:
                    type: string
                    example: null
                  callback_url:
                    type: string
                    example: null
                  status:
                    type: integer
                    example: 1
                  is_subscription:
                    type: boolean
                    example: false
                  is_deletable:
                    type: boolean
                    example: false
                  team_requisite_id:
                    type: integer
                    example: 1
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Поле customer last name обязательно. (and 1 more error)'
                  errors:
                    customer_last_name:
                      - 'Поле customer last name обязательно.'
                    customer_first_name:
                      - 'Поле customer first name обязательно.'
                properties:
                  message:
                    type: string
                    example: 'Поле customer last name обязательно. (and 1 more error)'
                  errors:
                    type: object
                    properties:
                      customer_last_name:
                        type: array
                        example:
                          - 'Поле customer last name обязательно.'
                        items:
                          type: string
                      customer_first_name:
                        type: array
                        example:
                          - 'Поле customer first name обязательно.'
                        items:
                          type: string
      tags:
        - Заказы
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                order_id_client:
                  type: string
                  description: 'ID заказа в вашей системе. Если указан, должен быть уникален в рамках аккаунта. От 1 до 64 символов.'
                  example: '123'
                  nullable: true
                customer_last_name:
                  type: string
                  description: 'Фамилия покупателя. От 2 до 255 символов.'
                  example: Пушкин
                customer_first_name:
                  type: string
                  description: 'Имя покупателя. От 2 до 255 символов.'
                  example: Александр
                customer_middle_name:
                  type: string
                  description: 'Отчество покупателя. От 2 до 255 символов.'
                  example: Сергеевич
                customer_email:
                  type: string
                  description: 'Email покупателя. До 128 символов. Не обязательно указывать, если указан телефон.'
                  example: alex@example.org
                customer_phone:
                  type: string
                  description: 'Телефон покупателя. До 32 символов. Не обязательно указывать, если указан email.'
                  example: '+79991111111'
                is_subscription:
                  type: boolean
                  description: 'Является ли подпиской'
                  example: true
                team_requisite_id:
                  type: integer
                  description: 'ID компании, к которой относится заказ'
                  example: 1
                methods:
                  type: array
                  description: 'Список доступных платёжных методов. Если is_subscription = true, максимум 1 метод. Иначе максимум 32 метода.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: 'Название платёжного метода. Видно покупателю на странице оплаты. От 3 до 128 символов.'
                        example: 'Оплата картой'
                      method:
                        type: integer
                        description: 'Код платёжного метода. 1 = эквайринг (карта, СБП, MirPay и т.п.), 2 = банковская рассрочка, 3 = банковский кредит, 4 = BNPL.'
                        example: 1
                      gateway:
                        type: integer
                        description: 'Код платёжного шлюза. Актуально только для банковского кредитования, рассрочек и BNPL. 4 = Т-Банк; 5 = +7Pay; 6 = Сбер; 7 = Plait.'
                        example: null
                        nullable: true
                      terms:
                        type: integer
                        description: 'Код дополнительных условий платёжного шлюза. Актуально только для банковского кредитования и рассрочек. 0 = Кредит, 1 = Рассрочка (3 месяца), 2 = Рассрочка (6 месяцев), 3 = Рассрочка (10 месяцев), 4 = Рассрочка (12 месяцев), 5 = Рассрочка (18 месяцев), 6 = Рассрочка (24 месяца), 7 = Рассрочка (36 месяцев).'
                        example: null
                        nullable: true
                      is_recurring:
                        type: boolean
                        description: 'Является ли рекуррентным (регулярным) платежом. Значение true можно прислать только для метода "Эквайринг"'
                        example: null
                      is_subscription:
                        type: boolean
                        description: 'Является ли подпиской. Значение true можно прислать только для метода "Эквайринг". Если is_recurring = true, а is_subscription = false, будет создан метод "Внутренняя рассрочка". Если оба параметра равны true, то подписка.'
                        example: null
                      custom_first_payment_amount:
                        type: number
                        description: 'Сумма первого платежа. Актуально только когда is_recurring = true. От 10 до 5000000. Можно указать до двух знаков после запятой.'
                        example: null
                        nullable: true
                      period:
                        type: integer
                        description: 'Через сколько дней/недель/месяцев списывать следующий платёж. Актуально только когда is_recurring = true.'
                        example: null
                      interval:
                        type: integer
                        description: 'Интервал работает в связке с period. Актуально только когда is_recurring = true. Указывает, какой промежуток использовать для следующего платежа. 3 = день, 4 = неделя, 5 = месяц, 6 = год.'
                        example: null
                      max_payments:
                        type: integer
                        description: 'Максимальное количество платежей по внутренней рассрочке. Актуально только когда is_recurring = true и is_subscription = false. От 2 до 12.'
                        example: null
                    required:
                      - name
                      - method
                return_url:
                  type: string
                  description: 'Ссылка для возврата в случае отказа от оплаты'
                  example: 'https://example.org/return'
                  nullable: true
                success_url:
                  type: string
                  description: 'Ссылка для возврата в случае успешной оплаты'
                  example: 'https://example.org/success'
                  nullable: true
                fail_url:
                  type: string
                  description: 'Ссылка для возврата в случае неуспешной оплаты'
                  example: 'https://example.org/fail'
                  nullable: true
                callback_url:
                  type: string
                  description: 'Ссылка для отправки вебхуков по данному заказу.'
                  example: 'https://example.org/callback'
                  nullable: true
                positions:
                  type: array
                  description: 'Список позиций заказа. От 1 до 200 элементов.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: 'Содержимое позиции. От 3 до 128 символов.'
                        example: 'Оплата доступа к курсу'
                      price:
                        type: number
                        description: 'Стоимость позиции (в рублях). От 10 до 5000000. Можно указать до двух знаков после запятой.'
                        example: 1999.99
                      quantity:
                        type: integer
                        description: 'Количество позиций. От 1 до 100. Итоговая стоимость заказа будет содержать стоимость позиции, помноженную на количество.'
                        example: 1
                      vat_code_id:
                        type: integer
                        description: 'Код ставки НДС. 1 = Без НДС, 2 = НДС по ставке 0%, 3 = НДС по ставке 10%, 4 = НДС по ставке 20% (с 2026 года 22%), 5 = НДС по расчётной ставке 10/110, 6 = НДС по расчётной ставке 20/120 (с 2026 года 22/122), 7 = НДС по ставке 5%, 8 = НДС по ставке 7%, 9 = НДС по расчётной ставке 5/105, 10 = НДС по расчётной ставке 7/107.'
                        example: 1
                    required:
                      - content
                      - price
                      - quantity
                      - vat_code_id
              required:
                - customer_email
                - customer_phone
                - is_subscription
                - team_requisite_id
                - methods
                - positions
  '/api/v1/orders/{order_number}/invoices':
    get:
      summary: 'Список инвойсов'
      operationId: ''
      description: 'В случае успеха, в ответе вы получите список (массив) объектов, по структуре полностью совпадающих с объектом "Инвойс"'
      parameters: []
      responses:
        200:
          description: 'Список объектов "Инвойс"'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    invoice_number:
                      type: string
                      example: INV-1-64641117273980928
                    created_at:
                      type: string
                      example: '26.05.2025 11:17'
                    has_recurring_cancelled:
                      type: boolean
                      example: false
                    has_recurring_failed:
                      type: boolean
                      example: false
                    amount:
                      type: integer
                      example: 10000
                    amount_paid:
                      type: integer
                      example: 0
                    currency_code:
                      type: string
                      example: RUB
                    payments_count:
                      type: integer
                      example: 0
                example:
                  -
                    invoice_number: INV-1-64641117273980928
                    created_at: '26.05.2025 11:17'
                    has_recurring_cancelled: false
                    has_recurring_failed: false
                    amount: 10000
                    amount_paid: 0
                    currency_code: RUB
                    payments_count: 0
                  -
                    invoice_number: INV-1-17558155068178432
                    created_at: '27.05.2025 10:34'
                    has_recurring_cancelled: false
                    has_recurring_failed: false
                    amount: 10000
                    amount_paid: 10000
                    currency_code: RUB
                    payments_count: 1
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Заказы
    parameters:
      -
        in: path
        name: order_number
        description: 'ID заказа'
        example: ZP-1-17875508976943104
        required: true
        schema:
          type: string
  '/api/v1/invoices/{invoice_number}':
    get:
      summary: 'Статус инвойса'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: 'Объект "Инвойс"'
          content:
            application/json:
              schema:
                type: object
                example:
                  invoice_number: INV-1-17558155068178432
                  created_at: '27.05.2025 10:34'
                  has_recurring_cancelled: false
                  has_recurring_failed: false
                  amount: 10000
                  amount_paid: 10000
                  amount_refunded: 0
                  currency_code: RUB
                  payments_count: 1
                properties:
                  invoice_number:
                    type: string
                    example: INV-1-17558155068178432
                    description: 'ID инвойса'
                    enum: []
                  created_at:
                    type: string
                    example: '27.05.2025 10:34'
                    description: 'Дата и время создания инвойса (часовой пояс МСК)'
                    enum: []
                  has_recurring_cancelled:
                    type: boolean
                    example: false
                    description: 'Был ли автоплатёж отменён'
                    enum: []
                  has_recurring_failed:
                    type: boolean
                    example: false
                    description: 'Была ли попытка автоплатежа завершена неудачей'
                    enum: []
                  amount:
                    type: integer
                    example: 10000
                    description: Сумма
                    enum: []
                  amount_paid:
                    type: integer
                    example: 10000
                    description: Оплачено
                    enum: []
                  amount_refunded:
                    type: integer
                    example: 0
                    description: Возвращено
                    enum: []
                  currency_code:
                    type: string
                    example: RUB
                    description: Валюта
                    enum: []
                  payments_count:
                    type: integer
                    example: 1
                    description: 'Кол-во платежей'
                    enum: []
                required:
                  - invoice_number
                  - created_at
                  - has_recurring_cancelled
                  - has_recurring_failed
                  - amount
                  - amount_paid
                  - amount_refunded
                  - currency_code
                  - payments_count
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Инвойсы
    parameters:
      -
        in: path
        name: invoice_number
        description: 'ID инвойса'
        example: INV-1-17558155068178432
        required: true
        schema:
          type: string
  '/api/v1/invoices/{invoice_number}/autopayment-disable':
    post:
      summary: 'Отключить автоплатёж'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  message: OK
                properties:
                  message:
                    type: string
                    example: OK
                    description: Результат
                    enum: []
                required:
                  - message
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
                    description: Результат
                    enum: []
                required:
                  - message
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
                    description: Результат
                    enum: []
                required:
                  - message
      tags:
        - Инвойсы
    parameters:
      -
        in: path
        name: invoice_number
        description: 'ID инвойса'
        example: INV-1-17558155068178432
        required: true
        schema:
          type: string
  '/api/v1/invoices/{invoice_number}/autopayment-enable':
    post:
      summary: 'Включить автоплатёж'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  message: OK
                properties:
                  message:
                    type: string
                    example: OK
                    description: Результат
                    enum: []
                required:
                  - message
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
                    description: Результат
                    enum: []
                required:
                  - message
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
                    description: Результат
                    enum: []
                required:
                  - message
      tags:
        - Инвойсы
    parameters:
      -
        in: path
        name: invoice_number
        description: 'ID инвойса'
        example: INV-1-17558155068178432
        required: true
        schema:
          type: string
  '/api/v1/payments/{payment_number}/refunds':
    get:
      summary: 'Список возвратов по платежу'
      operationId: ''
      description: 'Используйте метод, чтобы убедиться, что возврат был зарегистрирован, либо что возвратов вы ещё не делали. Также для того, чтобы получить список позиций чека: их id нужны будут при создании возврата.'
      parameters: []
      responses:
        200:
          description: 'Список объектов "Возврат" и "Позиция чека"'
          content:
            application/json:
              schema:
                type: object
                example:
                  refunds:
                    -
                      refund_number: RF-1-103019033699287040
                      created_at: '27.05.2025 10:34'
                      amount: 5000
                      currency_code: RUB
                    -
                      refund_number: RF-1-103019033703481346
                      created_at: '28.05.2025 21:01'
                      amount: 3000
                      currency_code: RUB
                  receipt_positions:
                    -
                      id: 2345
                      content: 'Доступ к онлайн-курсу'
                      amount_paid: 8000
                      amount_refunded: 8000
                      quantity: 1
                properties:
                  refunds:
                    type: array
                    example:
                      -
                        refund_number: RF-1-103019033699287040
                        created_at: '27.05.2025 10:34'
                        amount: 5000
                        currency_code: RUB
                      -
                        refund_number: RF-1-103019033703481346
                        created_at: '28.05.2025 21:01'
                        amount: 3000
                        currency_code: RUB
                    description: 'Список возвратов (смотри метод "Статус возврата")'
                    enum: []
                    items:
                      type: object
                      properties:
                        refund_number:
                          type: string
                          example: RF-1-103019033699287040
                        created_at:
                          type: string
                          example: '27.05.2025 10:34'
                        amount:
                          type: integer
                          example: 5000
                        currency_code:
                          type: string
                          example: RUB
                  receipt_positions:
                    type: array
                    example:
                      -
                        id: 2345
                        content: 'Доступ к онлайн-курсу'
                        amount_paid: 8000
                        amount_refunded: 8000
                        quantity: 1
                    description: 'Список позиций'
                    enum: []
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 2345
                        content:
                          type: string
                          example: 'Доступ к онлайн-курсу'
                        amount_paid:
                          type: integer
                          example: 8000
                        amount_refunded:
                          type: integer
                          example: 8000
                        quantity:
                          type: integer
                          example: 1
                required:
                  - refunds
                  - receipt_positions
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Возвраты
    parameters:
      -
        in: path
        name: payment_number
        description: 'ID платежа'
        example: P-1-17875508976943104
        required: true
        schema:
          type: string
  '/api/v1/refunds/{refund_number}':
    get:
      summary: 'Статус возврата'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: 'Объект "Возврат"'
          content:
            application/json:
              schema:
                type: object
                example:
                  refund_number: RF-1-19320990123163648
                  created_at: '27.05.2025 10:34'
                  amount: 10000
                  currency_code: RUB
                properties:
                  refund_number:
                    type: string
                    example: RF-1-19320990123163648
                    description: 'ID возврата'
                    enum: []
                  created_at:
                    type: string
                    example: '27.05.2025 10:34'
                    description: 'Дата и время создания возврата (часовой пояс МСК)'
                    enum: []
                  amount:
                    type: integer
                    example: 10000
                    description: 'Сумма возврата'
                    enum: []
                  currency_code:
                    type: string
                    example: RUB
                    description: 'Валюта возврата. На данный момент, поддерживается только RUB'
                    enum: []
                required:
                  - refund_number
                  - created_at
                  - amount
                  - currency_code
        403:
          description: 'Нет прав на данное действие'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden
                properties:
                  message:
                    type: string
                    example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
      tags:
        - Возвраты
    parameters:
      -
        in: path
        name: refund_number
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  '/api/v1/payments/{payment_number}/refund':
    post:
      summary: 'Провести возврат'
      operationId: ''
      description: 'В случае успеха, в ответе вы получите такой же объект, как при просмотре статуса возврата.'
      parameters: []
      responses:
        201:
          description: 'Объект "Возврат"'
          content:
            application/json:
              schema:
                type: object
                example:
                  refund_number: RF-1-19320990123163648
                  created_at: '27.05.2025 10:34'
                  amount: 10000
                  currency_code: RUB
                properties:
                  refund_number:
                    type: string
                    example: RF-1-19320990123163648
                  created_at:
                    type: string
                    example: '27.05.2025 10:34'
                  amount:
                    type: integer
                    example: 10000
                  currency_code:
                    type: string
                    example: RUB
        403:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Недостаточно средств на балансе'
                    type: object
                    example:
                      message: Forbidden
                      explanation: 'На балансе недостаточно средств'
                    properties:
                      message:
                        type: string
                        example: Forbidden
                      explanation:
                        type: string
                        example: 'На балансе недостаточно средств'
                  -
                    description: 'Шлюз не поддерживается'
                    type: object
                    example:
                      message: Forbidden
                      explanation: 'Функция возврата недоступна для данного платёжного шлюза.'
                    properties:
                      message:
                        type: string
                        example: Forbidden
                      explanation:
                        type: string
                        example: 'Функция возврата недоступна для данного платёжного шлюза.'
                  -
                    description: 'Платёж слишком старый'
                    type: object
                    example:
                      message: Forbidden
                      explanation: 'Функция возврата недоступна для платежей, совершённых более года назад'
                    properties:
                      message:
                        type: string
                        example: Forbidden
                      explanation:
                        type: string
                        example: 'Функция возврата недоступна для платежей, совершённых более года назад'
                  -
                    description: 'Нет прав на данное действие'
                    type: object
                    example:
                      message: Forbidden
                    properties:
                      message:
                        type: string
                        example: Forbidden
        404:
          description: 'Не найдено'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not found'
                properties:
                  message:
                    type: string
                    example: 'Not found'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Поле receipt positions обязательно.'
                  errors:
                    receipt_positions:
                      - 'Поле receipt positions обязательно.'
                properties:
                  message:
                    type: string
                    example: 'Поле receipt positions обязательно.'
                  errors:
                    type: object
                    properties:
                      receipt_positions:
                        type: array
                        example:
                          - 'Поле receipt positions обязательно.'
                        items:
                          type: string
      tags:
        - Возвраты
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                receipt_positions:
                  type: array
                  description: 'Список позиций чека, по которым будет оформлен возврат'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: 'id позиции. Его можно узнать, сделав запрос на получение позиций чека по платежу.'
                        example: 1
                      amount:
                        type: number
                        description: 'Сумма возврата по данной позиции (в рублях). От 10 до 5000000. Можно указать до двух знаков после запятой. Не может превышать общую стоимость данной позиции.'
                        example: 1999.99
                    required:
                      - id
                      - amount
              required:
                - receipt_positions
    parameters:
      -
        in: path
        name: payment_number
        description: 'ID платежа'
        example: P-1-17875508976943104
        required: true
        schema:
          type: string
