post/v3/billing/api/order/refund-order

Оформление возврата

Оформить возврат средств возможно только по оплаченному заказу. Перед оплатой, пожалуйста, воспользуйтесь методом удаления заказа. Схема оформления возврата по оплаченному заказу следующая:

Получить список доступных для возврата позиций
Создание возвратного заказа

Пример запроса и ответа

GET /v3/billing/api/order/refund-order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json

Ответ:

[
  {
    "id": "01859552-5136-da7a-62c0-c0ee2dfe1485",
    "description": "Возврат средств заказа",
    "currencyId": "RUB",
    "amount": 1476.2,
    "vatAmount": 0,
    "basketItems": [
      {
        "sku": "70633118938830",
        "name": "ТАРИФ ПЛАЦКАРТЫ 70633118938830",
        "measure": "шт",
        "measureCode": "796",
        "grossWeight": 0,
        "netWeight": 0,
        "quantity": 1,
        "amount": 518.5,
        "amountWoVat": 518.5,
        "totalAmount": 518.5,
        "totalVatAmount": 0,
        "vatCode": "RUS_VAT0",
        "type": "service",
        "paymentType": "full_prepayment",
        "metaData": {
          "@type": "TrainReservation",
          "provider": {
            "name": "Grand Service Express",
            "@type": "Organization",
            "taxID": "5544332219"
          },
          "underName": {
            "name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
            "@type": "Person"
          },
          "bookingTime": "2026-08-12T09:46:00+03:00",
          "reservationId": "70633118938830",
          "reservationFor": {
            "@type": "TrainTrip",
            "arrivalTime": "2026-08-12T09:20:00+03:00",
            "trainNumber": "092МА",
            "departureTime": "2026-08-12T23:52:00+03:00",
            "arrivalStation": {
              "name": "Симферополь",
              "@type": "TrainStation"
            },
            "departureStation": {
              "name": "Москва Казанская (Казанский вокзал)",
              "@type": "TrainStation"
            }
          },
          "reservedTicket": {
            "fare": 518.5,
            "@type": "trainTicket",
            "gender": "male",
            "vatValue": {
              "vatCode": "RUS_VAT0",
              "totalVatAmount": 0
            },
            "coachType": "Плацкартный",
            "underName": {
              "name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
              "@type": "Person"
            },
            "coachNumber": "04",
            "nationality": "RUS",
            "paymentType": "Безналичный расчёт",
            "serviceClass": "3Э",
            "ticketNumber": "70633118938830",
            "ticketedSeat": {
              "@type": "Seat",
              "seatNumber": "038"
            },
            "ticketIssueTime": "2026-08-12T09:20:00+03:00",
            "idDocumentNumber": "********8015"
          },
          "reservationStatus": "https://schema.org/ReservationConfirmed"
        }
      },
      {
        "sku": "70633118938830/1",
        "name": "ТАРИФ БИЛЕТА 70633118938830",
        "measure": "шт",
        "measureCode": "796",
        "grossWeight": 0,
        "netWeight": 0,
        "quantity": 1,
        "amount": 957.7,
        "amountWoVat": 957.7,
        "totalAmount": 957.7,
        "totalVatAmount": 0,
        "vatCode": "RUS_VAT0",
        "type": "service",
        "paymentType": "full_prepayment",
        "metaData": {
          "@type": "TrainReservation",
          "provider": {
            "name": "Grand Service Express",
            "@type": "Organization",
            "taxID": "5544332219"
          },
          "underName": {
            "name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
            "@type": "Person"
          },
          "bookingTime": "2026-08-12T09:46:00+03:00",
          "reservationId": "70633118938830",
          "reservationFor": {
            "@type": "TrainTrip",
            "arrivalTime": "2026-08-12T09:20:00+03:00",
            "trainNumber": "092МА",
            "departureTime": "2026-08-12T23:52:00+03:00",
            "arrivalStation": {
              "name": "Симферополь",
              "@type": "TrainStation"
            },
            "departureStation": {
              "name": "Москва Казанская (Казанский вокзал)",
              "@type": "TrainStation"
            }
          },
          "reservedTicket": {
            "fare": 957.7,
            "@type": "trainTicket",
            "gender": "male",
            "vatValue": {
              "vatCode": "RUS_VAT0",
              "totalVatAmount": 0
            },
            "coachType": "Плацкартный",
            "underName": {
              "name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
              "@type": "Person"
            },
            "coachNumber": "04",
            "nationality": "RUS",
            "paymentType": "Безналичный расчёт",
            "serviceClass": "3Э",
            "ticketNumber": "70633118938830",
            "ticketedSeat": {
              "@type": "Seat",
              "seatNumber": "038"
            },
            "ticketIssueTime": "2026-08-12T09:20:00+03:00",
            "idDocumentNumber": "********8015"
          },
          "reservationStatus": "https://schema.org/ReservationConfirmed"
        }
      }
    ],
    "merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "status": "created",
    "shipmentStatus": "unshipped",
    "subtype": "refund",
    "createdAt": "2026-08-12T06:57:58+00:00",
    "merchantOrderId": "/10004-00000-00003-50371",
    "orderContainerId": "01859547-cacb-80bd-25fd-31c8cee2f841",
    "parentId": "01859547-cad6-4652-18ab-5534cfa6ed0e",
    "processable": true
  }
]

Получается список доступных для возврата позиций:

метод: GET
ресурс: /v3/billing/api/order/order/:uuid/refund-basket-item - где :uuid это идентификатор заказа
тело ответа - array of BasketItem

Частичный возврат

Возвращать всю сумму заказа не обязательно. Возврат — это отдельный заказ со своей корзиной: в basketItems перечисляются только те позиции и количества, которые возвращаются, а amount и vatAmount считаются по ним. Из заказа на 10 000 ₽ можно вернуть 3 000 ₽, оформив возврат на одну позицию.

Возвратов по одному заказу может быть несколько. Каждому нужен свой merchantOrderId: по нему Инвойсбокс отличает новый возврат от повторно отправленного и не проводит один и тот же дважды.

Какие позиции ещё доступны к возврату, показывает метод из раздела ниже.

Создание возвратного заказа

метод: POST
ресурс: /v3/billing/api/order/refund-order
тело запроса - объект CreateRefundOrderRequest
тело ответа - объект RefundOrderResponse

CreateRefundOrderRequest

Свойство	Тип	Описание	Пример значения
parentId *	string(36)	Идентификатор базового заказа	`01771534-196a-1105-839a-82422289d6d9`
merchantOrderId *	string(100)	Идентификатор возвратного заказа в учётной системе магазина, для каждого отдельного возврата значение должно быть уникальным	`O-12345`
amount *	float	Сумма заказа	`19658.45`
vatAmount *	float	Сумма НДС	`156.56`
basketItems *	array of BasketItem	Корзина заказа
description *	string(1000)	Описание заказа	`Оплата номера в отеле`
status	string(50) enum	Статус заказа, по умолчанию `created`, так же возможен статус `draft` для создания корректирующих заказов	`created`
subtype	string(20) enum	Вид возврата: `refund` — обычный (по умолчанию), `secured` — с обеспечением	`secured`

Важно

При формировании нескольких возвратов в рамках одного заказа передавайте уникальный идентификатор возвратного заказа (возврата) merchantOrderId для каждого отдельного возврата. В случае, если будет передан уже существующий идентификатор, будет возвращена ошибка. Подобный механизм предупреждает инциденты случайных двойных возвратов.

Возврат с обеспечением

Обычный возврат уходит в выплату сразу после создания: покупатель получает деньги, а магазин рассчитывается с Инвойсбокс потом. Возврат с обеспечением меняет порядок на обратный — сначала деньги вносит магазин, и только потом стартует выплата покупателю. Такой возврат создаётся тем же методом с полем subtype:

{
  "parentId": "01771534-196a-1105-839a-82422289d6d9",
  "merchantOrderId": "R-4412-1",
  "subtype": "secured",
  "amount": 12000,
  "vatAmount": 0,
  "description": "Возврат за отменённое бронирование № 4412",
  "basketItems": []
}

Как это работает

Возврат создаётся в статусе created, как обычный, но в выплату не уходит.
Инвойсбокс выставляет магазину обеспечительный заказ на сумму возврата. В ответе на создание возврата приходит его идентификатор — securityOrderId.
Магазин оплачивает обеспечительный заказ. Счёт под него не выставляется: способ оплаты магазин выбирает на платёжной странице сам, как покупатель в обычном заказе.
После оплаты обеспечения возврат идёт штатным путём — processing, затем completed.

Статусы возврата при этом обычные: вид возврата виден только в subtype. Отдельных уведомлений у обеспечения нет — приходят те же события, что и всегда: о создании возврата, об оплате обеспечительного заказа и о завершении возврата.

Что нужно знать заранее

Обеспечительный заказ оформлен на организацию магазина. Плательщиком подставляются название, ИНН и КПП вашей организации; телефон и почту вы указываете на платёжной странице — что подтвердите там, то и попадёт в счёт. Позиция в корзине называется «Обеспечительный платёж», НДС не облагается.
Найти заказ по возврату и обратно можно тремя путями: по securityOrderId возврата, по номеру заказа в учётной системе (там лежит идентификатор возврата) и по артикулу позиции — он тоже равен идентификатору возврата.
Пока обеспечение не оплачено, возврат можно отменить — вместе с ним отменится и обеспечительный заказ. После оплаты отмена запрещена: деньги уже получены, и возврат обязан доехать до выплаты.
Изменить сумму нельзя. Обеспечительный заказ выставлен на исходную сумму, и правка развела бы её с суммой возврата. По той же причине с обеспечением не сочетается статус draft, то есть корректирующие возвраты.
Остаток по корзине резервируется так же, как у обычного возврата.

Важно

Возврат с обеспечением требует настройки на стороне Инвойсбокс. Если она не сделана, запрос создания возврата вернёт ошибку — обеспечительный заказ выставить не из чего, а возврат без него завис бы навсегда. Сам возврат к этому моменту уже создан: отмените его и повторите после настройки. Если планируете такие возвраты, договоритесь о настройке заранее.

RefundOrderResponse

Свойство	Тип	Описание	Пример значения
id *	string(36)	Идентификатор заказа в системе Инвойсбокс	`01771534-1a57-f184-dee3-ebeb91dded75`
parentId *	string(36)	Идентификатор базового заказа	`01771534-196a-1105-839a-82422289d6d9`
description *	string(1000)	Описание заказа	`Оплата номера в отеле`
merchantOrderId *	string(100)	Идентификатор возврата в учётной системе магазина, свой у каждого возврата	`R-12345`
merchantId *	string(36)	Идентификатор магазина	`01771534-1a57-f184-dee3-ebeb91dded76`
amount *	float	Сумма заказа	`19658.45`
vatAmount *	float	Сумма НДС	`156.56`
currencyId *	string(3) enum	Валюта заказа	`RUB`
basketItems *	array of BasketItem	Корзина заказа
createdAt *	datetime	Дата создания заказа	`2026-12-22T00:00:00+00:00`
status *	string(50) enum	Статус заказа	`completed`
paidAt	datetime	Дата осуществления возврата (если возвращен)	`2026-12-22T00:00:00+00:00`
subtype	string(20) enum	Вид возврата: `refund` или `secured`	`secured`
securityOrderId	string(36)	Идентификатор обеспечительного заказа, только у возврата с обеспечением	`019e51e2-3970-9852-e8c8-803c16ac9c74`

Параметры запроса — POST

Только обязательные15 обязательных из 36

ПолеТипОписание

amount *#numberот 0Сумма возврата. Денежное значение: ровно два знака после точки. В коде считайте Decimal/BigDecimal, не двоичным float

vatAmount *#numberот 0Сумма НДС возврата. Денежное значение: ровно два знака после точки. В коде считайте Decimal/BigDecimal, не двоичным float

basketItems *#BillingProviderDomainOrderEntityBasketItemApiCreateCollectionСостав возврата; форма позиций — та же BasketItem, что у создания заказа

parentId *#stringИдентификатор базового (оплаченного) заказа, по которому оформляется возврат

description *#stringОписание возврата

status#stringпо умолчанию "created"По умолчанию created; draft — для корректирующих заказов: https://docs.invoicebox.ru/docs/merchant/refund/correction/createddraft

subtype#BillingProviderDomainOrderEnumRefundOrderTypeApiCreateпо умолчанию "refund"Вид возврата: refund — обычный (по умолчанию), secured — возврат с обеспечениемrefundsecured

merchantOrderId *#stringИдентификатор возвратного заказа в учётной системе магазина — свой у каждого возврата. При повторе после сбоя не меняйте номер: сначала проверьте выборкой по /v3/filter/api/order/refund-order, создался ли возврат

orderSetting#BillingProviderDomainOrderEntityOrderSettingApiCreate | null

Страница помогла?

Нужна помощь?Написать в поддержку Телеграм-канал

← НазадРабота с возвратомДальше →Получение возвратов

postСоздание возвратного заказаДемо

curl -X POST 'https://api.invoicebox.ru/v3/billing/api/order/refund-order' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0' \
  -d '{
  "parentId": "00000000-0000-0000-0000-000000000000",
  "merchantOrderId": "demo-refund-1786618834039",
  "amount": 12000,
  "vatAmount": 0,
  "description": "Возврат по бронированию № 4412",
  "basketItems": [
    {
      "sku": "room-deluxe",
      "name": "Проживание в номере «Делюкс», 2 ночи",
      "measure": "шт",
      "measureCode": "796",
      "quantity": 1,
      "amount": 12000,
      "amountWoVat": 12000,
      "totalAmount": 12000,
      "totalVatAmount": 0,
      "vatCode": "RUS_VAT0",
      "type": "service",
      "paymentType": "full_prepayment"
    }
  ]
}'

getПолучение списка возвратовДемо

curl -X GET 'https://api.invoicebox.ru/v3/billing/api/order/refund-order' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'

getПолучение списка позиций заказа, доступных для возвратаДемо

id *

curl -X GET 'https://api.invoicebox.ru/v3/billing/api/order/order/<id>/refund-basket-item' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'

В демо-режиме операция недоступна — выполните запрос своим токеном по примеру рядом