[Честный знак](https://xn--80ajghhoc2aj1c8b.xn--p1ai/) — это национальная система маркировки и прослеживания продукции.
Специальный цифровой код гарантирует подлинность и качество товара. Основная задача системы — повышение уровня безопасности
россиян, борьба с контрафактом и некачественными аналогами.
Система Инвойсбокс может получать, обрабатывать и передавать необходимую информацию о маркировке товара в системах Честный знак и ЭДО
в соответствии с бизнес-требованиями поставщика товаров (магазина).
## Справочник "Список поддерживаемых товарных групп"
| Код | Наименование | Описание | Сочетание |
|-----|--------------|--------------------------------------------------------------------------|-----------|
| 1 | lp | Предметы одежды, бельё постельное, столовое, туалетное и кухонное | 2 |
| 2 | shoes | Обувные товары | 2 |
| 3 | tobacco | Табачная продукция | 1 |
| 4 | perfumery | Духи и туалетная вода | 2 |
| 5 | tires | Шины и покрышки пневматические резиновые новые | 2 |
| 6 | electronics | Фотокамеры (кроме кинокамер), фотовспышки и лампывспышки | 2 |
| 8 | milk | Молочная продукция | 3 |
| 9 | bicycle | Велосипеды и велосипедные рамы | 2 |
| 10 | wheelchairs | Медицинские изделия | 2 |
| 12 | otp | Альтернативная табачная продукция | 1 |
| 13 | water | Упакованная вода | 4 |
| 14 | furs | Товары из натурального меха | |
| 15 | beer | Пиво, напитки, изготавливаемые на основе пива, слабоалкогольные напитки | 5 |
| 16 | ncp | Никотиносодержащая продукция | 1 |
| 17 | bio | Биологически активные добавки к пище | 2 |
| 19 | antiseptic | Антисептики и дезинфицирующие средства | 2 |
| 21 | seafood | Морепродукты | 3 |
| 22 | nabeer | Безалкогольное пиво | 4 |
| 23 | softdrinks | Соковая продукция и безалкогольные напитки | 4 |
---
---
# Данные для интеграции
# Где взять данные для интеграции с Инвойсбокс
**Все интеграционные данные находятся в [личном кабинете](https://business.invoicebox.ru/Login)**
Проведение тестовых платежей будет доступно после регистрации и создания магазина
> [!NOTE]
> Интеграция нужна не всегда: счёт можно выставить вручную прямо в кабинете — с QR-кодом для оплаты
> через СБП и отчётными документами. Это бесплатно, подробности и регистрация — на странице
> [бесплатного выставления счёта](https://www.invoicebox.ru/ru/free-invoice).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## API V2
Во вкладке "Мои продажи" -> "Мои магазины" необходимо выбрать нужный магазин и перейти во вкладку "Интеграция (API)".
Отсюда потребуются:
1) Идентификатор магазина
2) Региональный код
3) API ключ
4) API пароль
5) API пользователь (нужен не для всех модулей)
**Не забудьте сохранить введённые данные**
### Тестовые данные
1) Идентификатор магазина - 207
2) Региональный код магазина - 78054
3) API пользователь - 78054-API
4) API Пароль - LM936s#3jz0
5) API ключ - LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
## API L3
Во вкладке "Мои продажи" -> "Мои магазины" необходимо выбрать нужный магазин и перейти во вкладку "Интеграция (API)".
Отсюда потребуются:
1) Идентификатор магазина
2) API ключ
3) API токен
**Не забудьте сохранить введённые данные**
### Тестовые данные
## API L3
1) Идентификатор магазина - 91cb0d9a-bc9b-4420-bf2d-fd44bc9f8657
2) API ключ - QrUSjD1ZlsMbg2RNCXibRX6sKZ7FWzBh
3) API токен - 25622-API:1b3a082f38ae682ed9d2aaa5c7bb2735c43b9c7282418545bc2235a9b4bf23ad
## API V3
1) Идентификатор магазина - ffffffff-ffff-ffff-ffff-ffffffffffff
2) API ключ - 098f6bcd4621d373cade4e832627b4f6
3) API токен - b37c4c689295904ed21eee5d9a48d42e
## URL для уведомлений
Также необходимо заполнить графу "URL уведомления", сюда сервер Инвойсбокс будет отправлять запрос для подтверждения оплаты заказа.
Это URL указан в инструкции, если используется модуль для CMS.
При интеграции по API вам нужно будет указать свой адрес
О том, как работает обработка уведомлений можно узнать [здесь](https://docs.invoicebox.ru/docs/merchant/notification)
---
# Приём платежей
# Методы для организации приёма платежей
Описываемые методы предназначены для интернет-магазинов, веб-сервисов и приложений, с его помощью можно произвести
интеграцию с платёжным решением системы «Инвойсбокс». Обратите внимание, что далее будут описаны базовые
функции протокола.
### Какие функции позволяют реализовать описываемые методы?
1. Создавать заказы и направлять счета для покупателей;
2. Получать информацию и управлять сформированными заказами;
3. Получать информацию об оплате заказов;
4. Возвращать деньги покупателям по оплаченным заказам;
### Готовые библиотеки и компоненты
Описываемые методы реализованы в [SDK](/docs/merchant/sdk), готовых [модулях для CMS](/docs/merchant/cms),
[модулях для CRM](/docs/merchant/crm) и [модулях для ERP](/docs/merchant/erp). Для быстрого старта, вы также
можете воспользоваться [платёжными виджетами](/docs/merchant/widget).
### Кто может подключиться
Инвойсбокс работает с организациями и индивидуальными предпринимателями.
Самозанятые на налоге на профессиональный доход не обслуживаются.
Договор запрещает принимать оплату за ряд товаров и услуг. Коротко: всё, что нарушает
законодательство России; наркотики, стероиды и контролируемые вещества; лекарственная атрибутика;
алкоголь и табак; краденое, включая цифровое; материалы сексуального характера; нарушение авторских,
патентных и смежных прав; оружие, боеприпасы и регулируемые ножи; персональные данные третьих лиц;
финансовые пирамиды и схемы быстрого обогащения; рента и лотерейные контракты; обмен валюты и
обналичивание чеков; реструктуризация кредитов; финансирование политических партий; вероятные
подделки; программы и медиа без прав на распространение.
Полный перечень — в пункте 5 договора. Если ваш случай близок к границе, спросите менеджера до
интеграции, а не после.
### Что доступно на бесплатном тарифе
Без оплаты работают выставление счёта, оплата по счёту на расчётный счёт поставщика и мгновенная
оплата через СБП по QR-коду. При этом поступление оплаты по счёту магазин отслеживает сам и сам же
оформляет отчётные документы.
На платном тарифе прохождение платежей и оформление документов для покупателя происходит
автоматически — это и есть основная разница. Условия: https://www.invoicebox.ru/ru/free-invoice
### Перед началом работы
Для работы с методами понадобятся:
- **идентификатор магазина** — выдаётся при подключении к Инвойсбоксу;
- **API-токен и ключ проверки подписи** — без токена не пройдёт ни один запрос, ключом проверяется
подпись уведомлений; где их взять — [данные для интеграции](/docs/merchant/integrationdata/);
- **адрес для уведомлений** — куда Инвойсбокс будет присылать
[уведомление о смене статуса заказа](/docs/merchant/notification/status/).
Как передавать токен в запросах — в разделе [авторизации](/docs/api/auth/). Если чего-то из этого нет,
запросите у своего менеджера или у службы поддержки.
---
---
# Платёжная страница
# Платёжная страница
Платёжная страница — единственное, что покупатель видит от Инвойсбокса. Магазин
[создаёт заказ](/docs/merchant/order/create/) и переадресует на неё покупателя; тот выбирает способ
оплаты, платит и возвращается обратно на сайт магазина.
Адрес страницы приходит в ответе на создание заказа — поле `paymentUrl`
[в OrderResponse](/docs/merchant/order/create/#orderresponse). Его открывают переадресацией или
кодируют в QR-коде, если покупатель платит на месте.
## Что видит покупатель
Набор способов зависит от того, кем он платит. Тип задаётся полем `customer.type` при создании заказа
либо выбирается на самой странице, если магазин разрешил выбор.
| Способ оплаты | Физическое лицо | Организация или ИП | Что формируется по итогу |
|---|---|---|---|
| Банковская карта | да | да | Фискальный чек, [онлайн-касса](/docs/merchant/fz54/) |
| СБП по QR-коду | да | да | Фискальный чек |
| СБП B2B | нет | да | Счёт и закрывающие документы |
| Оплата по счёту | нет | да | Счёт, затем акт, счёт-фактура и УПД после оплаты |
| Отсрочка платежа | нет | да | Те же документы, деньги продавцу приходят сразу ([сроки](/docs/terms/)) |
| [Обещанный платёж](/docs/merchant/payment-instruments/) | нет | да | Подтверждение картой, оплата переводом в течение 5 дней |
| [Гарантийный фонд](/docs/merchant/payment-instruments/) | нет | да | Списание с баланса организации, подтверждение кодом |
Реквизиты организации страница проверяет на месте: при неверном ИНН покупатель увидит
сообщение об ошибке, а неправильно заполненные поля будут подсвечены — оплатить с
некорректным ИНН не получится.
Физлицо получает чек, организация — комплект документов. Отсюда простое правило: если в вашем сценарии
важны закрывающие документы, передавайте `customer.type: legal` и реквизиты организации.
## Что настраивается магазином
- **Возврат покупателя.** Адреса `itransfer_url_return` и `itransfer_url_returnsuccess` в
[виджете](/widgets/constructor/) либо соответствующие поля заказа в API.
- **Срок жизни счёта.** Поле `expirationDate`: по его истечении неоплаченный заказ можно
[отменить](/docs/merchant/order/delete/).
- **Язык страницы.** Поле `languageId` при создании заказа: `ru` или `en`.
- **Дополнительные услуги.** Если магазин подключён к [маркетплейсу](/docs/marketplace/), покупателю
на странице оплаты предлагаются сопутствующие предложения партнёров.
## Как узнать об оплате
Возврат покупателя на страницу «спасибо» ничего не доказывает: этот адрес открывается в браузере и его
можно набрать руками. Единственный надёжный сигнал —
[уведомление о смене статуса заказа](/docs/merchant/notification/status/). По нему запускайте отгрузку,
выдачу услуги и всё остальное. Для сверки пригодится
[получение заказа](/docs/merchant/order/get/).
## Что дальше
- [Платёжные инструменты для B2B](/docs/merchant/payment-instruments/) — чем отличаются способы оплаты для организаций и ИП.
- [Схемы документооборота](/docs/merchant/schema/) — какие документы формируются в каждой схеме.
- [Готовые модули CMS](/docs/merchant/cms) — если не хочется собирать переадресацию руками.
---
---
# Уведомление о смене статуса
# Уведомление по умолчанию
Если в настройках Магазина была активирована опция отправки автоматических уведомлений о смене
статуса Заказа, то при поступлении оплаты в пользу Заказа, система «Инвойсбокс»
осуществит запрос на специальный URL, который указан в настройках Магазина.
На указанный URL будет осуществлен `POST` запрос с `Content-Type: application/json` в теле которого будет находиться объект [OrderNotification](#ordernotification).
## OrderNotification
Повторяет структуру [OrderResponse](/docs/merchant/order/create/#orderresponse), основные поля:
| Свойство | Обязательное | Тип | Описание |
|------------------------|--------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор заказа в системе «Инвойсбокс», например: `01771534-1a57-f184-dee3-ebeb91dded75` |
| status | да | string(50) enum | Статус заказа: `created`, `hold`, `completed`, `expired`, `canceled`. Оплаченным считается только `completed` — перечень и переходы на странице [работы с заказом](/docs/merchant/order/) |
| merchantId | да | string(36) | Идентификатор магазина, например: `01771534-1a57-f184-dee3-ebeb91dded76` |
| merchantOrderId | да | string(100) | Идентификатор заказа в учётной системе магазина, например: `O-12345` |
| merchantOrderIdVisible | нет | string(100) | Номер заказа, отображаемый на платежной странице. Если не заполнено, показывается значение из merchantOrderId например `111TN22-33` |
| amount | да | float | Сумма заказа, например: `19658.45` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике |
| currencyId | да | string(3) enum | Валюта заказа, например: `RUB`, `USD`,`EUR`, `GBP` |
| createdAt | да | datetime | Дата создания заказа, например: `2026-12-22T00:00:00+00:00` |
Заказ считается оплаченным, если его статус равен `completed`. В этом случае Магазин должен сверить
сумму Заказа в запросе с суммой Заказа в своей системе учёта. Если не совпадает, в обработке запроса
нужно отказать и вернуть ошибку.
Перечень статусов закрытый: кроме пяти перечисленных, других не бывает. Статусов вида `refunded` или
`partial_refund` в заказе нет — возврат оформляется [отдельным заказом](/docs/merchant/refund/create/)
со своими статусами (`draft`, `created`, `completed`, `canceled`), а сам заказ после возврата остаётся
`completed`.
# Формат ответа
В случае успешности обработки запроса веб-сервис Магазина должен вернуть объект [NotificationSuccess](#notificationsuccess), а в случае осознанной ошибки обработки (например, неверная сумма, заказ не найден, ошибка подписи и т.п.) - [NotificationError](#notificationerror).
> [!IMPORTANT]
> **И успешный, и осознанно-ошибочный ответ должны возвращаться с HTTP-кодом 200.** HTTP-код 200 сам по себе не означает успех — успехом считается только связка **HTTP 200 + `{"status":"success"}`** в теле. Связка **HTTP 200 + `{"status":"error", "code": ...}`** — это тоже штатный, ожидаемый ответ, просто сигнализирующий об осознанной ошибке обработки (см. [NotificationErrorCode](#notificationerrorcode)).
>
> Любой ответ с HTTP-кодом, отличным от 200 (а также ответ без валидного JSON в теле), система «Инвойсбокс» трактует не как конкретный код ошибки из тела, а как **техническую недоступность веб-сервиса Магазина** — то есть равносильно `out_of_service`, независимо от того, что написано в `code`. Такие запросы будут повторены ещё до 10 раз в течение суток (см. [NotificationErrorCode](#notificationerrorcode)).
>
> Другими словами: `code` в теле ответа имеет смысл, только если HTTP-код равен 200. Если веб-сервис Магазина вернул, например, HTTP 400 или 401 — тело ответа не разбирается, и запрос будет повторён как при `out_of_service`, даже если в теле был указан другой код ошибки (например, `signature_error`).
## NotificationSuccess
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|-----------------------------------------------------------------------|
| status | да | string(50) | В случае успешной обработки допустимо только одно значение - `success` |
Пример объекта NotificationSuccess:
```json
{
"status" : "success"
}
```
## NotificationError
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------------|---------------------------------------------------------------------------------------------------------------------|
| status | да | string(50) enum | В случае ошибки обработки запроса допустимо только одно значение - `error` |
| code | нет | string(100) enum | Код ошибки - значение из справочника [NotificationErrorCode](#notificationerrorcode), по умолчанию `out_of_service` |
| message | нет | string(500) | Детальное описание ошибки в текстовом формате |
Пример объекта NotificationError:
```json
{
"status" : "error",
"code" : "order_wrong_amount",
"message" : "Сумма заказа не соответствует сумме оплаты"
}
```
## NotificationErrorCode
| Код ошибки | Описание |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `out_of_service` | Техническая ошибка обработки запроса веб сервером Магазина, при получении этого кода ошибки система «Инвойсбокс» будет пытаться повторить этот запрос еще 10 раз в течение последующих суток. |
| `order_wrong_amount` | Сумма заказа в Магазине не соответствует сумме заказа в уведомлении |
| `order_already_paid` | Заказ уже оплачен другим инструментом оплаты |
| `order_not_found` | Заказ не найден в учётной системе Магазина |
| `shipping_unavailable` | [Услуга не может быть оказана или товар не может быть доставлен](/docs/merchant/notification/shipping-unavailable/) |
| `full_refund_required` | То же самое что `shipping_unavailable` с автоматическим формированием возврата или отмены оплаты |
| `signature_error` | Ошибка проверки подписи запроса |
> [!IMPORTANT]
> Обратите внимание, в случае, если аналогичный запрос с тем же идентификатором (id) уже был обработан ранее
> успешно в вашей системе, то в этом случае следует вернуть статус успешной обработки уведомления status = `success`.
>
> В случае, если заказ в вашей системе был оплачен ранее уведомлением с другим идентификатором (id) или иным платёжным инструментом,
> то следует вернуть ошибку status = `error`, code = `order_already_paid`.
## Время выполнения запроса
Существует лимит ожидания ответа от веб-сервера Магазина на запросы уведомления, который составляет 20 секунд.
Запросы отрабатывающие дольше этого значения считаются ошибочными.
## Подпись запроса
При обработке запроса уведомления Магазину необходимо проверить его целостность.
Для этого необходимо сформировать подпись тела входящего запроса и сравнить со значением из заголовка `X-Signature`.
Если эти значения не совпадают, необходимо сформировать ответ [NotificationError](#notificationerror) с
[NotificationErrorCode](#notificationerrorcode) `signature_error` и вернуть его с **HTTP-кодом 200** — как и для
любого другого [NotificationError](#notificationerror) (см. [Формат ответа](#формат-ответа)). Возврат HTTP 400/401/403
вместо 200 приведёт к тому, что «Инвойсбокс» не разберёт `code` из тела ответа и обработает запрос как
техническую ошибку `out_of_service`, а не как `signature_error`. Электронная подпись формируется путем
криптографического преобразования содержимого тела запроса с использованием ключа и алгоритма выбранных в настройках уведомлений.
Ключ свой у каждого магазина, а не общий на учётную запись: если магазинов несколько, проверяйте
подпись ключом того магазина, чей `merchantId` пришёл в теле уведомления.
По умолчанию используется алгоритм `sha1` и метод `hmac`. Ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс.
#### Пример проверки подписи на языке PHP
```php
$value) {
if (strtolower($header) === 'x-signature') {
$xSignature = $value;
break;
}
}
if (!$xSignature) {
// Ошибка, подпись запроса не получена.
// HTTP-код ответа здесь не задаётся явно, поэтому используется код 200 по
// умолчанию — это обязательно, иначе "Инвойсбокс" не разберёт code из тела.
header("Content-Type: application/json");
die('{"status":"error","code":"out_of_service"}');
}
$payload = file_get_contents("php://input");
$apiKey = ""; // Согласованный ключ для подписи
$calcSignature = hash_hmac("sha1", $payload, $apiKey);
// hash_equals, а не !=: обычное сравнение отвечает тем быстрее, чем раньше строки
// разошлись, и по этому времени подпись можно подобрать
if (!hash_equals($calcSignature, $xSignature)) {
// Ошибка, подпись запроса неверная.
// HTTP-код ответа — 200 по умолчанию (см. выше), а не 400/401.
header("Content-Type: application/json");
die('{"status":"error","code":"signature_error"}');
}
```
#### Пример проверки подписи на языке Python
```python
import hashlib
import hmac
from flask import Flask, request, jsonify
app = Flask(__name__)
# Проверьте правильность пути и метода в декораторе @app.route()
# - его нужно подстроить под ваше веб-приложение.
@app.route("/invoicebox_callback", methods=['POST'])
def invoicebox_callback():
x_signature = request.headers.get('x-signature')
if not x_signature:
# Ошибка, подпись запроса не получена.
# HTTP-код должен быть 200 — иначе "Инвойсбокс" не разберёт code из тела
# и посчитает ответ технической ошибкой (out_of_service).
response = jsonify({'status': 'error', 'code': 'out_of_service'})
response.headers["Content-Type"] = "application/json"
return response, 200
# Согласованный ключ для подписи
api_key = ""
payload = request.data
calc_signature = hmac.new(api_key.encode(), payload, hashlib.sha1).hexdigest()
# compare_digest, а не !=: обычное сравнение выдаёт по времени, сколько символов совпало
if not hmac.compare_digest(calc_signature, x_signature):
# Ошибка, подпись запроса неверная.
# HTTP-код должен быть 200, а не 400/401 — см. раздел "Формат ответа".
response = jsonify({'status': 'error', 'code': 'signature_error'})
response.headers["Content-Type"] = "application/json"
return response, 200
# Подпись верна: здесь отмечаем заказ оплаченным в своей учётной системе —
# идемпотентно, потому что то же уведомление может прийти повторно.
# mark_order_paid(request.get_json())
return jsonify({'status': 'success'}), 200
```
[Для удобства, смотрите также PHP SDK](/docs/merchant/sdk/php/)
## Как проверить свой обработчик
Тратить деньги для проверки не нужно: **на демо-магазине оплата подтверждается на платёжной
странице автоматически**. Достаточно довести заказ до платёжной страницы, и уведомление уйдёт
так же, как в бою.
1. Укажите адрес обработчика в личном кабинете: «Мои продажи» → «Мои магазины» →
«Интеграция (API)», поле «URL уведомления». Адрес должен быть публичным и работать по
HTTPS — на `localhost` уведомление не придёт.
2. [Создайте заказ](/docs/merchant/order/create/) своим токеном на своём магазине.
3. Откройте `paymentUrl` из ответа. На демо-магазине оплата подтвердится сама.
4. Обработчик получит уведомление того же формата, что в бою; ответьте
`200 {"status":"success"}` — иначе уведомление придёт повторно.
### Если своего магазина ещё нет
Посмотреть на живое уведомление можно и без него. Заказы, созданные кнопкой «Выполнить» в
документации, уходят с адресом уведомлений портала: что прислал Инвойсбокс — статус, сумма, тело
запроса и результат проверки подписи — видно в [песочнице на быстром старте](/quickstart/#уведомление).
Ключ подписи демо-магазина — `5a3797956281681be7cbb33ffc390ea1`, метод `hash_hmac`, алгоритм `sha1`.
С ними тот же расчёт повторяется на вашей стороне: сравните свою подпись с той, что пришла в
заголовке `X-Signature`.
Свой обработчик всё равно нужно проверить на своём магазине — адрес уведомлений задаётся либо в
личном кабинете, либо полем `notificationUrl` при создании заказа.
Если обработчика ещё нет, а посмотреть на смену статуса хочется, статус заказа можно прочитать
запросом: [Получение заказа](/docs/merchant/order/get/).
## Система мониторинга и автоматическое тестирование интеграции
В системе мониторинга «Инвойсбокс» реализовано автоматическое тестирование работоспособности интеграции.
Для проверки корректности интеграции, система может направлять тестовое уведомление, в котором в качестве идентификатора заказа в учётной системе магазина будет
передано пустое значение, в качестве идентификатора заказа в системе «Инвойсбокс» будет передано значение `ffffffff-ffff-ffff-ffff-ffffffffffff`.
При получении такого запроса, система учёта магазина должна проверить корректность подписи запроса, сверить идентификатор магазина с настройками и вернуть ответ по результатам проверки.
---
---
# 1С Битрикс
# Описание модуля 1С Битрикс
Затем добавьте новую платёжную систему в настройках магазина
На открывшейся странице:
1. Выберите "Обработчик": «Инвойсбокс» (invoicebox);
2. Выберите версию платёжной системы: Инвойсбокс v2 или Инвойсбокс v3;
3. Если требуется измените "Заголовок" и "Название";
2. Выберите версию платёжной системы: Инвойсбокс l3(текущий) или Инвойсбокс v3(новый);
3. Если требуется, измените "Заголовок" и "Название";
4. **(обязательно)** Укажите кодировку "UTF-8";
5. **(обязательно)** Снимите, если установлены, 2 чекбокса "Разрешить печать чеков" и "Открывать в новом окне".
В блоке «Настройка обработчика ПС» настройте следующие параметры:
- В случае выбора в типе платежной системы версии Инвойсбокс v3, требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v3»:
- Идентификатор магазина - укажите идентификатор магазина, полученный при заключении договора;
- В случае выбора в типе платежной системы версии Инвойсбокс l3(текущий), требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v3»:
- Идентификатор магазина - укажите идентификатор магазина, полученный при заключении договора;
- Авторизационный токен - формируется в момент регистрации магазина в системе «Инвойсбокс» и направляется по электронной почте в письме «Об активации в системе «Инвойсбокс». Если письмо не пришло, вы можете сформировать его автоматически в личном кабинете (в разделе Настройки);
- Ключ для проверки подписи запроса — ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс;
- Тип позиции у товаров каталога, Тип позиции у доставки — выберите один из двух вариантов (Товар или Сервис), данные поля необходимы для чека;
- В случае выбора в типе платёжной системы версии Инвойсбокс v2 **(не рекомендуется)**, требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v2»:
- ID магазина — укажите идентификатор магазина, полученный при заключении договора;
- Региональный код магазина — укажите региональный код магазина, полученный при заключении договора;
- API ключ — укажите ключ безопасности, полученный при заключении договора;
- URL страницы для отправки уведомлений — этот параметр обычно не требуется редактировать, т. к. он устанавливается по умолчанию и значение обязательно должно быть в виде http(s)://адрес_сайта/bitrix/tools/invoicebox/notification.php;
- Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Модуль amoCRM предоставляет простую возможность подключить вашу CRM систему к «Инвойсбокс» для оформления счетов
клиентам.
# Установка расширения Инвойсбокс из амоМаркета
Модуль находится во вкладке амоМаркет -> Счета и эквайринги -> Инвойсбокс
В настройках самого модуля необходимо указать апи-токен, id магазина и ключ. Все данные отправляются после заключения договора.
Нужны три значения: токен, идентификатор магазина и ключ проверки подписи. Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
Брать актуальные данные [здесь](https://docs.invoicebox.ru/docs/merchant/integrationdata/)
## Выставление счетов
2. Создаём новый контакт, который будет выступать в роли плательщика во вкладке "списки" -> "контакты"
**Обязательно нужно указать номер телефона и email. Без этих данных счёт на оплату не будет сформирован!**
**При добавлении компании ИНН обязателен!**
3. После создаём счёт по вкладке "списки" -> "счета / покупки"
Необходимо указать:
- Цену
- Название
- Количество
- НДС. Допустимые значения: 0, 10%, 20%
4. Ссылка на оплату будет сформирована внутри счёта.
5. Сначала идёт переход на страницу Amocrm, а оттуда на платёжную страницу Инвойсбокс
## Читайте также
- [Допустимые ставки НДС](/docs/dictionary/tag1199/)
---
# iiko
# Описание модуля iiko
iiko - специализированная система ERP-класса, предназначенная для автоматизации ресторанного бизнеса.
Модуль (плагин) Инвойсбокс для iiko предоставляет простую возможность организации приёма оплаты от организаций и
индивидуальных предпринимателей в залах ресторана.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке, пожалуйста,
обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Требования
- Минимальная версия `iiko 7.9.7` так как плагин использует `Front API v7`
- Наличие лицензии `api payment (21016318)`
- Запуск iikoFront от имени администратора
- НДС должен быть включен в стоимость блюд
## Установка модуля (плагина)
[Скачайте](https://repo.open-s.info/Plugins/iiko/BeOpen.Front.Plugin.InvoiceBox/) и распакуйте архив с модулем в папку `C:\Program Files\iiko\iikoRMS\Front.Net\Plugins`
## Настройка модуля (плагина)
Перейдите в папку `C:\Program Files\iiko\iikoRMS\Front.Net\Plugins\BeOpen.Plugins.Invoicebox`
и с помощью блокнота откройте конфигурационный файл `BeOpen.Plugins.Invoicebox.dll.config`.
В конфигурационном файле модуля укажите следующие значения параметров:
- **WS** – адрес вебсокета, к которому требуется подключиться: `ws-gate.invoicebox.ru` (см. [использование веб-сокетов](/docs/api/websockets/))
- **TimeWebSocketSecond** – частота проверки подключения к веб-сокету в секундах: `10`
- **Url** – базовый URL Инвойсбокс API: `https://api.invoicebox.ru` (см. [подключение к API](/docs/api))
- **RoundPolicy** - политика округления, рекомендуется `none`
- **PartnerId** – идентификатор (GUID) Магазина в системе Инвойсбокс. Если ваша организация ещё не зарегистрирована в системе Инвойсбокс, см. ниже функцию регистрации в настройках iikoFront
- **PaymentType** – идентификатор (GUID) типа оплаты. При запуске iikoFront с плагином (модулем), в лог будут выведены все типы оплат, выберите нужный.
Лог плагина находится в папке: `%appdata%\iiko\CashServer\Logs`, название файла: `plugin-BeOpen.Plugins.Invoicebox.log`.
#### Пример заполненного конфигурационного файла
``` xml
Плагин при старте проверяет, есть ли тип заказа invoicebox, и в случае, если его нет, выдает ошибку *«Для запуска платина invoicebox, создайте в системе тип заказа invoice_box, и сделайте доступным для данного терминала».*
В iikoOffice переходим в раздел “Сотрудники” - “Должности” и нажимаем “Добавить”, создаем должность по примеру:
Созданную должность назначаем системному пользователю плагина. Это необходимо, чтобы другой сотрудник ресторана без указанной должности, не смог добавить в заказ тип оплаты invoicebox.
В iikoOffice переходим в раздел “Розничные продажи” - “Типы оплат” и нажимаем “добавить”.
Тип оплаты - внешний, название выбираете по желанию клиента. В поле безналичный тип выбираем InvoiceboxPayment после первого старта плагина.
## Настройка в iikoFront
Перезапустите iikoFront, откройте вкладку дополнений в главном меню.
Если ваша организация ещё не зарегистрирована в Инвойсбокс, нажмите "Инвойсбокс: Регистрация в системе" и в открывшемся
окне укажите электронный адрес администратора. Дождитесь получения письма от системы Инвойсбокс.
Если ваша организация уже зарегистрирована, нажмите "Инвойсбокс: активация кассы", укажите код активации кассы.
## Логика работы
Путь одного заказа целиком: от пречека на кассе до уведомления, по которому iiko закрывает стол.
```mermaid
sequenceDiagram
participant O as Официант в iikoFront
participant P as Плагин Инвойсбокса
participant I as API Инвойсбокс
participant G as Гость
O->>P: печать пречека, тип оплаты «Инвойсбокс»
P->>I: создание заказа с составом и суммой
I-->>P: paymentUrl
P->>O: QR-код на пречеке
G->>I: оплата по QR-коду на платёжной странице
I->>P: уведомление о смене статуса
P->>O: заказ закрыт, стол свободен
```
Если в заказе указан тип заказа Инвойсбокс (invoicebox), заказ проходит проверку и на пречеке формируется QR-код.
**Передача состава заказа**
При формировании QR-кода в систему Инвойсбокс передается состав заказа и его сумма.
Для каждого блюда в заказе указываются его наименование, цена позиции, номинал и сумма НДС, количество и сумма с учётом скидки, модификаторы и их цена.
**Оплата**
После того, как гость перейдёт по QR-коду и произведёт оплату, в заказ в iikoFront будет добавлена оплата на сумму заказа с типом из конфигурационного файла и заказ будет закрыт.
**Ограничения**
QR-код НЕ будет напечатан в случае, если в заказе есть:
1. Бесплатные блюда и модификаторы
2. Надбавка
3. Блюда с составными модификаторами
Не поддерживаются предоплаты (QR-код будет сформирован на полную сумму заказа)
Поддерживается только НДС, включенный в стоимость
При каждой печати пречека запрос отправляется заново и создается новый QR-код.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке, пожалуйста,
обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts). Для ускорения процесса
диагностики, пожалуйста, приложите к обращению файл лога модуля (плагина), который находится в папке: `%appdata%\iiko\CashServer\Logs`,
название файла: `plugin-BeOpen.Plugins.Invoicebox.log`.
---
# Схема взаимодействия
# Схема партнёрского взаимодействия
Половина отказов при создании заказа — это расхождение сумм. Правило простое:
- `amount` заказа равен сумме `totalAmount` всех позиций корзины;
- `vatAmount` заказа равен сумме `totalVatAmount` всех позиций;
- в позиции `amount` — цена одной единицы, `totalAmount` — за всё количество (`quantity × amount`);
- `amountWoVat` — цена единицы без НДС; сумма без НДС и сумма НДС вместе дают `totalAmount`;
- строгость сверки задаёт `orderSetting.roundPolicy` (по умолчанию `none`).
Если суммы не сходятся, API отвечает ошибкой `wrong_total_vat_amount` — расшифровка и остальные коды
в [справочнике ошибок](/docs/dictionary/error/).
Ставка НДС передаётся кодом в поле `vatCode` позиции: с 2026 года основная ставка — 22 %
(`RUS_VAT22` — НДС в цене, `RUS_VAT22_ADDED` — НДС сверху). Полный перечень — в
[справочнике ставок](/docs/dictionary/tag1199/).
## Фискальные поля позиции
Чек формирует онлайн-касса, а данные для него берутся из позиций корзины. Реквизиты чека,
которые в 54-ФЗ называются тегами, передаются обычными полями:
| Реквизит чека | Поле позиции | Справочник |
|---|---|---|
| Признак предмета расчёта (тег 1212) | `type` | [значения](/docs/dictionary/tag1212/) |
| Признак способа расчёта (тег 1214) | `paymentType` | значения в таблице [BasketItem](#basketitem) |
| Ставка НДС | `vatCode` | [ставки НДС](/docs/dictionary/tag1199/) |
| Единица измерения | `measureCode` | [ОКЕИ](/docs/dictionary/okei/) |
Как устроена фискализация и когда чек попадает покупателю — [онлайн-касса](/docs/merchant/fz54/).
## Пока заказ не оплачен
Созданный заказ не высечен в камне:
- сумму и состав можно [изменить](/docs/merchant/order/update/) — новый заказ создавать не нужно;
- ненужный заказ [отменяют](/docs/merchant/order/delete/);
- когда наступает время из `expirationDate`, заказ сам переходит в статус `expired`: оплатить по
прежней ссылке нельзя, нужен новый заказ. О переходе магазин узнаёт из
[уведомления о смене статуса](/docs/merchant/notification/status/) — обработайте этот статус, иначе
заказ останется в вашей системе «ждущим оплаты» навсегда.
## Повтор после сбоя и таймаута
Сеть обрывается на самом неудачном месте: запрос ушёл, ответ не вернулся, и магазин не знает,
создан ли заказ.
Сразу о главном: **по умолчанию уникальность `merchantOrderId` не проверяется**. Номер можно передать
любой, в том числе уже использованный, — и на тот же номер создастся второй заказ. Значит слепой
повтор после таймаута приводит к двум счетам на одну покупку, а идемпотентности у создания заказа нет
ни полной, ни частичной.
Порядок действий, который от этого защищает:
1. Сохраните `merchantOrderId` до отправки запроса и не меняйте его при повторах — он строится из
номера покупки в вашей системе, а не из случайного числа.
2. Если ответ не пришёл (таймаут, обрыв, `5xx`), **не отправляйте создание заново**. Сначала спросите,
есть ли заказ — созданный заказ виден в выборке сразу, поэтому пустой ответ означает, что заказа
нет, и ждать не нужно:
```http
GET /v3/filter/api/order/order?merchantOrderId=O-12345
```
3. Заказ нашёлся — сверьте `merchantId`, сумму и состав с тем, что отправляли, и берите из него `id`
и `paymentUrl`.
4. По номеру нашлось несколько заказов — остановите автоматическую обработку и разберитесь вручную.
Выбирать «последний по `createdAt`» нельзя: скорее всего дубль создал предыдущий неудачный повтор,
и лишние счёта нужно отменить, а не тихо выбрать один из них.
5. Заказ не нашёлся — повторите создание с тем же номером.
6. Новый номер генерируйте только для новой покупки. Новый номер после неудачи — это второй заказ на
ту же покупку: покупатель увидит два счёта, а магазин — двойную выручку в отчётах.
> [!IMPORTANT]
> Проверку уникальности можно включить на стороне Инвойсбокса: это настройка магазина, и меняет её
> [служба поддержки](https://www.invoicebox.ru/ru/contacts) по обращению. С включённой проверкой
> повторный номер вернёт ошибку `merchant_order_id_duplicate` — это страховка от второго заказа, а не
> замена порядку выше: ответ первого запроса повтор всё равно не вернёт, `id` и `paymentUrl` придётся
> получить выборкой. Если номера заказов у вас и так уникальны, проверку стоит попросить включить.
### Что можно повторять
| Что случилось | Чтение (GET) | Создание, возврат, отмена |
|---|---|---|
| Таймаут или обрыв связи | повторить сразу | результат неизвестен: сначала выборка по `merchantOrderId`, повтор — только если операции нет |
| `5xx` | повторить с задержкой | то же: запрос мог дойти и выполниться |
| `429` — превышен [лимит частоты](/docs/api/limits/) | повторить с растущей задержкой | повторить с растущей задержкой: до операции запрос не дошёл |
| Прочие `4xx` | не повторять | не повторять: причина в данных запроса, а не в связи |
Задержку увеличивайте от попытки к попытке (например, 1, 2, 4, 8 секунд) и добавляйте случайный
разброс, чтобы повторы нескольких процессов не сошлись в одну секунду. Заголовка `Retry-After` в
ответах нет — паузу выбирает магазин.
### Возврат и отмена
Правило то же, меняется только запрос, которым вы проверяете результат.
**Возврат.** У каждого возврата свой `merchantOrderId` — по нему и ищите:
```http
GET /v3/filter/api/order/refund-order?merchantOrderId=R-12345
```
Нашёлся — возврат создан, работайте с ним. Не нашёлся — повторяйте создание с тем же номером. Новый
номер после неудачи означает второй возврат по тому же заказу.
**Отмена заказа.** Прочитайте заказ и посмотрите статус: `canceled` — отмена прошла, повторять
нечего. Любой другой статус — отмену можно повторить, она идемпотентна по смыслу: отменить уже
отменённый заказ нельзя, и API ответит ошибкой, а не отменит что-то ещё.
## CreateOrderRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------------------|--------------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| description | да | string(1000) | Описание заказа | `Оплата номера в отеле` |
| merchantId | да | string(36) | Идентификатор магазина. В примерах на этой странице стоит демо-магазин — свой возьмите в личном кабинете, вкладка «Интеграция (API)» | `ffffffff-ffff-ffff-ffff-ffffffffffff` |
| merchantOrderId | да | string(100) | Идентификатор заказа в учётной системе магазина, должен быть уникальным | `O-12345` |
| merchantOrderIdVisible | нет | string(100) | Номер заказа, отображаемый на платежной странице. Если не заполнено, показывается значение из merchantOrderId | `111TN22-33` |
| amount | да | float | Сумма заказа, ограничений нет | `19658.45` |
| vatAmount | да | float | Сумма НДС | `156.56` |
| currencyId | да | string(3) enum | Код валюты заказа в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| languageId | нет | string(2) enum | Язык интерфейса платежной страницы | `ru`, `en` |
| expirationDate | да | datetime | Срок действия заказа | `2026-12-22T00:00:00+00:00` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| metaData | нет | object | [Дополнительные данные заказа](/docs/merchant/order/metadata/) | |
| customer | да | [Customer](#customer) | Информация о заказчике | |
| notificationUrl | нет | string(1000) | URL для отправки [уведомлений](/docs/merchant/notification) об изменениях статуса заказа, по умолчанию используется URL из настроек магазина | |
| successUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае успешной оплаты | `https://shop.example.com/order/4412?result=success` |
| failUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае ошибки оплаты | `https://shop.example.com/order/4412?result=fail` |
| returnUrl | нет | string(1000) | Ссылка для возврата на сайт Магазина (кнопка «вернуться в магазин» на платёжной странице) | `https://shop.example.com/order/4412?result=return` |
| invoiceSetting | нет | [InvoiceSetting](#invoicesetting) | Дополнительные настройки параметров оплаты | |
| orderSetting | нет | [OrderSetting](#ordersetting) | Дополнительные настройки параметров заказа | |
| parentId | нет | string(36) | Идентификатор базового заказа, применимо для создания [корректирующих заказов](/docs/merchant/refund/correction/) | `01771534-196a-1105-839a-82422289d6d9` |
| orderContainerId | нет | string(36) | Идентификатор основного заказа, применимо для добавления заказа к уже существующему счёту | `01771534-196a-1105-839a-82422289d6d9` |
| shopId | нет | string(36) | Идентификатор связанного магазина/маркетплейса | `06581534-196a-1105-839a-82422289d6d8` |
| userAccountId | нет | string(36) | Идентификатор программы лояльности | `06581534-196a-1105-839a-82422289d6d7` |
| processable | нет | bool | Признак процессингового заказа: `true` — расчёты проходят в биллинге Инвойсбокса (по умолчанию), `false` — [непроцессинговый заказ](/docs/merchant/order/non-processable-order/): оплату принимает магазин, а Инвойсбокс формирует документы | `true`, `false` |
| subtype | нет | string(36) | Подтип заказа, возможные значения `order` - обычный заказ (по умолчанию). `hold` - заказ с холдированием | `order`, `hold` |
## OrderResponse
Повторяет свойства объекта [CreateOrderRequest](#createorderrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------|--------------|-----------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз для оплаты заказа | |
| createdAt | да | datetime | Дата создания заказа | `2026-12-22T00:00:00+00:00` |
| status | да | string(50) enum | Статус заказа: `created` — ожидает оплаты, `completed` — успешная оплата, `hold` — средства захолдированы | `completed`, `hold` |
| paidAt | нет | datetime | Дата оплаты заказа (если оплачен) | `2026-12-22T00:00:00+00:00` |
| paymentInfo | нет | [PaymentInfo](#paymentinfo) | Информация об оплате и плательщике | `{"maskedPan": "220024**0954", "expiration": "202601", "paymentSystem": "MIR", "cardholderName": "CARDHOLDER NAME"}` |
| holdTill | нет | datetime | Дата и время списания холдированных средств (для заказов с подтипом `hold`) | `2026-08-03T12:00:00+03:00` |
> [!IMPORTANT]
> В зависимости от сценария использования API, ссылка для перехода на платёжный шлюз (paymentUrl) может быть получена для
> переадресации пользователя в браузере или же закодирована в QR-коде для дальнейшего его сканирования камерой или приложением
> Инвойсбокс.
## Customer
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-----------------|-------------------|------------------------------------------------------|
| type | нет | string(10) enum | Тип заказчика | `legal` - юр. лицо, `private` - физ лицо |
| name | нет | string(500) | Наименование или имя | `ООО «Ромашка»` |
| phone | нет | string(100) | Номер телефона | `79001112233` |
| email | нет | string(100) | Электронная почта | `buh@example.invbox.ru` |
| vatNumber | нет | string(20) | ИНН | `7701234560` |
| taxRegistrationReasonCode | нет | string(9) | КПП | `770101001` |
| registrationAddress | нет | string(1000) | Юр. адрес, включая почтовый индекс | `190000, Санкт-Петербург, Невский пр. 147, офис 321` |
Примеры выше собраны на плательщика-организацию: `type` = `legal`, ИНН в `vatNumber`, КПП в
`taxRegistrationReasonCode`. По этим реквизитам покупателю уходят закрывающие документы. У ИП КПП нет —
поле остаётся пустым. Если платит физлицо, укажите `type` = `private`: ИНН, КПП и юридический адрес
тогда не нужны, а из документов формируется только [фискальный чек](/docs/merchant/fz54/).
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54/).
| Свойство | Обязательное | Тип | Описание |
|-------------------|----------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(36) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(300) | Наименование, например `Бронирование номера` |
| type | да | string(10) | Идентификатор типа позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или `service` - Услуга, `commodity` - Товар |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения словом, например `шт.`. Достаточно передать одно из двух полей — единицу или код: второе сервер заполнит сам по справочнику [ОКЕИ](/docs/dictionary/okei/) |
| measureCode | да | string(4) | Код единицы измерения по [ОКЕИ](/docs/dictionary/okei/), например `796`. Парное поле к `measure`: см. строку выше |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55`, ограничений нет |
| amountWoVat | да | float | Стоимость единицы без учета НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| gtdNumber | нет | string(23) | Номер грузовой транспортной накладной |
| vatCode | да | string(20) enum | Код ставки НДС Инвойсбокс, см. [справочник - ставки НДС](/docs/dictionary/tag1199/) |
| serviceDate | нет | date | Дата оказания услуги, если тип позиции = Услуга, например, 2023-11-16 |
| paymentType | да | string(20) enum | Признак способа расчёта (тег 1214): `full_prepayment`, `prepayment`, `advance`, `full_payment`. В контракте поле помечено необязательным: если его не передать, сервер подставит значение из настроек магазина. Передавайте явно — так состав чека не зависит от настройки, которую можно поменять в кабинете |
| categoryType | при наличие category | string(20) enum | Справочник категории товаров: `merchantHonestSignMap` (Справочник категорий магазина) или `honestSign` ([Честный знак](/docs/merchant/honest-sign/)) |
| category | нет | string(20) enum | Товарная группа в справочнике категорий товаров магазина или системы [Честный знак](/docs/merchant/honest-sign/): `milk`, `water` и т.д. |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
## InvoiceSetting
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-------------------------|--------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| customerLocked | нет | bool | Запретить изменение реквизитов плательщика (всех) | true - запретить изменения, по умолчанию false |
| customerLockedFields | нет | array
[МПС (EgoPay)](https://ips.su) — платёжное решение [Сирена Трэвел](https://sirena-travel.ru), позволяет
оплачивать билеты не только ТКП, но и BSP. При этом МПС поддерживает прямой процессинг в BSP.
## Решения на базе интеграции
- [Автоматизация продаж авиабилетов юридическим лицам и ИП (b2b)](/docs/scenarios/air-carriers).
## Настройка интеграции
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# Оформление возврата
# Оформление возврата
Оформить возврат средств возможно только по оплаченному заказу. Перед оплатой, пожалуйста, воспользуйтесь
[методом удаления заказа](/docs/merchant/order/delete/). Схема оформления возврата по оплаченному заказу следующая:
- Получить список доступных для возврата позиций
- Создание возвратного заказа
#### Пример запроса и ответа
``` json
GET /v3/billing/api/order/refund-order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` 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": "2023-01-09T09:46:00+03:00",
"reservationId": "70633118938830",
"reservationFor": {
"@type": "TrainTrip",
"arrivalTime": "2023-01-27T09:20:00+03:00",
"trainNumber": "092МА",
"departureTime": "2023-01-25T23: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": "2023-01-27T09: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": "2023-01-09T09:46:00+03:00",
"reservationId": "70633118938830",
"reservationFor": {
"@type": "TrainTrip",
"arrivalTime": "2023-01-27T09:20:00+03:00",
"trainNumber": "092МА",
"departureTime": "2023-01-25T23: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": "2023-01-27T09:20:00+03:00",
"idDocumentNumber": "********8015"
},
"reservationStatus": "https://schema.org/ReservationConfirmed"
}
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "created",
"shipmentStatus": "unshipped",
"subtype": "refund",
"createdAt": "2023-01-09T06: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](/docs/merchant/order/create/#basketitem)
## Частичный возврат
Возвращать всю сумму заказа не обязательно. Возврат — это отдельный заказ со своей корзиной: в
`basketItems` перечисляются только те позиции и количества, которые возвращаются, а `amount` и
`vatAmount` считаются по ним. Из заказа на 10 000 ₽ можно вернуть 3 000 ₽, оформив возврат на одну
позицию.
Возвратов по одному заказу может быть несколько. Каждому нужен свой `merchantOrderId`: по нему
Инвойсбокс отличает новый возврат от повторно отправленного и не проводит один и тот же дважды.
Какие позиции ещё доступны к возврату, показывает метод из раздела ниже.
## Создание возвратного заказа
- метод: `POST`
- ресурс: `/v3/billing/api/order/refund-order`
- тело запроса - объект [CreateRefundOrderRequest](#createrefundorderrequest)
- тело ответа - объект [RefundOrderResponse](#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](/docs/merchant/order/create/#basketitem) | Корзина заказа | |
| description | да | string(1000) | Описание заказа | `Оплата номера в отеле` |
| status | нет | string(50) enum | Статус заказа, по умолчанию `created`, так же возможен статус `draft` для создания [корректирующих заказов](/docs/merchant/refund/correction/) | `created` |
| subtype | нет | string(20) enum | Вид возврата: `refund` — обычный (по умолчанию), `secured` — [с обеспечением](#возврат-с-обеспечением) | `secured` |
> [!IMPORTANT]
> При формировании нескольких возвратов в рамках одного заказа передавайте уникальный идентификатор возвратного заказа (возврата) merchantOrderId
для каждого отдельного возврата. В случае, если будет передан уже существующий идентификатор, будет возвращена ошибка. Подобный механизм предупреждает инциденты
случайных двойных возвратов.
## Возврат с обеспечением
Обычный возврат уходит в выплату сразу после создания: покупатель получает деньги, а магазин
рассчитывается с Инвойсбоксом потом. Возврат с обеспечением меняет порядок на обратный — сначала
деньги вносит магазин, и только потом стартует выплата покупателю. Такой возврат создаётся тем же
методом с полем `subtype`:
``` json
{
"parentId": "01771534-196a-1105-839a-82422289d6d9",
"merchantOrderId": "R-4412-1",
"subtype": "secured",
"amount": 12000,
"vatAmount": 0,
"description": "Возврат за отменённое бронирование № 4412",
"basketItems": []
}
```
### Как это работает
1. Возврат создаётся в статусе `created`, как обычный, но в выплату не уходит.
2. Инвойсбокс выставляет магазину **обеспечительный заказ** на сумму возврата. В ответе на создание
возврата приходит его идентификатор — `securityOrderId`.
3. Магазин оплачивает обеспечительный заказ. Счёт под него не выставляется: способ оплаты магазин
выбирает на платёжной странице сам, как покупатель в обычном заказе.
4. После оплаты обеспечения возврат идёт штатным путём — `processing`, затем `completed`.
Статусы возврата при этом обычные: вид возврата виден только в `subtype`. Отдельных уведомлений
у обеспечения нет — приходят те же события, что и всегда: о создании возврата, об оплате
обеспечительного заказа и о завершении возврата.
### Что нужно знать заранее
- **Обеспечительный заказ оформлен на организацию магазина.** Плательщиком подставляются название,
ИНН и КПП вашей организации; телефон и почту вы указываете на платёжной странице — что подтвердите
там, то и попадёт в счёт. Позиция в корзине называется «Обеспечительный платёж», НДС не облагается.
- **Найти заказ по возврату и обратно** можно тремя путями: по `securityOrderId` возврата, по номеру
заказа в учётной системе (там лежит идентификатор возврата) и по артикулу позиции — он тоже равен
идентификатору возврата.
- **Пока обеспечение не оплачено, возврат можно отменить** — вместе с ним отменится и обеспечительный
заказ. После оплаты отмена запрещена: деньги уже получены, и возврат обязан доехать до выплаты.
- **Изменить сумму нельзя.** Обеспечительный заказ выставлен на исходную сумму, и правка развела бы
её с суммой возврата. По той же причине с обеспечением не сочетается статус `draft`, то есть
[корректирующие возвраты](/docs/merchant/refund/correction/).
- **Остаток по корзине** резервируется так же, как у обычного возврата.
> [!IMPORTANT]
> Возврат с обеспечением требует настройки на стороне Инвойсбокса. Если она не сделана, запрос
> создания возврата вернёт ошибку — обеспечительный заказ выставить не из чего, а возврат без него
> завис бы навсегда. Сам возврат к этому моменту уже создан: отмените его и повторите после
> настройки. Если планируете такие возвраты, договоритесь о настройке заранее.
## 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](/docs/merchant/order/create/#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` |
---
---
# Физические лица
## Покупатели - физические лица
### Процесс создания заказа и оплаты счёта
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создаёт заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Онлайн касса: Чек "предоплата 100%"
Инвойсбокс->>Покупатель: Предоставление чека "предоплата 100%"
Инвойсбокс->>Магазин: Уведомление об успешной оплате
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» формирует и регистрирует чек "предоплата 100%" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "предоплата 100%" покупателю (физическому лицу).
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа.
### Процесс отгрузки и оформления чека "полный расчёт"
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(15, 123, 119, 0.13)
Магазин->>Инвойсбокс: Вызов метода отгрузки по заказу
Инвойсбокс->>Онлайн касса: Чек "полный расчёт"
Инвойсбокс->>Покупатель: Предоставление чека "полный расчёт"
end
1. В случае, если Магазин оказывает услугу или продаёт товар, Магазин направляет запрос отгрузки в систему «Инвойсбокс» по факту оказания услуги или факту отгрузки товара курьерской службой/службе доставки или покупателю. Если услуга оказывается онлайн, отгрузка по заказу может быть установлена автоматически.
1. Система «Инвойсбокс» формирует и регистрирует чек "полный расчёт" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "полный расчёт" покупателю (физическому лицу).
### Процесс оформления возврата
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Онлайн касса: Чек "возврат"
Инвойсбокс->>Покупатель: Предоставление чека "возврат"
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин создает возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Система «Инвойсбокс» формирует и регистрирует чек "возврат" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "возврат" покупателю (физическому лицу).
## Читайте также
- [Магазин направляет запрос отгрузки через метод API](/docs/merchant/order/shipment_create/)
---
---
# Схемы взаимодействия
# Схемы взаимодействия
В зависимости от типа покупателя, схема взаимодействия системы «Инвойсбокс» и Магазина могут отличаться незначительно
в части предоставления отчётных документов. Для покупателя - [физического лица](/docs/merchant/schema/private), отчётный документ
по оплате — фискальный чек, зарегистрированный в [онлайн кассе](/docs/merchant/fz54/) и ОФД.
Для покупателя — [организации и индивидуального предпринимателя](/docs/merchant/schema/legal) отчётными документами могут быть:
акт, ТОРГ-12, накладная, счёт-фактура, отчёт о переводе средств, универсальный передаточный документ (УПД), маршрутная квитанция и
другие.
Перечень необходимых документов и порядок их предоставления покупателю (схема документооборота) согласовываются на этапе заключения
договора между Магазином и системой «Инвойсбокс».
1. [Покупатели - физические лица](/docs/merchant/schema/private)
1. [Покупатели - организации и индивидуальные предприниматели](/docs/merchant/schema/legal)
1. [Комиссионная торговля](/docs/merchant/schema/commission)
1. [Запрос о платеже](/docs/merchant/schema/rtp)
---
---
# PHP SDK
# Описание SDK
PHP SDK — готовая библиотека для серверного взаимодействия с Инвойсбокс API. Библиотека поддерживает
все необходимые методы API для организации приёма платежей.
## Требования
PHP 7.4+ (или более поздняя версия)
## Установка с помощью Composer
1. Установите Composer, менеджер пакетов
2. В консоли выполните следующую команду:
```bash
composer require invoicebox/sdk-php
```
Пропишите в файле composer.json вашего проекта:
1. Добавьте строку "invoicebox/sdk-php": "^1.0" в список зависимостей вашего проекта в файле composer.json
```json
"require": {
"php": ">=7.4",
"invoicebox/sdk-php": "^1.0"
```
2. Обновите зависимости вашего проекта. В консоли, в папке с файлом composer.json выполните следующую команду:
```bash
composer update
```
3. Подготовьте код своего проекта, чтобы активировать автоматическую загрузку зависимостей:
```php
require __DIR__ . '/vendor/autoload.php';
```
## Установка SDK вручную
1. Скачайте архив [Инвойсбокс PHP SDK](https://github.com/invoicebox/sdk-php) и распакуйте его в необходимую папку вашего проекта.
2. Подготовьте код своего проекта, чтобы активировать автоматическую загрузку зависимостей:
```php
require __DIR__ . '/vendor/autoload.php';
```
## Пример создания заказа
```php
$client = new InvoiceboxClient(
'*auth токен*',
'v3',
null,
HttpClient::create(),
);
/**
* Проверка авторизации (необязательный шаг, для тестирования наличия доступа)
*/
$result = $client->checkAuth();
if ($result->getUserId()) {
echo "Успешная авторизация \n";
}
// Покупатель юр.лицо
//$customer = new LegalCustomer(
// 'OOO TEST',
// '78121111111',
// 'test@test.test',
// '7804445210',
// '123321, Улица, 1, 1'
//);
// Покупатель физ.лицо
$customer = new PrivateCustomer(
'name',
'78121111111',
'test@test.test',
);
$basketItems[] = new BasketItem(
"12312", /* Идентификатор заказа (необходим для создания возврата) */
'Тест',
'шт.',
'796',
1.0,
1000.00,
1000,
1000.00,
0,
VatCode::VATNONE,
BasketItemType::COMMODITY,
PaymentType::FULL_PREPAYMENT
);
$request = new CreateOrderRequest(
'Описание заказа',
'ffffffff-ffff-ffff-ffff-ffffffffffff', // id магазина
strval(random_int(1,2000)),
1000.00,
0,
'RUB',
new \DateTime('tomorrow'),
$basketItems,
);
$result = $client->createOrder($request);
if ($result->getPaymentUrl()) {
echo sprintf('Заказ успешно создан - ссылка на оплату - %s', $result->getPaymentUrl());
}
/* Redirect to: $result->getPaymentUrl() */
```
## Читайте также
- [Формат уведомления и коды ответов](/docs/merchant/notification/status/)
---
---
# retailCRM
# Описание модуля retailCRM
Модуль RetailCRM предоставляет простую возможность подключить вашу CRM систему к «Инвойсбокс» для оформления счетов
клиентам.
# Установка расширения Инвойсбокс из маркетплейса
Модуль находится во вкладке настройки -> маркетплейс -> Инвойсбокс
После установки в настройках самого модуля необходимо указать апи-токен, id магазина и ключ. Все данные отправляются после заключения договора.
Нужны три значения: токен авторизации, идентификатор магазина и секретный ключ. Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
Найти актуальные данные можно [здесь](https://docs.invoicebox.ru/docs/merchant/integrationdata/)
## Выбор платёжной системы по умолчанию для retailCRM
Для удобства можно добавить платёжную системы по умолчанию для счетов. Для этого нужно перейти в "настройки -> справочники -> типы оплат -> invoicebox (invoicebox payment system)"
и включить пункт "по умолчанию в системе"
## Выставление счетов
1. Создаём новый заказ через заказы -> новый заказ
2. Указываем клиента, состав заказа, тип доставки (по необходимости)
3. Сохраняем заказ
4. Генерируем ссылку на оплату, если выбрана системы оплаты по умолчанию. Либо выбираем invoicebox (Инвойсбокс payment system) через выпадающее меню кнопки "добавить оплату"
**Обязательно нужно указать номер телефона и email. Без этих данных счёт на оплату не будет сформирован!**
**При добавлении компании ИНН обязателен!**
После оплаты заказа можно отследить его статус на вкладке заказов
---
# Создание группы заказов
# Создание группы заказов
Группа заказов от разных поставщиков с единым приёмом оплаты создаётся одним запросом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/order-container`
- тело запроса - объект [OrderContainerRequest](#ordercontainerrequest)
- тело ответа - объект [OrderContainerResponse](#ordercontainerresponse)
- Возможные [ошибки](/docs/dictionary/error/)
> > [!NOTE]
> Каждый заказ внутри группы заказов имеет базовую структуру, описанную в документации [Создание заказа](/docs/merchant/order/create/). Перед использованием данного метода рекомендуется ознакомиться с основной документацией по созданию заказа.
#### Пример запроса
``` json
POST /v3/billing/api/order/order-container
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "019e207b-b0fe-ae2f-43e7-17054f15913d",
"originalCurrencyId": "RUB",
"originalAmount": 246,
"originalVatAmount": 11.72,
"merchantOrderIdVisible": "zakaz-123",
"returnUrl": "https://marketplace.com#return",
"successUrl": "https://marketplace.com#success",
"failUrl": "https://marketplace.com#fail",
"customer": {
"vatNumber": "7736642031",
"phone": "79045173703",
"email": "gb@invbox.ru",
"taxRegistrationReasonCode": "770901001",
"name": "ООО ЮРлицо",
"registrationAddress": "101000, г. Москва, Лубянский проезд, д.19",
"isLegal": true,
"type": "legal"
},
"orders": [
{
"basketItems": [
{
"sku": "1",
"name": "Позиция заказа магазина маркетплейса",
"type": "service",
"paymentType": "full_payment",
"measureCode": "796",
"quantity": 1,
"vatCode": "RUS_VAT5",
"amount": 123,
"amountWoVat": 117.14,
"totalAmount": 123,
"totalVatAmount": 5.86
}
],
"expirationDate": "2026-05-25T17:11:28+03:00",
"merchantOrderId": "222222/333",
"description": "Оплата заказа магазина маркетплейса",
"amount": 123,
"vatAmount": 5.86,
"merchantId": "019e2094-8403-89f0-1a75-953e2103cfc2",
"currencyId": "RUB"
},
{
"basketItems": [
{
"sku": "1",
"name": "Комиссия маркетплейса",
"type": "service",
"paymentType": "full_payment",
"measureCode": "796",
"quantity": 1,
"vatCode": "RUS_VAT5",
"amount": 123,
"amountWoVat": 117.14,
"totalAmount": 123,
"totalVatAmount": 5.86
}
],
"expirationDate": "2026-05-25T17:11:28+03:00",
"merchantOrderId": "1111/2222",
"description": "Оплата заказа комиссии маркетплейса",
"amount": 123,
"vatAmount": 5.86,
"merchantId": "019e207b-b0fe-ae2f-43e7-17054f15913d",
"currencyId": "RUB"
}
]
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"originalCurrencyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"originalAmount": 100.5,
"originalVatAmount": 100.5,
"expirationDate": "2026-08-03T12:00:00+03:00",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"status": "string",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"payerUserId": "01771534-1a57-f184-dee3-ebeb91dded75",
"payerCounterpartyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"systemCounterpartyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"processable": false,
"merchantOrderIdVisible": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"sourceId": "l3"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## OrderContainerRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------------------|--------------|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор основгонго магазина (маркетплейса или агрегатора) | `019e207b-b0fe-ae2f-43e7-17054f15913d` |
| originalCurrencyId | да | string(3) enum | Код валюты группы заказов в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`, `EUR`, `GBP` |
| originalAmount | да | float | Общая сумма группы заказов | `246.00` |
| originalVatAmount | да | float | Общая сумма НДС группы заказов | `11.72` |
| orders | да | array of [Order](/docs/merchant/order/create/#createorderrequest) | Массив заказов, входящих в группу. Структура каждого заказа описана в [документации по созданию заказа](/docs/merchant/order/create/) | |
| customer | нет | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике (если не указана, плательщик сам заполнит на платежной странице) | |
| merchantOrderIdVisible | нет | string(100) | Идентификатор группового заказа, отображаемый на платежной странице | `zakaz-123` |
| returnUrl | нет | string(1000) | Ссылка для возврата на сайт Магазина | |
| successUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае успешной оплаты | |
| failUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае ошибки оплаты | |
| expirationDate | нет | datetime | Срок действия группы заказов | `2026-05-25T17:11:28+03:00` |
| languageId | нет | string(2) enum | Язык интерфейса платежной страницы | `ru`, `en` |
| invoiceSetting | нет | [InvoiceSetting](/docs/merchant/order/create/#invoicesetting) | Дополнительные настройки параметров оплаты | |
## OrderContainerResponse
Ответ содержит информацию о созданной группе заказов, включая идентификаторы созданных заказов и ссылки на оплату. Объект повторяет свойства объекта [OrderContainerRequest](#ordercontainerrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------|--------------|---------------------------------------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор группы заказов в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз для оплаты заказа | |
| createdAt | да | datetime | Дата создания заказа | `2026-12-22T00:00:00+00:00` |
| status | да | string(50) enum | Статус заказа, `pending` - Ожидает оплаты, `completed` - успешная оплата | `completed`, `pending`, |
| paidAt | нет | datetime | Дата оплаты заказа (если оплачен) | `2026-12-22T00:00:00+00:00` |
---
# Создание заказа с холдированием
# Холдирование (блокировка) средств на карте
Холдирование (предавторизация) средств на карте покупателя работает так:
1. [Создать заказ](/docs/merchant/order/create/) с подтипом `subtype` = `hold`.
В таком заказе все позиции корзины `basketItems` должны быть с типом оплаты `paymentType` равным `full_prepayment` (предоплата 100%).
2. После оплаты такого заказа, средства на карте будут заблокированы до даты, указанной в параметре `holdTill` в [ответе на запрос](/docs/merchant/order/create/#orderresponse) создания заказа.
3. До этой даты магазину нужно сообщить по API об успешной отгрузке товаров или факта оказания услуги [методом создания отгрузки](/docs/merchant/order/shipment_create).
Можно осуществить сколько угодно отгрузок с указанием позиций заказа. На каждую такую отгрузку будут оформлены отчётные документы (фискальный чек).
Как только во всех отгрузках будет указаны все позиции из заказа, то заблокированные средства на карте спишутся.
4. Так же есть возможность списать средства, оказав только часть услуг или отгрузив только часть товаров из заказа, для этого
необходимо [создать отгрузку](/docs/merchant/order/shipment_create) с флагом `final` = `true`.
После такой отгрузки заказ считается выполненным, остаток средств на карте будет разблокирован.
---
# Создание заказа агентом
# Создание заказа с использованием реквизитов продавца
При интеграции с банками и крупными платёжными агрегаторами (далее — Агент) заказ создаётся в особом режиме: идентификационные данные магазина Инвойсбокс не нужны, вместо них передаются реквизиты юрлица. Отличий два:
- ИНН и КПП вместо идентификатора магазина
- авторизационные данные агента вместо авторизационных данных магазина
Заказ в этом режиме создаётся отдельным методом:
- метод: `POST`
- ресурс: `/v3/adapter/api/subagent/order`
> [!IMPORTANT]
> Метод обслуживается отдельным модулем: его схема не входит в публикуемый набор, поэтому консоль «Выполнить» для него недоступна. Перед интеграцией сверьте контракт с технической поддержкой.
- тело запроса - объект [CreateAgentOrderRequest](#createagentorderrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/billing/api/order/order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"seller": {
"type": "counterparty",
"vatNumber": "232323232323",
"taxRegistrationReasonCode": "232323232323"
},
"merchantOrderId": "m-1608560079",
"amount": 366.00,
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"vatAmount": 66.00,
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Бронирование номера",
"measure": "шт.",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 3,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 366.00,
"totalVatAmount": 66.00,
"vatCode": "RUS_VAT22",
"type": "service",
"paymentType": "full_prepayment"
}
],
"metaData": {
"@type": "LodgingReservation",
"reservationId": "abc456",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "John Smith"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Hilton San Francisco Union Square",
"address": {
"@type": "PostalAddress",
"streetAddress": "333 O'Farrell St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"telephone": "415-771-1400"
},
"checkinTime": "2017-04-11T16:00:00-08:00",
"checkoutTime": "2017-04-13T11:00:00-08:00"
},
"expirationDate": "2026-12-22T00:00:00+00:00",
"languageId": "ru",
"currencyId": "RUB",
"description": "Оплата номера в отеле",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"vatNumber": "7701234560",
"taxRegistrationReasonCode": "770101001",
"registrationAddress": "190000, Санкт-Петербург, Невский пр. 147, офис 321"
}
}
```
Ответ:
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderId": "O-12345",
"status": "created",
"amount": 19658.45,
"vatAmount": 3276.41,
"currencyId": "RUB",
"createdAt": "2026-08-01T10:00:00+03:00",
"expirationDate": "2026-08-04T10:00:00+03:00",
"paymentUrl": "https://pay.invoicebox.ru/order/01771534-1a57-f184-dee3-ebeb91dded75"
}
}
```
## CreateAgentOrderRequest
Объект включает в себя все поля [CreateOrderRequest](/docs/merchant/order/create/#createorderrequest) а так же:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|-------------------|-----------------|-----------------------------------------------------------------------------------------------------|
| seller | да | [Seller](#seller) | Данные продавца | `{"type": "counterparty", "vatNumber":"232323232323", "taxRegistrationReasonCode": "232323232323"}` |
## Seller
Повторяет свойства объекта [CreateOrderRequest](/docs/merchant/order/create/#createorderrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|------------|--------------------------------------------------|-----------------|
| type | да | string(36) | Тип продавца, доступные значения: `counterparty` | `counterparty` |
| countryId | да | string(3) | Страна, доступные значения: `RUS` | `RUS` |
| vatNumber | да | string(20) | ИНН | `7710044140` |
| taxRegistrationReasonCode | нет для ИП | string(9) | КПП | `770201001` |
Если продавец не найден в системе Инвойсбокс, то будет возвращена ошибка.
---
# WordPress
# Описание модуля WooCommerce
Плагин WordPress для Woocommerce предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает два режима работы - с системой «Инвойсбокс» версии 2, а также с обновлённой версией 3.
Версию вашего подключения уточняйте у вашего персонального менеджера или в службе поддержки системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. Зайдите в административную часть вашего сайта, перейдите на страницу «Плагины» → «Добавить новый»;
2. В списке доступных решений найдите модуль «InvoiceBox: Payment module for WooCommerce» ([InvoiceBox, invoicebox payment](https://ru.wordpress.org/plugins/invoicebox-payment-gateway/)), установите и активируйте его.
## Настройка модуля
В административном разделе сайта перейдите на страницу «Woocommerce» → «Настройки» → «Платежи» и нажмите на кнопку «Управление» у метода Инвойсбокс Payment для физ.лиц и Инвойсбокс Legal Payment для юр.лиц.
В настройках платёжной системы настройте следующие параметры:
1. “Название” и “Описание”. Значения данных полей будут показываться клиенту при выборе способа оплаты.
2. Выберите язык, на котором будет отображаться интерфейс платёжной страницы. Также изменится логотип платежной системы на странице оформления заказа (будет написан на кириллице или латинице)
3. Выберите версию API, которая будет использоваться
4. Для проверки настроек включите тестовый режим и проведите тестовый платёж в интернет-магазине. После успешного тестирования обязательно отключите тестовый режим.
5. В выпадающем списке выберите статус "В обработке". После того, как платежная система пришлёт сообщение об успешном прохождении оплаты, статус заказа изменится на указанный в этом поле (например “в обработке” или “выполнен”)
6. Поле "Email, куда отправлять сообщения об ошибках". Заполните это поле, если хотите получать оповещения в случае возникновения ошибок.
7. Выберите ставку НДС. Обратите внимание, что если в WooCommerce выключен расчёт налогов, то НДС будет рассчитываться по выбранному в этом поле значению. Если расчёт налогов включён - значение из настроек Инвойсбокс будет игнорироваться, а расчёт будет производиться по ставкам из настроек Woocommerce.
8. В поле "Тип оплаты" выберите вариант full_prepayment (в случае, если он не выбран по умолчанию)
9. Поле "Тип товара по умолчанию": выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, дополнительный вариант можно указать ниже в графе "Мета-поле, где задан тип для отдельного товара" (см. подробнее в пункте “Настройка мета-полей”)
10. Поле “Единица измерения по умолчанию”": выберите единицу измерения, которая будет использоваться по умолчанию. Если на сайте используются разные единицы измерения, дополнительный вариант можно указать ниже в графе "Мета-поле, где задана единица измерения для отдельного товара" (см. подробнее в пункте “Настройка мета-полей”). Также дополнительно указывается код единицы измерения (если выбран русский язык - проверяется по справочнику ОКЕИ). **Примечание: для русского языка важно точное соответствие значению справочнику ОКЕИ (пример - в единице измерения “шт” не должно быть точки в конце)**.
11. Поле “Страна-производитель товара по умолчанию”: выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, дополнительный вариант можно указать ниже в графе "Мета-поле, где задана страна-производитель товара" (см. подробнее в пункте “Настройка мета-полей”).
12. Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания). Для этого нужно указать
мета-поле заказа, из которого плагин будет брать информацию. Подробнее о формате передаваемых данных написано в [разделе метаданные](/docs/merchant/order/metadata/).
Это поле должно создаваться и заполняться “на лету” из кода сразу после создания заказа перед оплатой, поэтому для его настройки может понадобиться помощь разработчика.
13. Далее нужно заполнить данные для доступа к API:
- идентификатор магазина (v2 и v3)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2 и v3)
- токен (v3).
**Имя пользователя API и пароль API направляются после активации магазина в системе Инвойсбокс на электронную почту, указанную при регистрации.
Идентификатор магазина, региональный код магазина, ключ API находятся в личном кабинете Инвойсбокс в разделе "Настройки магазина".
Для теста плагина можно воспользоваться данными специально созданных магазинов для 2й и 3й версии апи (доступы к магазинам различаются).**
## Доступы для 2й версии API
- Поле “Идентификатор магазина” - вписываем нужное значение или тестовое значение “207”, если включен тестовый режим
- Поле “Региональный код магазина” - вводим нужное значение в поле или тестовое значение “78054”, если включен тестовый режим
- Поля “Имя пользователя” и “Пароль API”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“
- Поле “Ключ API”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
- Нажимаем “Сохранить изменения”
## Доступы для 3й версии API:
- Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
- Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции. соответственно
- Нажимаем “Сохранить изменения”
**Вы сможете отслеживать ошибки, включив функцию логирования. Данные об операциях и ошибках вносятся в логи WooCommerce (меню - WooCommerce - Статус - Журналы)**
**Чтобы настроить приём платежей от юридических лиц, повторите все шаги для способа оплаты Инвойсбокс Legal Payment**
Зайдите в свой личный кабинет на Инвойсбокс и в разделе “Мои магазины - Настройки - Интеграция API - URL уведомления” заполните настройки:
- Тип уведомления: Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных);
- URL уведомления: https://ВАШ_ДОМЕН/wc-api/wc_invoicebox_gateway
> [!WARNING]
> URL уведомления должен работать только по HTTPS: уведомления об оплате содержат данные заказов и подпись запроса.
## Настройка мета-полей
Мета-поле используется для установки дополнительных параметров товара (страна-производитель, единица измерения и тип товара и т.д.)
Возможно, сайт уже настроен таким образом, что эти поля в товарах есть (их добавляют некоторые плагины, либо это может быть дописанный код в теме). Об их наличии и том, какие значения записать в настройки плагина Инвойсбокс, можно уточнить у разработчиков сайта.
Если нужные поля отсутствуют, их можно создать самостоятельно с помощью плагина Advanced Custom Fields :
Далее в инструкции показано, как настроить рекомендуемые к заполнению поля. Обо всех остальных возможностях плагина вы можете прочесть в документации по ссылке [advanced custom fields](https://www.advancedcustomfields.com/resources/)
1. Установите и активируйте плагин Advanced Custom Fields [advanced custom fields](https://ru.wordpress.org/plugins/advanced-custom-fields/)
2. В меню выберите пункт “Добавить группу полей”
3. Добавьте новое поле
4. Произвольно назовите группу полей, а в условиях отображения выберите “Тип записи - равно - Товар”
В строке "Имя поля" - введите значение предыдущей строки латиницей (обязательно!). В строке "Тип поля" в выпадающем списке выберите "Текст"
5. Чтобы создать мета-поле "Тип товара", добавьте новое поле, заполните ярлык и имя, а в типе поля выберите “Выбор (select)”..
- Далее скопируйте и вставьте в пункт “Варианты” следующий текст:
- commodity : товар
- service : услуга
6. Сохраните группу полей.
7. Перейдите в любой товар в административной панели и убедитесь, что на странице товара появилась вкладка с новыми полями.
8. Впишите идентификаторы, которые вы задавали в “имени поля” на странице настроек плагина и сохраните настройки.
## Частые вопросы
1. Что такое мета-поле?
Мета-поля WordPress (произвольные поля) – это метаданные, которые используются для добавления дополнительной информации, относящихся к редактируемой записи, странице или товару.
2. Нужны ли какие-то дополнительные плагины для работы плагина Инвойсбокс?
Да. Для работы требуется плагин [WooCommerce](https://ru.wordpress.org/plugins/woocommerce/). Так же для настройки передачи дополнительных данных в платёжную систему может понадобиться плагин [advanced custom fields](https://ru.wordpress.org/plugins/advanced-custom-fields/)/ (см. подробности в пункте “Настройка мета-полей”).
3. Можно ли изменить время на оплату счёта?
Да. В настройках платёжной системы есть параметры для изменения времени на оплату
---
[Проект на github](https://github.com/InvoiceBox/WooCommerce-2)
---
# SportCRM
# Описание модуля SportCRM
[SportCRM](https://sportcrm.club) — это облачная система для организации и контроля тренировочных и соревновательных процессов
в спортивных клубах. Помогает контролировать работу администраторов, тренеров и партнёров по франшизе. Модуль Инвойсбокс
предоставляет простую возможность приёма оплаты для спортивных клубов и полное соответствие ФЗ-54 без лишних хлопот.
## Настройка модуля
Зайдите в SportCRM в раздел Управление > Настройки > Филиалы.
В выпадающем окне выберите Инвойсбокс
Укажите в настройках Идентификатор Магазина (v2), Региональный код, API ключ, которые можно получить в [личном кабинете Инвойсбокс](https://business.invoicebox.ru).
Также пропишите URL уведомления, которые сгенерирует SportCRM. Тип уведомления надо выбрать Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных).
## Читайте также
- [Онлайн касса (ФЗ-54)](/docs/merchant/fz54/)
---
# Bnovo
# Описание модуля Bnovo
Bnovo - система управления для гостиничного бизнеса. Модуль Инвойсбокс для Bnovo предоставляет
простую возможность отелям и иным участникам гостиничного бизнеса организации приёма оплаты как
от организаций и индивидуальных предпринимателей, так и от частных лиц за бронироания.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Настройка модуля
1. Зайдите в Bnovo в раздел Меню **бургер > Bnovo Финансы > Настройки > Прием онлайн-оплаты > Добавить шлюз** и
заполните заявку на подключение.
2. После настройки шлюза с стороны Bnovo, дождитесь письмо на электронную почту, что шлюз подключен.
3. После настройки шлюза совершите тестовое бронирование с платежом.
---
# Проверка возможности оплаты
# Проверка возможности подтверждения оплаты
Проверка, можно ли подтверждать оплату, — отдельный вызов:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/validate`
- тело запроса - объект [ValidateRequest](#validaterequest)
- тело ответа - объект [ValidateResponse](#validateresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/validate
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "available",
"resultData": {
"url": "",
"method": "POST",
"arguments": []
}
}
}
```
## ValidateRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
## ValidateResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/validate/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|-----------------------------|
| result | да | enum | Статус проверки (см. ниже) |
| resultNote | нет | string | Комментарий |
Возможные статусы:
- notRegistered - Организация или ИП не зарегистрировано в системе
- notEnoughMoney - Недостаточно средств для подтверждения оплаты заказа
- available - Подтверждение оплаты заказа доступно
---
---
# Услуга не может быть оказана
# Услуга не может быть оказана или товар не может быть доставлен
Как правило, система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта асинхронно от действий
покупателя на платёжной странице. Т.е. покупатель подтверждает оплату заказа в интерфейсе «Инвойсбокс»,
возвращается на страницу магазина, а уведомление об оплате счёта асинхронно передаётся системой
«Инвойсбокс» в магазин по API.
В некоторых сценариях, требуется контролировать факт успешной доставки уведомления об оплате до
Магазина и уведомлять покупателя о таком процессе. Например, по факту оплаты требуется подтвердить
наличие товара на складе и зарезервировать его, или же, по факту оплаты требуется забронировать
места/номера/время и оформить билет. Такие сценарии как правило используются совместно с
гарантийными оплатами (предавторизация денежных средств на банковской карте или использование
гарантийного фонда до момента подтверждения возможности оказания услуги и дальнейшее списание
средств или отмена).
> [!IMPORTANT]
> Использование сценария требует включения настройки платёжной страницы Магазина "Контроль отгрузки на
> платёжной странице". В случае, если у вас возникнут сложности при самостоятельной настройке,
> пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Пример сценария
Покупатель подтверждает оплату счёта на [платёжной странице](/docs/merchant/payment-page/). Платёжная страница
отображает покупателю загрузчик (лоадер ⌛). Система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта и ожидает
ответ.
Система Магазина выполняет свою логику по резервированию товара или бронированию услуги.
### ✅ Позитивный сценарий
Система Магазина успешно резервирует товар или бронирует услугу. В этом случае, в ответ на запрос
«Инвойсбокс», система Магазина возвращает статус `success`.
Покупателю на платёжной странице отображается информация об успешном подтверждении оплаты, покупатель
перенаправляется в Магазин на страницу успешной оплаты заказа.
### ❌ Негативный сценарий
При попытке резервирования товара или бронирования услуги, система Магазина получает ошибку. В
этом случае, в ответ на запрос «Инвойсбокс», система Магазина возвращает статус `error` с кодом
`shipping_unavailable` (Услуга не может быть оказана или товар не может быть доставлен).
Покупателю на платёжной странице отображается информация о невозможности оказания услуги, а также
дальнейшие инструкции о том, как и когда платёж будет отменён. Покупатель перенаправляется в Магазин
на страницу ошибки при оплате заказа.
### Отмена оплаты и возврат денежных средств
Обратите внимание, негативный ответ на уведомление об оплате счёта, не инициирует процессы возврата.
Магазин должен самостоятельно инициировать процессы возврата в случае невозможности поставки товара
или оказания услуги. Если требуется формирование автоматического возврата/разблокирования средств, необходимо
вместо `shipping_unavailable` использовать код `full_refund_required`
В случае, если оплата заказа была подтверждена с использованием гарантийного платежа, Магазин может
вызвать [метод отмены заказа](/docs/merchant/order/delete/) для полного возврата средств покупателю
(отмены гарантийной оплаты, reverse).
В случае, если оплата заказа была подтверждена с использованием иных платёжных инструментов, Магазин
может вызвать [метод возврата по заказу](/docs/merchant/refund) для полного или частичного возврата
средств покупателю.
---
---
# ТАИС (TravelShop)
# Описание интеграции ТАИС (TravelShop)
[TravelShop](https://ors.aero/travelshop) — это гибкий модуль онлайн-продаж авиационного контента для онлайн-трэвел
агентств и авиакомпаний. Модуль настраивается под особенности вашего бизнеса: сценарии продажи,
оформление и правила работы с клиентами задаются на вашей стороне.
## Решения на базе интеграции
- [Автоматизация продаж авиабилетов юридическим лицам и ИП (b2b)](/docs/scenarios/air-carriers).
## Настройка интеграции
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# Получение возвратов
# Получение списка возвратов
Возвраты читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/filter/api/order/refund-order`
- тело ответа - коллекция объектов [RefundOrderResponse](/docs/merchant/refund/create/#refundorderresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
Пример запроса с фильтром по идентификатору возврата
```http
GET /v3/filter/api/order/refund-order?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по идентификатору заказа (по которому оформлялся возврат)
```http
GET /v3/filter/api/order/refund-order?parentId=d6f1ccb2-2e32-43c2-8a42-5a835dd88607
```
Пример запроса возвратов с фильтром по [статусу](/docs/merchant/refund)
```http
GET /v3/filter/api/order/refund-order?status=completed
```
Пример запроса возвратов с фильтром по идентификатору магазина
```http
GET /v3/filter/api/order/refund-order?merchantId=2ce417f1-8702-4517-bb56-11cd305d2594
```
Пример запроса возвратов с фильтром по идентификатору заказа в учётной системе магазина
```http
GET /v3/filter/api/order/refund-order?merchantOrderId=ORD123456
```
---
#### Пример запроса и ответа
``` json
GET /v3/filter/api/order/refund-order?status=completed
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ (по схеме):
``` json
{
"data": [
{
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
],
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
---
# Организации и ИП
## Покупатели - организации и индивидуальные предприниматели
### Процесс создания заказа и оплаты счёта
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создаёт заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа.
### Процесс отгрузки и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(15, 123, 119, 0.13)
Магазин->>Инвойсбокс: Вызов метода отгрузки по заказу
Инвойсбокс->>Покупатель: Предоставление отчётных документов
Магазин-->>Покупатель: Предоставление отчётных документов (если требуется)
end
1. В случае, если Магазин оказывает услугу или продаёт товар, Магазин направляет запрос отгрузки в систему «Инвойсбокс» по факту оказания услуги или факту отгрузки товара курьерской службой/службе доставки или покупателю. Если услуга оказывается онлайн, отгрузка по заказу может быть установлена автоматически.
1. Система «Инвойсбокс» формирует отчёт о переводе средств, а также дополнительный набор отчётных документов по доверенности от магазина, если требуется. При оказании услуг формируется акт, при продаже товаров - формируется ТОРГ-12. Система «Инвойсбокс» направляет пакет отчётных документов покупателю по электронной почте, оригиналы по почте и с помощью ЭДО.
1. Магазин направляет покупателю пакет отчётных документов, если это предусмотрено процессом.
### Процесс оформления возврата
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Покупатель: Предоставление отчётных документов
Магазин-->>Покупатель: Предоставление отчётных документов (если требуется)
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин создает возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Система «Инвойсбокс» формирует набор отчётных документов по доверенности от магазина, если требуется (например, при [комиссионной торговле](/docs/merchant/schema/commission/)). При оказании услуг формируется акт, при продаже товаров - формируется ТОРГ-12. Система «Инвойсбокс» направляет пакет отчётных документов покупателю по электронной почте, оригиналы по почте и с помощью ЭДО.
1. Магазин направляет покупателю пакет отчётных документов, если это предусмотрено процессом.
---
---
# Отмена возврата
# Отмена возврата
Возврат в статусе `created` (создан) можно отменить:
- метод: `DELETE`
- ресурс: `/v3/billing/api/order/refund-order/:uuid` - где `:uuid` это идентификатор возврата
- тело запроса - отсутствует
- тело ответа — пустой ответ (HTTP 200); статус возврата меняется на `cancel`
#### Пример запроса и ответа
#### 🌐 HTTP
```http
DELETE /v3/billing/api/order/refund-order/c5041a79-24a6-42d1-b0ce-4abb94982cd9
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X DELETE '{baseUrl}/v3/billing/api/order/refund-order/c5041a79-24a6-42d1-b0ce-4abb94982cd9' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
{baseUrl} - [базовый URL](/docs/api)
В зависимости от сценария использования и настроек магазина, может быть применена разная логика при вызове метода.
По умолчанию, отменить возврат возможно только в статусах `draft` (черновик) или `created` (создан).
---
Ответ: HTTP 200 с пустым телом. Отмена состоялась, если статус возврата
сменился на `cancel` — его видно [методом получения возврата](/docs/merchant/refund/get/).
---
# Документооборот
# Документооборот
Вторая половина работы Инвойсбокса: принять оплату мало, корпоративному покупателю нужны документы.
Их формирует и отправляет Инвойсбокс — магазину не нужен свой оператор ЭДО и не нужно собирать
комплекты вручную.
## Какие документы формируются
| Документ | Когда появляется | Кому нужен |
|---|---|---|
| Счёт на оплату | сразу после [создания заказа](/docs/merchant/order/create/) | покупателю, чтобы провести платёж через банк |
| Фискальный чек | в момент оплаты, регистрируется в [онлайн-кассе](/docs/merchant/fz54/) | покупателю-физлицу, по 54-ФЗ |
| Акт или ТОРГ-12 | после оплаты и подтверждения отгрузки | бухгалтерии покупателя-организации |
| Счёт-фактура | после оплаты, если продавец на общей системе налогообложения | для вычета НДС |
| УПД | вместо связки «акт + счёт-фактура», если так удобнее сторонам | бухгалтерии обеих сторон |
Состав комплекта зависит от схемы работы: см. [схемы документооборота](/docs/merchant/schema/) —
[с юрлицами](/docs/merchant/schema/legal/), [с физлицами](/docs/merchant/schema/private/)
и [с комиссией](/docs/merchant/schema/commission/).
## Что запускает формирование
Документы привязаны к событиям заказа, а не к календарю:
1. Заказ создан — формируется счёт.
2. Оплата подтверждена — регистрируется чек, магазину уходит
[уведомление о смене статуса](/docs/merchant/notification/status/).
3. Отгрузка подтверждена — формируются акт или накладная. Если отгрузка идёт частями, документ
создаётся на каждую [отгрузку](/docs/merchant/order/shipment_create/).
4. Возврат оформлен — формируются корректирующие документы; при удержании части суммы
используйте [возврат с корректировкой](/docs/merchant/refund/correction/).
О движении документов в ЭДО магазин узнаёт из [событий ЭДО](/docs/merchant/documentflow/edo_events/):
документ отправлен, получен, подписан, отклонён.
## Как покупатель получает документы
Способ выбирает сам покупатель — магазину для этого ничего делать не нужно.
| Путь | Когда срабатывает |
|---|---|
| Автоматически по ЭДО | покупатель заранее настроил обмен с Инвойсбоксом и запросил документы для себя на [платёжной странице](/docs/merchant/payment-page/) — комплект уходит сразу после оплаты |
| По ссылке из письма | после оплаты покупателю приходит письмо со ссылкой на сервис запроса документов: там он выбирает электронные файлы, бумажные оригиналы почтой или обмен по ЭДО |
| Из личного кабинета | покупатель заходит в кабинет Инвойсбокса и запрашивает комплект в любом виде в любой момент |
Магазин видит документы покупателя в информации о своём заказе — отдельно запрашивать
их не нужно.
**Когда документы становятся доступны.** По умолчанию — после оплаты заказа. Но момент
зависит от схемы документооборота: что продаётся и на каких условиях. Например, документы
на товары могут появляться после отгрузки покупателю или выполнения других условий
договора — см. [схемы документооборота](/docs/merchant/schema/).
## Кто подписывает и куда уходит
Документы подписываются электронной подписью Инвойсбокса как оператора расчётов и уходят
покупателю через его оператора ЭДО. Оператор определяется по реквизитам организации; если у покупателя
ЭДО нет, документы доступны в личном кабинете и отправляются на почту.
## Что дальше
- [События ЭДО](/docs/merchant/documentflow/edo_events/) — как получать статусы документов в свою систему.
- [Сроки и условия](/docs/terms/) — когда документы формируются и когда приходят деньги.
- [Схемы документооборота](/docs/merchant/schema/) — какой комплект получается в вашей схеме.
---
---
# События документооборота
### Обработка событий документооборота
---
В жизненном цикле документооборота по заказу возникают события, которые необходимо обрабатывать магазином (например: расхождения данных, подписание или отклонение документов).
Такие события отправляются в формате JSON на `URL`, предоставленный магазином.
---
### **Формат объекта события**
Каждое событие содержит общую структуру:
```json
{
"eventName": "название_события",
"eventData": { ... } // Данные, специфичные для типа события
}
```
| Поле | Тип | Обязательность | Описание |
|---------------|---------|----------------|-------------------------------------------------|
| `eventName` | string | Да | Тип события (см. ниже возможные значения). |
| `eventData` | object | Да | Объект с данными, зависящими от типа события. |
---
### **Типы событий**
---
#### **1. Документ подписан (`document_signed`)**
Уведомление о успешном подписании документа (например, счета или акта).
**Структура `eventData`:**
```json
{
"documentType": "invoice",
"documentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```
| Поле | Тип | Обязательность | Описание | Пример значения |
|-----------------|---------|----------------|-------------------------------------------|------------------------------------------|
| `documentType` | string | Да | Тип документа: `invoice`, `act`, `order`. | `"invoice"` |
| `documentId` | string | Да | UUID документа. | `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` |
---
#### **2. Документ отклонен (`document_rejected`)**
Уведомление об отклонении документа (например, из-за ошибок или несогласия сторон).
**Структура `eventData`:**
```json
{
"documentType": "invoice",
"documentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
}
```
| Поле | Тип | Обязательность | Описание | Пример значения |
|-----------------|---------|----------------|-------------------------------------------|------------------------------------------|
| `documentType` | string | Да | Тип документа: `invoice`, `act`, `order`. | `"invoice"` |
| `documentId` | string | Да | UUID документа. | `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` |
| `rejectReason` | string | Да | Причина отклонения. | `"Несоответствие данных в счете"` |
---
#### **3. Расхождение данных (`data_mismatch`)**
Уведомление о несоответствии данных между заказом/отгрузкой и документом ЭДО.
**Структура `eventData`:**
```json
{
"sourceType": "shipment",
"sourceId": "550e8400-e29b-41d4-a716-446655440000",
"compareType": "edo",
"compareId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "mismatch",
"details": [
{
"type": "value",
"field": "quantity",
"sku": "product_123",
"sourceValue": 2,
"compareValue": 3
}
]
}
```
| Поле | Тип | Обязательность | Описание |
|------------------|---------|----------------|-------------------------------------------------------------------------|
| `sourceType` | string | Да | Тип источника: `order`, `shipment`, `refund`. |
| `sourceId` | string | Да | UUID источника (например, отгрузки). |
| `compareType` | string | Да | Тип сравнения: только `edo`. |
| `compareId` | string | Да | UUID документа ЭДО. |
| `status` | string | Да | Статус: только `mismatch`. |
| `details` | array | Да | Массив расхождений (см. таблицу ниже). |
**Поля объектов в массиве `details`:**
| Поле | Тип | Обязательность | Описание |
|------------------|---------|----------------|-------------------------------------------------------------------------|
| `type` | string | Да | Тип расхождения: `value`, `missing`, `extra`. |
| `field` | string | Условно | Поле (для `type: value`): `quantity`, `price`, `vatRate`. |
| `sku` | string | Да | SKU товара. |
| `sourceValue` | number | Условно | Значение из источника (для `type: value`). |
| `compareValue` | number | Условно | Значение из ЭДО (для `type: value`). |
---
### **Пример полного события**
```json
{
"eventName": "data_mismatch",
"eventData": {
"sourceType": "shipment",
"sourceId": "550e8400-e29b-41d4-a716-446655440000",
"compareType": "edo",
"compareId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "mismatch",
"details": [
{
"type": "missing",
"sku": "product_456",
"sourceValue": null,
"compareValue": null
}
]
}
}
```
---
# OpenCart 2.x
# Описание модуля OpenCart 2.x
[OpenCart](https://www.opencart.com/) — платформа электронной коммерции, ориентированная на создание интернет-магазинов.
Бесплатное свободное программное обеспечение, поддерживаются дополнения - модули и шаблоны.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки и настройки платёжного модуля Инвойсбокс:
1. Пройдите по ссылке к плагину на сайте OpenCart. [OpenCart - Платёжный модуль Инвойсбокс](https://www.opencart.com/index.php?route=marketplace/extension/info&member_token=5a2149467743eb9a98246d974109dc4c&extension_id=43952)
2. Авторизуйтесь или зарегистрируйте новый аккаунт. Это нужно для скачивания плагина.
3. Скачайте архив с плагином.
**Важно: название архива с модулем должно заканчиваться на .ocmod.zip.**
**Важно: сайт должен работать на версии php не менее 7.3.**
4. В административной панели зайдите в раздел Настройки - Управление магазином - FTP и заполните данные для ftp-доступа к сайту.
5. В административной панели зайдите в раздел Модули/Расширения → Установка расширений и загрузите файл install.ocmod.zip.
6. Перейдите в раздел Модули/Расширения → Модификаторы. Очистите и обновите кэш модификаторов, нажав на соответствующие кнопки в правом верхнем углу экрана.
7. Заходим в раздел Модули/расширения → Модули/расширения.
8. Открываем селект и выбираем Оплата.
9. Находим Инвойсбокс и нажимаем на кнопку “активировать”.
## Настройка модуля
1. Зайдите в раздел Модули/расширения → Модули/расширения.
2. В выпадающем списке выберете "Оплата".
3. Найдите модуль “Инвойсбокс” и перейдите в редактирование.
4. Перейдите в раздел "настройка платежей". Выберите версию API, заполните необходимые данные:
- идентификатор магазина (v2, v3 новая и v3 текущая)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2, v3 новая и v3 текущая)
- токен (v3 новая и v3 текущая)
В пункте 5 будут даны тестовые данные для 2й версии, а в пункте 6 - для 3й версии (новой), для получения данных для 3 версии текущего АПИ рекомендуется написать на почту [c-support@invoicebox.ru](mailto:c-support@invoicebox.ru).
5. Доступы для 2й версии API:
- Поле “Магазин” - вставьте нужное или тестовое значение “207” (если включен тестовый режим)
- Поле “Региональный код магазина” - введите нужное или тестовое значение “78054” (если включен тестовый режим)
- Заполните поля “Имя пользователя” и “Пароль”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“.
- Поле “Ключ”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC.
- Нажмите кнопку “Сохранить” в правом верхнем углу экрана
- 
6. Доступы для 3й версии API:
- Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
- Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции.
- Нажмите кнопку “Сохранить” в правом верхнем углу экрана
7. Выберите налоговый режим, в котором работает магазин. См. раздел “настройка налогового режима”.
8. Убедитесь, что заполнены значения полей “Единица измерения” и “Код единицы измерения”. Стандартные значения “шт” и “796”. Индивидуальные значения для каждого товара задаются в атрибутах товара.
9. Если нужно допускать заказ к оплате только после проверки модератором, выберите режим отложенной оплаты и статус, при переводе заказ в который, пользователю будет посылаться ссылка на оплату. Подробнее - в разделе “Специфические настройки”.
10. Заполните значения полей SKU в товарах. Если они будут не заполнены, оплату за товар нельзя будет вернуть. Для этого:
1. Зайдите в раздел Каталог → Товары и нажмите на редактирование товара.
2. Далее зайдите в раздел “Данные” и нажмите кнопку справа “двойная стрелка”.
3. Найдите поле “Артикул” и при отсутствии актуальных артикулов заполните строку любыми числами. Главное, чтобы у каждого товара был свой уникальный артикул.
11. Значения остальных полей описано в разделе “Специфические настройки”.
12. Не забудьте в настройках модуля поставить статус “включено”.
При оформлении заказа обязательно нужно добавить корректный номер телефона.
Возникшую при оплате ошибку можно узнать в истории заказа в админ-панели.
Настройка налогового режима
В налогах важны три пункта:
показываются они клиенту или нет
ставка НДС
формат цен
Формат цен задается в “Система - Локализация - Валюта”. Для каждой валюты проставьте в поле “количество знаков после запятой” значение 2.
Ставка НДС задаётся в меню “Система - Локализация - Налоги - Налоговые ставки”.
Допускаются ставки НДС 0%, 10%, 20%. В типе нужно выставить “процент”, а в “ставке” - нужное число.
Показ налогов настраивается в 3х местах: в модуле “Инвойсбокс”, в настройках, в модуле “Учитывать в заказе”.
Корректными являются такие варианты:
1. Налоги уже учтены в стоимости и не показываются клиенту.
- Модуль “Инвойсбокс”:
- “Система - Настройки - Опции”:
- Модули/расширения - Учитывать в заказе/Всего заказов-Отчеты - Налоги / Налоговый отчет:
2. Налоги считаются поверх указанной стоимости товара и показываются клиенту:
- Модуль “Инвойсбокс”:
- Система - Настройки - Опции:
- Модули/расширения - Учитывать в заказе - Налоги:
### Обновление модуля
При обновлении модуля необходимо в начале удалить модификатор модуля
И очистить кеш
После этого провести ту же процедуру, что и при первой установке модуля
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале «Инвойсбокс», но деньги с вашей карты списаны не будут.
Статус заказа после оплаты - после успешной оплаты заказа, заказу будет установлен выбранный статус.
Статус заказа после подтверждения - при нажатии на кнопку "Подтвердить" на последнем этапе оформления заказа, заказу будет установлен выбранный статус.
Статус заказа после неудачной оплаты - Если «Инвойсбокс» вернёт покупателя после неудачного платежа, заказу будет установлен выбранный статус.
Статус заказа для отсроченной оплаты - после проверки заказа менеджер магазина выставит этот статус, покупатель будет уведомлен по электронной почте и сможет оплатить заказ. Также, ссылка на оплату появится в личном кабинете покупателя в разделе "Мои заказы".
**БУДЬТЕ ВНИМАТЕЛЬНЫ!** Если этот статус совпадёт со "статус заказа после подтверждения" - режим отсроченной оплаты будет отключён и покупатели будут перенаправляться на сайт «Инвойсбокс» для оплаты сразу после нажатия на кнопку "Оформить заказ".
Режим отсроченной оплаты - при включённом режиме отсроченной (отложенной) оплаты покупатель сможет оплатить заказ только после проверки заказа менеджером магазина. Если вам необходимо, чтобы у покупателя была возможность произвести оплату сразу после оформления заказа без подтверждения менеджером - не включайте эту опцию.
Название - Название метода оплаты на странице оформления заказа.
Инструкция по оплате - выводится при подтверждении заказа. Если поле не заполнено - инструкция выводиться не будет.
В поле "Тип оплаты" выберите вариант full_prepayment (если он не выбран по умолчанию).
Поле "Тип товара по умолчанию"- выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, у каждого товара свой тип можно задать в атрибутах.
Поля “Страна-производитель товара по умолчанию” и “Код страны-производителя товара по умолчанию” : выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, у каждого товара свою страну можно задать в атрибутах.
Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания).
Для передачи этих данных понадобится помощь разработчика. Сохранять информацию нужно в таблицу `oc_invoicebox_meta`. Подробнее о формате
передаваемых данных можете узнать в [разделе метаданные](/docs/merchant/order/metadata/).
Причины возникновения ошибок при загрузке:
Проверьте, оканчивается ли архив с модулем на “.ocmod.zip”
Проверьте версию php на сайте. Версия должна быть не менее 7.3.
Причины возникновения ошибок при оплате:
Если при оплате возникает ошибка, в первую очередь стоит зайти в административную панель, в раздел заказов и открыть новый заказ. Чаще всего причина будет указана там.
Проверьте, корректно ли указаны единицы измерения. Они должны быть указаны либо в каждом товаре, либо в настройках модуля (если в товаре нужных атрибутов нет, значения берутся из модуля). Частая ошибка - “шт.” вместо “шт”. Код для “шт” - 796.
Проверьте, корректно ли в товарах указан тип товара в самом товаре. Допустимые значения “commodity” и “service”. Либо оставьте поле пустым, чтобы значение бралось из настроек модуля.
Проверьте, правильно ли выставлены настройки налогов. См. раздел “настройка налогового режима”.
Проверьте, корректно ли заполнены доступы от API.
Проверьте, не включена ли опция “тестовое окружение”, если для магазина в Инвойсбокс не создавалось тестовое окружение. Если вы используете тестовые данные доступа из этой инструкции, настройка “тестовое окружение” должна быть отключена.
Проверьте в настройках модуля, включен ли он.
Если включен режим отложенной оплаты, убедитесь, что статус заказа для отсроченной оплаты не совпадает со статусом заказа после подтверждения.
Причины возникновения ошибок при возврате:
Если при оплате возникает ошибка, в первую очередь стоит посмотреть в истории заказа - иногда точная ошибка может быть указана там.
Проверьте, что используется та же версия API, что и при оплате заказа (нельзя переключаться со 2й на 3ю и наоборот).
Убедитесь, что общая сумма возврата не превышает допустимую для этого заказа (если по этому заказу уже был возврат, остаток будет указан в предупреждении на странице возврата).
Убедитесь, что сумма возврата по каждому товару не больше суммы оплаты по этому товару.
Убедитесь, что у каждого товара заполнено поле SKU (Артикул) - с пустым полем сделать возврат для товара нельзя.
#### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Часто задаваемые вопросы:
Вопрос: При выборе способа оплаты, заказ исчезает из панели управления магазином, даже если клиент его оплатил
Ответ: Проверьте корректность указания ссылка уведомления об оплате в личном кабинете системы Инвойсбокс. Заказ отображается в панели управления магазином только в том случае, если система оплаты корректно передала магазину информацию об оплате заказа.
---
# Запрос кода подтверждения
# Запрос кода подтверждения
Код подтверждения запрашивается и уходит покупателю одним вызовом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/send-code`
- тело запроса - объект [CodeRequest](#coderequest)
- тело ответа - объект [CodeResponse](#coderesponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/send-code
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "success",
"resultData": {
"publicCode": "aaaaaaa123",
"leftAttempt" : 5
}
}
}
```
## CodeRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
## CodeResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/code/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|----------------------------------------------|
| type | да | enum | Тип действия: none |
| result | да | enum | Статус проверки (см. ниже) |
| resultData | да | object | [Code](/docs/merchant/guarantee/code/#code) |
Возможные статусы:
- error - ошибка
- codeAlreadySent - код уже был отправлен ранее, срок повторной отправки кода не истёк
- success - успешно
## Code
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|---------------------------------------------|
| publicCode | да | string | Публичный идентификатор кода |
| leftAttempt | да | int | Количество оставшихся попыток отправки кода |
---
---
# Не процессинговые заказы
# Не процессинговые заказы
Заказ считается не процессинговым, если:
- При создании заказа был указан флан `processable` в значении `false`
- Если отсутствует действующий договор с магазином
Если при создании заказ помечен процессинговым, но действующего контракта с магазином нет,
то заказ становится не процессинговым. По не процессинговым заказам не происходит движения денежных средств
в рамках биллинга.
У не процессинговых заказов имеется возможность [смены статуса](/docs/merchant/order/order-status-update/).
## Возможные статусы заказа
1. `created` - Заказ создан, но еще не оплачен
2. `completed` - Заказ оплачен
3. `expired` — срок действия заказа истёк: указанное в `expirationDate` время уже прошло. Оплатить по прежней ссылке нельзя, нужен новый заказ
4. `canceled` - Заказ отменён магазином до его оплаты
---
---
# Работа с заказом
# Работа с заказом
Заказ — основной объект при работе Магазина с системой «Инвойсбокс».
Текущий раздел описывает возможные манипуляции с заказом.
## Возможные статусы заказа
Заказ живёт по одной схеме независимо от способа оплаты: из `created` он уходит либо в оплату, либо в
`expired` по сроку, либо в `canceled` по решению магазина. Холдирование добавляет промежуточное
состояние.
```mermaid
stateDiagram-v2
[*] --> created: создание заказа
created --> completed: оплата
created --> hold: оплата с холдированием
hold --> completed: отгрузка закрыла все позиции
hold --> canceled: отмена, резерв снят
created --> expired: истёк expirationDate
created --> canceled: отмена магазином
completed --> completed: возврат оформляется отдельным заказом
```
Возврат не меняет статус исходного заказа: он создаётся
[отдельной операцией](/docs/merchant/refund/create/) со своим жизненным циклом.
1. `created` - Заказ создан, но еще не оплачен
2. `hold` - По заказу удержаны (захолдированы) денежные средства до момента списания или отмены холда
3. `completed` - Заказ оплачен
4. `expired` — срок действия заказа истёк: указанное в `expirationDate` время уже прошло. Оплатить по прежней ссылке нельзя, нужен новый заказ
5. `canceled` - Заказ отменён магазином до его оплаты
---
# Возврат с комиссией/штрафом
# Возврат с комиссией/штрафом
Иногда при возврате нужно удержать штраф, комиссию за возврат или сервисный сбор — и провести удержание в финансовой отчётности.
Такой возврат происходит в два этапа через корректировочный заказ на комиссию, штраф или сервисный сбор:
- [Формирование возврата](#формирование-возврата)
- [Формирование корректировочного заказа](#формирование-корректировочного-заказа)
Сумма возврата из первого шага пересчитывается на сумму корректировочного заказа — её и получает покупатель.
### Процесс оформления возврата через корректировочный заказ
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Магазин->>Инвойсбокс: Вызов метода создания корректировочного заказа
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Онлайн касса: Чек "ВОЗВРАТ 100%"
Инвойсбокс->>Покупатель: Предоставление чека "ВОЗВРАТ 100%"
Инвойсбокс->>Онлайн касса: Чек "ОПЛАТА 100%" по корректировочному заказу
Инвойсбокс->>Покупатель: Предоставление чека "ОПЛАТА 100%"
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин формирует возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Магазин формирует корректировочный заказ в системе «Инвойсбокс» с указанием позиции комиссии, штрафа или сервисного сбора [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю на сумму возврата за минусом суммы корректировочного заказа.
1. Система «Инвойсбокс» формирует и регистрирует чек "ВОЗВРАТ 100%" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "ВОЗВРАТ 100%" покупателю (физическому лицу).
1. Система «Инвойсбокс» формирует и регистрирует чек "ОПЛАТА 100%" по корректировочному заказу в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "ОПЛАТА 100%" покупателю (физическому лицу).
### Формирование возврата
Сформируйте возврат со специальным статусом **draft** и получите его **идентификатор** (id) через метод API [создания возврата](/docs/merchant/refund/create/)
### Формирование корректировочного заказа
Сформируйте корректировочный заказ с указанием новых позиций (штрафов, комиссий, сервисных сборов) со ссылкой на возврат из пункта 1. через поле `parentId`,
т.е. укажите в поле `parentId` полученный идентификатор `id` возврата.
Корректировочный заказ создаётся своим методом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/correction-order`
- тело запроса — объект CorrectionOrderRequest: `parentId`, `amount`, `vatAmount`, `description`, `basketItems` (все обязательные)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
- Возможные [ошибки](/docs/dictionary/error/)
---
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/correction-order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
---
# Комиссионная торговля
## Комиссионная торговля
Магазин может продавать товары не напрямую покупателю, а через Инвойсбокс. Порядок действий и перечень документов
зависят от систем налогообложения, которые применяют собственник товара (комитент) и Инвойсбокс (комиссионер).
По договору комиссии:
1. Собственник товара — это комитент.
2. Инвойсбокс — это комиссионер.
Комиссионер (Инвойсбокс) продаёт товары от своего имени или от имени комитента (магазина). При этом комитент и
комиссионер могут использовать разные налоговые режимы — общий (ОСНО) или упрощённый (УСН).
Предлагаем изучить схему взаимодействия и документооборота в рамках комиссионной торговли для клиентов — организаций
и индивидуальных предпринимателей (B2B).
### Процесс отгрузки и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (ДОП)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода обновления заказа
end
Магазин->>Инвойсбокс: Вызов метода отгрузки товара
opt Полная отгрузка товара
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УПД (СЧФДОП)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса заказа
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (СЧФ)
end
opt Частичная отгрузка товара
Магазин->>Инвойсбокс: Передача документа через ЭДО: УКД (ДИС)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода обновления отгрузки
end
Инвойсбокс->>Покупатель: Возврата денежных средств (при переплате)
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УКД КСЧФ (ДИС)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса заказа
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (СЧФ)
end
Магазин->>Инвойсбокс: Документооборот завершён, заказ закрыт
end
1. После [оплаты товара](/docs/merchant/schema/legal), Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (ДОП)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин обновляет данные заказа в системе «Инвойсбокс» [через метод API](/docs/merchant/order/update/).
1. Магазин создает в системе «Инвойсбокс» отгрузку [через метод API](/docs/merchant/order/shipment_create/).
1. Если произведена полная отгрузка товара, то система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УПД (СЧФДОП)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса заказа.
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (СЧФ)**.
1. Если произведена частичная отгрузка товара, то Магазин передаёт через ЭДО в «Инвойсбокс» документ **УКД (ДИС)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин обновляет данные отгрузки в системе «Инвойсбокс» [через метод API](/docs/merchant/order/shipment_update/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю при наличие переплаты.
1. Система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УКД (КСЧФДИС)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса заказа.
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (СЧФ)**.
1. Документооборот завершён, заказ закрыт
### Процесс возврата товара и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(107, 70, 193, 0.13)
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УКД (КСЧФДИС)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса возврата
Магазин->>Инвойсбокс: Передача документа через ЭДО: УКД (КСЧФ)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода отмены возврата или переотправка УКД (КСЧФ)
end
opt Оформление счёта для возврата средств
Инвойсбокс->>Магазин: Оформление счёта для возврата средств
end
Магазин->>Инвойсбокс: Осуществление возврата денежных средств
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Магазин->>Инвойсбокс: Документооборот завершён, возврат закрыт
end
1. После [оформления возврата](/docs/merchant/refund/create/), система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УКД (КСЧФДИС)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса возврата
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УКД (КСЧФ)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин отменяет возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/delete/) или переотправляет документ через ЭДО: **УКД (КСЧФ)**.
1. «Инвойсбокс» оформляет счёт на возврат для Магазина.
1. Магазин возвращает денежных средств в «Инвойсбокс».
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Документооборот завершён, возврат закрыт.
---
---
# OpenCart 3.x
# Описание модуля OpenCart 3.x
[OpenCart](https://www.opencart.com/) — платформа электронной коммерции, ориентированная на создание интернет-магазинов.
Бесплатное свободное программное обеспечение, поддерживаются дополнения - модули и шаблоны.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки и настройки платёжного модуля Инвойсбокс:
1. Пройдите по ссылке к плагину на сайте OpenCart [OpenCart - Платежный модуль Invoicebox](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=43891)
2. Авторизуйтесь или зарегистрируйте новый аккаунт. Это нужно для скачивания плагина.
3. Скачайте архив с плагином.
4. В административной панели зайдите в раздел Модули/Расширения → Установка расширений и загрузите файл с расширением ".ocmod.zip."
5. Перейдите в раздел Модули/Расширения → Модификаторы. Очистите и обновите кэш модификаторов, нажав на соответствующие кнопки в правом верхнем углу экрана.
6. Перейдите на главную страницу административной панели и сбросьте кэш.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Настройка модуля
1. Зайдите в раздел Модули/расширения → Модули/расширения.
2. В выпадающем списке выберете "Оплата".
3. Найдите модуль “Инвойсбокс” и перейдите в редактирование.
4. Перейдите в раздел "настройка платежей". Выберите версию API, заполните необходимые данные:
- идентификатор магазина (v2 и v3 старый и новый)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2 и v3 старый и новый)
- токен (v3 старый и новый)
В пункте 5 будут даны тестовые данные для 2й версии API, а в пункте 6 - для 3й (новой), для получения доступов для 3й версии текущей необходимо обратиться на почту [c-support@invoicebox.ru](mailto:c-support@invoicebox.ru)
5. Доступы для 2й версии API:
1. Поле “Магазин” - вставьте нужное или тестовое значение “207” (если включен тестовый режим)
2. Поле “Региональный код магазина” - введите нужное или тестовое значение “78054” (если включен тестовый режим)
3. Заполните поля “Имя пользователя” и “Пароль”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“
4. Поле “Ключ”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
5. Нажмите кнопку “Сохранить” в правом верхнем углу экрана
6. Доступы для 3й версии API (новой) :
1. Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
2. Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции.
3. Нажмите кнопку “Сохранить” в правом верхнем углу экрана
7. Выберите налоговый режим, в котором работает магазин.
Настройка налогового режима
В налогах важны три пункта:
- показываются они клиенту или нет
- ставка НДС
- формат цен
Формат цен задается в “Система - Локализация - Валюта”. Для каждой валюты проставьте в поле “количество знаков после запятой” значение 2.
Ставка НДС задаётся в меню “Система - Локализация - Налоги - Налоговые ставки”.
Допускаются ставки НДС 0%, 10%, 20%. В типе нужно выставить “процент”, а в “ставке” - нужное число.
Показ налогов настраивается в 3х местах: в модуле “Инвойсбокс”, в настройках, в модуле “Учитывать в заказе”.
Корректными являются такие варианты:
1. Налоги уже учтены в стоимости и не показываются клиенту.
“Система - Настройки - Опции”:
Модули/расширения - Учитывать в заказе-Отчеты - Налоги / Налоговый отчет:
2. Налоги считаются поверх указанной стоимости товара и показываются клиенту:
Модуль “Инвойсбокс”:
Система - Настройки - Опции:
Модули/расширения - Учитывать в заказе - Налоги:
**Убедитесь, что заполнены значения полей “Единица измерения” и “Код единицы измерения”. Стандартные значения “шт” и “796”. Индивидуальные значения для каждого товара задаются в атрибутах товара.**
Если нужно допускать заказ к оплате только после проверки модератором, выберите режим отложенной оплаты и статус, при переводе заказ в который, пользователю будет посылаться ссылка на оплату.
Режим отсроченной оплаты - при включённом режиме отсроченной (отложенной) оплаты покупатель сможет оплатить заказ только после проверки заказа менеджером магазина. Если вам необходимо, чтобы у покупателя была возможность произвести оплату сразу после оформления заказа без подтверждения менеджером - не включайте эту опцию.
Статус заказа для отсроченной оплаты - после проверки заказа менеджер магазина выставит этот статус, покупатель будет уведомлен по электронной почте и сможет оплатить заказ. Также, ссылка на оплату появится в личном кабинете покупателя в разделе "Мои заказы".
**БУДЬТЕ ВНИМАТЕЛЬНЫ!** Если этот статус совпадёт со значением в графе "статус заказа после подтверждения" - режим отсроченной оплаты будет отключён и покупатели будут перенаправляться на сайт «Инвойсбокс» для оплаты сразу после нажатия на кнопку "Оформить заказ".
Заполните значения полей SKU в товарах. Если они будут не заполнены, оплату за товар нельзя будет вернуть. Для этого:
1. Зайдите в раздел Каталог → Товары и нажмите на редактирование товара.
2. Далее зайдите в раздел “Данные” и нажмите кнопку справа “двойная стрелка”.
3. Найдите поле “Артикул” и при отсутствии актуальных артикулов заполните строку любыми числами. Главное, чтобы у каждого товара был свой уникальный артикул.
**Значения остальных полей:**
4.
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале «Инвойсбокс», но деньги с вашей карты списаны не будут.
Статус заказа после оплаты - после успешной оплаты заказа, заказу будет присвоен выбранный статус.
Статус заказа после подтверждения - при нажатии на кнопку "Подтвердить" на последнем этапе оформления заказа, заказу будет присвоен выбранный статус.
Статус заказа после неудачной оплаты - в случае неудачного платежа, заказу будет установлен выбранный статус.
Название - Название метода оплаты на странице оформления заказа.
Инструкция по оплате - отображается при подтверждении заказа. Если поле не заполнено - инструкция выводиться не будет.
В поле "Тип оплаты" выберите вариант full_prepayment (если он не выбран по умолчанию).
Поле "Тип товара по умолчанию"- выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, у каждого товара свой тип можно задать в атрибутах.
Поля “Страна-производитель товара по умолчанию” и “Код страны-производителя товара по умолчанию” : выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, у каждого товара свою страну можно задать в атрибутах.
Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания). Для передачи этих данных понадобится помощь разработчика. Сохранять информацию нужно в таблицу `oc_invoicebox_meta`.
Подробнее о формате передаваемых данных можете узнать в [разделе метаданные](/docs/merchant/order/metadata/).
**Не забудьте в настройках модуля поставить статус “включено”.**
При оформлении заказа обязательно нужно добавить корректный номер телефона.
**Url для уведомлений**
https://ваш_домен/index.php?route=extension/payment/invoicebox/callback
Возникшую при оплате ошибку можно узнать в истории заказа в админ-панели.
**Url для уведомлений** https://ваш_домен/index.php?route=extension/payment/invoicebox/callback
> [!WARNING]
> URL уведомления должен работать только по HTTPS: уведомления об оплате содержат данные заказов и подпись запроса.
### Причины возникновения ошибок при оплате
Если при оплате возникает ошибка, в первую очередь стоит зайти в административную панель, в раздел заказов и открыть новый заказ. Чаще всего причина будет указана там.
1. Проверьте, корректно ли указаны единицы измерения. Они должны быть указаны либо в каждом товаре, либо в настройках модуля (если в товаре нужных атрибутов нет, значения берутся из модуля). Частая ошибка - “шт.” вместо “шт”. Код для “шт” - 796.
2. Проверьте, корректно ли в товарах указан тип товара в самом товаре. Допустимые значения “commodity” и “service”. Либо оставьте поле пустым, чтобы значение бралось из настроек модуля. Путь до настройки: Каталог → Товары → Настройки товара → Атрибуты
3. Проверьте, правильно ли выставлены настройки налогов. См. раздел “настройка налогового режима”.
4. Проверьте, корректно ли заполнены доступы от API.
5. Проверьте, не включена ли опция “тестовое окружение”, если для магазина в Инвойсбокс не создавалось тестовое окружение. Если вы используете тестовые данные доступа из этой инструкции, настройка “тестовое окружение” должна быть отключена.
6. Проверьте в настройках модуля, включен ли он.
7. Если включен режим отложенной оплаты, убедитесь, что статус заказа для отсроченной оплаты не совпадает со статусом заказа после подтверждения.
### Причины возникновения ошибок при возврате
Если при оплате возникает ошибка, в первую очередь стоит посмотреть в истории заказа - иногда точная ошибка может быть указана там.
1. Проверьте, что используется та же версия API, что и при оплате заказа (нельзя переключаться со 2й на 3ю и наоборот).
2. Убедитесь, что общая сумма возврата не превышает допустимую для этого заказа (если по этому заказу уже был возврат, остаток будет указан в предупреждении на странице возврата).
3. Убедитесь, что сумма возврата по каждому товару не больше суммы оплаты по этому товару.
4. Убедитесь, что у каждого товара заполнено поле SKU (Артикул) - с пустым полем сделать возврат для товара нельзя.
### Часто задаваемые вопросы
Вопрос: При выборе способа оплаты, заказ исчезает из панель управления магазином, даже если клиент его оплатил
Ответ: Проверьте корректность указания ссылка уведомления об оплате в личном кабинете системы Инвойсбокс. Заказ отображается в панели управления магазином только в том случае, если система оплаты корректно передала магазину информацию об оплате заказа.
---
# Получение заказа
# Получение заказа
Заказы читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/filter/api/order/order`
- тело ответа - коллекция объектов [OrderResponse](/docs/merchant/order/create/#orderresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
Пример запроса с фильтром по идентификатору заказа
```http
GET /v3/filter/api/order/order?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по [статусу](/docs/merchant/order)
```http
GET /v3/filter/api/order/order?status=completed
```
Пример запроса с фильтром по дате (время создания заказа)
```http
GET /v3/filter/api/order/order?createdAt[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по дате (срок действия заказа)
```http
GET /v3/filter/api/order/order?expirationDate[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по дате (время оплаты заказа)
```http
GET /v3/filter/api/order/order?paidAt[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по идентификатору заказа в учётной системе магазина
```http
GET /v3/filter/api/order/order?merchantOrderId=ORD123456
```
---
#### Пример запроса и ответа
``` json
GET /v3/filter/api/order/order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` json
{
"data": [
{
"id": "01857270-9281-af42-5b20-5fd792455718",
"description": "Оплата заказа №1433",
"currencyId": "RUB",
"amount": 1100,
"vatAmount": 0,
"basketItems": [
{
"sku": "11094",
"name": "Брелок, Категория",
"measure": "шт",
"measureCode": "796",
"quantity": 1,
"amount": 1100,
"amountWoVat": 1100,
"totalAmount": 1100,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "commodity",
"paymentType": "full_prepayment"
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "expired",
"shipmentStatus": "unshipped",
"subtype": "order",
"createdAt": "2023-01-02T12:24:18+00:00",
"merchantOrderId": "1433",
"merchantOrderIdVisible": "1433",
"expirationDate": "2023-01-03T12:24:16+00:00",
"notificationUrl": "https://demo.invoicebox.ru/api/integration/invoicebox-v3",
"successUrl": "https://demo.invoicebox.ru/order/1433",
"failUrl": "https://demo.invoicebox.ru/order/1433",
"paymentUrl": "https://pay.invoicebox.ru/order/01857270-9272-7a9e-d511-a5cd34b6ee62",
"paymentPageUrl": "https://pay.invoicebox.ru/order/01857270-9272-7a9e-d511-a5cd34b6ee62",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru"
},
"languageId": "ru",
"processable": true,
"orderContainerId": "01857270-9272-7a9e-d511-a5cd34b6ee62"
}
],
"metaData": {
"totalCount": 5965,
"page": 1,
"pageSize": 30
},
"extendedData": []
}
```
## Читайте также
- [Выборка поддерживает фильтры, сортировку и постраничный вывод](/docs/api/filters/)
---
# Работа с возвратом
# Работа с возвратом
Как правило, возврат оформляет Магазин, если покупатель хочет вернуть товар или отказался от услуги.
Возврат всегда связан с операцией оплаты, сумма средств с которой будет возвращена покупателю.
Возвращать можно как полную сумму оплаты, так и её часть. Денежные средства обычно возвращаются
через тот платёжный инструмент, через который поступила оплата.
Деньги уходят покупателю после того, как возврат оформлен в системе «Инвойсбокс».
Текущий раздел описывает возможные операции с возвратами.
## Возможные статусы возврата
1. `draft` - Черновик возврата, который возможно скорректировать
2. `created` - Возврат сформирован
3. `completed` - Возврат осуществлён
4. `canceled` - Возврат отменён
---
# Запрос о платеже
## Запрос о платеже
Счёт через сервис Запрос о платеже (RtP) может быть направлен как плательщиками - физическими лицами (B2C),
так и организациям (B2B). Оплата может быть совершена с использованием QR-кода СБП или
[СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b), а также множество альтернативных способов оплаты
на [платёжной странице](/docs/merchant/payment-page/) Инвойсбокс.
### Выставление счёта через Запрос о платеже
Счёт через Запрос о платеже выставляет метод [создания заказа](/docs/merchant/order/create/) — с дополнительными
настройками счёта (InvoiceSetting):
### InvoiceSetting
| Свойство | Обязательное | Значение |
|-------------------------|--------------|----------|
| paymentMethodCode | да | `invoice-rtp` |
| paymentMethodAutosubmit | да | `true` |
Также обязательно предварительное заполнение данных покупателя (Customer):
### Customer
| Свойство | Обязательное | Значение |
|---------------------------|--------------|--------------------------------|
| type | да | legal |
| name | да | Наименование организации |
| phone | да | Номер моб. телефона покупателя |
| email | да | Адрес эл. почты покупателя |
| vatNumber | да | ИНН организации |
| taxRegistrationReasonCode | да | КПП организации |
| registrationAddress | да | Юридический адрес |
При передаче указанных значений, система Инвойсбокс:
1. В случае, если покупатель зарегистрирован в сервисе Запрос о платеже (НСПК), вернёт ссылку для оплаты,
которую можно отобразить в том числе в виде QR-кода.
1. В случае, если покупатель не зарегистрирован в сервисе Запрос о платеже (НСПК), вернёт ссылку на
платёжную страницу Инвойсбокс, где покупатель завершит регистрацию, а также получит ссылку для оплаты, в том числе,
в виде QR-кода.
Информация о факте оплаты будет направлена по API [стандартным уведомлением](/docs/merchant/notification/).
---
---
# Tilda
# Описание модуля Tilda
[Tilda](https://tilda.cc/) — блочный конструктор сайтов, не требующий навыков программирования. Позволяет создавать
сайты, интернет-магазины, посадочные страницы, блоги и email-рассылки. Сайты на платформе собираются из готовых блоков,
которые автоматически адаптируются под мобильные устройства и выделены в смысловые категории (например, обложка сайта,
меню, форма, текст, изображение).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки платёжного модуля системы «Инвойсбокс» в сервисе Tilda на тарифах Personal или Business:
1. Зайдите в административную часть интернет-магазина в Tilda. Перейдите в раздел «Мои сайты» → «Редактировать сайт» → «Настройки сайта» → «Платёжные системы»;
2. Найдите пункт «Универсальная платёжная система», перейдите в него. В шаблоне настроек выберите пункт «Инвойсбокс»
3. Заполните необходимые настройки:
- Идентификатор Магазина;
- API Ключ;
- URL страницы успеха и отказа;
- Выберите галку «Отключить тестовый режим».
Если вам требуется добавить способ оплаты по счёту для организаций и ИП, в настройках платёжного модуля раскройте раздел
«Расширенные настройки», далее, в блоке «Список дополнительных полей» удалите поле `itransfer_body_type`, сохраните
настройки.
Если раздел "Расширенные настройки" отсутствует, добавить его можно в настройках профиля Тильды, поставив галку
"Участвовать в тестировании новых функций".
Идентификатор Магазина и API Ключ доступны в [личном кабинете](https://business.invoicebox.ru) на сайте «Инвойсбокс»,
для просмотра необходимо перейти в раздел «Мои продажи» → «Мои магазины» → нажать на иконку «шестерёнки» и справа от
названия магазина и перейти в раздел «Смотреть детали» (API ключ необходимо скопировать во вкладке «Интеграция (API)»)
4. Нажмите на кнопку «Добавить»;
5. Далее необходимо произвести настройки в личном кабинете системы «Инвойсбокс».
Перейдите в раздел «Мои продажи» → «Мои магазины» → Нажмите на иконку «шестерёнки» справа от названия магазина и
перейдите в раздел «Смотреть детали»
Во вкладке «Интеграция (API)» укажите следующие настройки:
- Тип уведомления: `Оплата/HTTP/Tilda`;
- URL уведомления: `https://forms.tildacdn.com/payment/custom/invoicebox/`
Платформа Tilda Publishing не несет на себе обязательств за работу и безопасность сторонних платёжных интеграций.
#### Читать пользовательское соглашение
```
Выражая свое намерение на интеграцию с сервисом Настраиваемая платежная система (далее – НПС) и/или совершая действия по подключению и дальнейшему использованию выбранного платежного ресурса (далее – Платежная система), юридическое лицо или индивидуальный предприниматель, направившие заявку на интеграцию (далее - заявитель), и Пользователь Платформы Тильда Паблишинг (далее – Пользователь) настоящим подтверждают свое согласие с нижеследующим:
1. Администрация Платформы Тильда Паблишинг (далее – Администрация) прикладывает все усилия, чтобы обеспечить Пользователей точной и достоверной информацией.
1.1. В обязанности Администрации не входит контроль легальности передаваемой заявителями информации, а также определение их законных прав и/или обязанностей.
1.2. Направляя заявку на интеграцию, заявитель гарантирует и подтверждает, что он обладает необходимым правовым статусом, достаточным для осуществления предусмотренной заявкой деятельности по обеспечению совершения платежных операций, включая необходимые разрешения, наличие которых обусловлено требованиями законодательства РФ, национального законодательства.
1.3. Заявитель гарантирует правомерность использования заявленной Платежной системы, и подтверждает, что ее интеграция и дальнейшее применение не ущемляет права и законные интересы третьих лиц, в том числе на результаты интеллектуальной деятельности.
2. В соответствии с действующим законодательством Администрация отказывается от каких-либо заверений и гарантий, предоставление которых может иным образом подразумеваться, и ответственности в отношении использования Платежных систем, интегрированных в НПС.
2.1. Администрация Платформы не гарантирует безопасность использования Платежных систем и бесперебойность их работы.
2.2. Администрация Платформы предоставляет только необходимые вычислительные мощности, позволяющие произвести интеграцию той или иной Платежной системы в НПС с целью ее дальнейшего использования Пользователями Платформы на своих проектах.
2.3. Администрация не является субъектом или иным заинтересованным лицом в отношениях, возникающих между заявителем, Пользователем Платформы и третьими лицами.
2.4. Администрация Платформы не несет ответственности за: а) любые действия и/или бездействия поставщиков услуг, сервисов, сетей, программного обеспечения или оборудования; б) убытки (прямой/косвенный ущерб, упущенная выгода), которые могут возникнуть в результате использования Платежных систем, включая, но не ограничиваясь, ущерб, причиненный любым устройствам и носителям информации и/или программному обеспечению Пользователя, а также приостановку его хозяйственной деятельности.
3. Пользователь несет единоличную ответственность за выбор и дальнейшее использование Платежной системы, а также любые действия, связанные с электронной торговлей.
3.1. Пользователь самостоятельно следит за соблюдением любых применимых к нему и его деятельности законов.
3.2. Пользователь соглашается, что использование выбранной им Платежной системы может сопровождаться взиманием дополнительной платы.
3.3. Пользователь осуществляет использование выбранной им Платежной системы исключительно на свой риск и под свою ответственность, принимая во внимание возможность распространения на него действия юридических и финансовых условий, регулирующих деятельность заявителей, с которыми Пользователю рекомендуется ознакомиться, прежде чем использовать выбранную Платежную систему.
4. Действуя во исполнение требований закона/ требований (уведомлений, претензий) уполномоченных органов и/или их должностных лиц, Администрация Платформы вправе в любой момент приостановить или заблокировать доступ к той или иной Платежной системе или удалить ее из НПС - вне зависимости от того, встроены ли соответствующая Платежная система в проект Пользователя на соответствующий момент времени, без возникновения каких-либо обязательств перед самим Пользователем и/или его клиентами.
```
## Читайте также
- [Где взять идентификатор магазина и API ключ](/docs/merchant/integrationdata/)
---
# Обработка уведомлений
# Обработка уведомлений
Система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта несколькими способами. В первую очередь,
все уведомления о платежах направляются по электронной почте магазина или SMS. Ежедневно система
«Инвойсбокс» также направляет сводный реестр платежей (Переводов) за прошедшие сутки.
Если Магазину требуется получать уведомления о платежах в автоматическом режиме, например, для передачи
статуса оплаты заказа в CMS или иную систему учёта, система «Инвойсбокс» может направлять такие
уведомления по заранее заданным параметрам (ссылке). Система «Инвойсбокс» поддерживает множество
форматов уведомлений, в том числе форматы сторонних платёжных решений.
Если в системе Магазина отсутствует возможность реализации сервиса (ссылки) для получения информации
об оплате заказа, существует возможность реализации механизма уведомлений через [веб-сокеты](/docs/api/websockets/).
В текущем разделе описаны базовые форматы уведомлений.
---
# Изменение заказа
Заказ меняется, пока не оплачен:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/:uuid` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderRequest](#updateorderrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/019fc671-6d37-77e0-6080-fec092bf521f
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"amount": 15000,
"vatAmount": 0,
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Бронирование номера, продление на сутки",
"measure": "шт.",
"measureCode": "796",
"quantity": 1,
"amount": 15000,
"amountWoVat": 15000,
"totalAmount": 15000,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "service",
"paymentType": "full_prepayment"
}
]
}
```
Суммы заказа и корзины обязаны сходиться — правило описано в разделе
[как считаются суммы](/docs/merchant/order/create/#как-считаются-суммы).
Ответ:
``` json
{
"id": "019fc671-6d37-77e0-6080-fec092bf521f",
"description": "Оплата бронирования № 4412",
"currencyId": "RUB",
"amount": 12000,
"vatAmount": 0,
"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"
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "created",
"shipmentStatus": "unshipped",
"subtype": "order",
"createdAt": "2026-08-03T07:05:50+00:00",
"merchantOrderId": "portal-6c2fcf273e55-docs-example-1785740749696",
"merchantOrderIdVisible": "portal-6c2fcf273e55-docs-example-1785740749696",
"expirationDate": "2026-08-04T07:05:49+00:00",
"internalProperty": {},
"tags": [
"agent"
],
"sourceId": "v3",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"paymentUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
"paymentPageUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"countryId": "RUS"
},
"languageId": "ru",
"processable": true,
"orderContainerId": "019fc671-6c80-eed3-ce48-9bb53f679353"
}
```
## UpdateOrderRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------|
| description | нет | string | Описание заказа | `Оплата номера в отеле` |
| amount | нет | float | Сумма заказа | `19658.45` |
| vatAmount | нет | float | Сумма НДС | `156.56` |
| expirationDate | нет | datetime | Срок действия заказа | `2026-12-22T00:00:00+00:00` |
| basketItems | нет | array of [BasketItem](/docs/merchant/order/create/#basketitem) | Корзина заказа | |
| metaData | нет | object | [Дополнительные данные заказа](/docs/merchant/order/metadata/) | |
| customer | нет | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике | |
| shopId | нет | string(36) | Идентификатор связанного магазина/маркетплейса | `06581534-196a-1105-839a-82422289d6d9` |
---
---
# Гарантийный фонд: подтверждение оплаты
# Гарантийный фонд: подтверждение оплаты заказа
Постоянный покупатель, заключивший договор, держит в системе гарантийный фонд и подтверждает оплату
счёта в его пределах — не переходя на платёжную страницу Инвойсбокса. Магазин делает это тремя
методами подряд:
1. [Проверка возможности оплаты](/docs/merchant/guarantee/validate/) — хватает ли средств фонда;
2. [Запрос кода подтверждения](/docs/merchant/guarantee/code/) — код уходит покупателю;
3. [Подтверждение оплаты заказа](/docs/merchant/guarantee/pay/) — заказ переходит в оплаченный.
Общая картина — в [схеме взаимодействия](/docs/merchant/guarantee/schema/). Не путайте этот механизм
с [холдированием](/docs/scenarios/guarantee/): там сумма блокируется на банковской карте, здесь
списывается с фонда организации.
Для использования описываемых методов, в сервисе Магазина должны быть приняты меры безопасности
в виде использования таких инструментов как Google reCaptcha, Yandex SmartCaptcha, Huawei Safety Detect и пр.
---
# Аспро Корпоративный сайт
# Описание модуля Аспро
[Аспро: Корпоративный сайт](https://aspro.ru/marketplace/solutions/aspro.allcorp/) — готовое решение для создания сайта компании.
Начиная с версии 1.1.0 решения, появилась возможность подключать прямую интеграцию с системой Инвойсбокс. Система позволяет
принимать платежи на сайте. При этом вам не нужно покупать сторонние модули, поскольку в решении добавлен специальный
компонент для работы с платёжной системой.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Чтобы подключить систему Инвойсбокс, в административной части сайта перейдите в Аспро (1) → Аспро: Allcorp3 (2) → Настройки (3) и
перейдите на вкладку:
На вкладке «Корзина» найдите поле «Платёжная система», выберите «Интернет-эквайринг Инвойсбокс (приём платежей)» и нажмите «Применить».
Для настройки платёжной системы выполните тестовый заказ. На странице успешного оформления заказа в режиме вкладки перейдите в
настройки параметров компонента платёжной системы Инвойсбокс. Нажмите на стрелку рядом с шестерёнкой (1), выберите «Аспро: Платёжная
платформа Инвойсбокс» (2) и «Редактировать параметры компонента» (3).
В параметрах компонента доступны следующие поля:
1. Идентификатор магазина
2. Региональный код магазина
3. Подпись безопасности — API ключ. Подпись, идентификатор и код получаются при заключении договора с «Инвойсбокс» и находятся в [личном кабинете](https://business.invoicebox.ru/Login/).
4. Номер заказа. Значение по умолчанию `«={$_REQUEST["RESULT_ID"]}»` **менять не нужно**.
5. Стоимость заказа. Значение по умолчанию «={$totalSumm}» **менять не нужно**.
6. Код валюты. По умолчанию используются рубли. Этот код указывается в соответствии со стандартом [ISO 4217](/docs/dictionary/iso4217/): RUB — российский рубль, EUR — евро, USD — доллар США и т. д.
7. Тестовый режим. **Параметр неактуален**, его необходимо отключить. По-умолчанию магазин находится в тестовом режиме, для перевода магазина в боевой режим обратитесь к вашему менеджеру или [напишите нам](https://www.invoicebox.ru/ru/contacts/feedback.html).
---
# Отмена заказа
# Отмена заказа
Заказ отменяется, пока не оплачен полностью:
- метод: `DELETE`
- ресурс: `/v3/billing/api/order/order/:uuid` - где `:uuid` это идентификатор заказа
- тело запроса - отсутствует
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse) со статусом status = `canceled`
#### Пример запроса и ответа
#### 🌐 HTTP
```http
DELETE /v3/billing/api/order/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X DELETE '{baseUrl}/v3/billing/api/order/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
{baseUrl} - [базовый URL](/docs/api)
В зависимости от сценария использования и настроек магазина, может быть применена разная логика при вызове метода.
По умолчанию, отменить заказ возможно только до момента получения системой Инвойсбокс
информации об отгрузке по заказу (информация о факте оказания услуги или поставки товара). После получения информации
об отгрузке системой Инвойсбокс, для отмены заказа и возврата средств, пожалуйста, воспользуйтесь
[методом оформления возврата](/docs/merchant/refund).
> [!IMPORTANT]
> В случае, если оплата заказа подтверждена с использованием гарантийных платёжных инструментов (Обещанный платёж, Гарантийный фонд,
> Овердрафт и т.д.) и у заказа нет информации об успешной отгрузке, отмена заказа инициирует полный возврат гарантийного платежа
> плательщику. Гарантийный платёж и его отмена не будут отражены в реестрах и финансовых отчётах магазина.
### Сценарий отмены заказа без невозможности оказания услуги
Пример использования метода отмены заказа для осуществления отмены гарантийного платежа в случае невозможности оказать
услугу или поставить товар покупателю. Например, при получении информации об оплате заказа произошла ошибка оформления
купленного билета или на складке не оказалось выбранного товара.
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создает заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта через предавторизацию средств на карте или гарантийный фонд
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате
Магазин->>Инвойсбокс: Ошибка оказания услуги/поставки товара, status = shipping_unavailable
Магазин->>Инвойсбокс: Вызов метода отмены заказа
Инвойсбокс->>Покупатель: Возврат оплаченных средств
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт, система Инвойсбокс предавторизует сумму оплаты на карте плательщика или гарантийном фонде.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» [оповещает Магазин](/docs/merchant/notification) об успешной оплате заказа.
1. Магазин отвечает системе «Инвойсбокс» на уведомление ошибкой оказания услуги/поставки товара, возвращая статус `shipping_unavailable`
1. Магазин вызывает в системе «Инвойсбокс» [метод отмены заказа](/docs/merchant/order/delete/).
1. Если в заказе имеется статус `shipping_unavailable` и предавторизованный платёж, система «Инвойсбокс» отменяет оплату и заказ, возвращает средства плательщику. Если в заказе иной статус - возвращается ошибка.
---
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "canceled",
"amount": 12000,
"currencyId": "RUB",
"createdAt": "2026-08-01T10:00:00+03:00"
}
}
```
---
# SDK
# Готовые библиотеки (SDK)
Для интеграции с Инвойсбокс API вы можете использовать готовые библиотеки (SDK) для серверного или клиентского
взаимодействия с Инвойсбокс и для встраивания платёжных форм на сайт, в мобильное или иное приложение.
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты.
| Платформа/язык разработки | Детали
| -----------------------------------| ---------------------------------------
|  | [Смотреть »](/docs/merchant/sdk/php)
---
# Подтверждение оплаты заказа
# Подтверждение оплаты заказа
Оплата заказа подтверждается одним вызовом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/pay`
- тело запроса - объект [PayRequest](#payrequest)
- тело ответа - объект [PayResponse](#payresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/pay
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
},
"customerPaymentData" : {
"publicCode" : "string",
"code" : "string"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "success",
"resultData": {}
}
}
```
## PayRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
| customerPaymentData | да | [customerPaymentData](/docs/merchant/guarantee/validate/#validaterequest) | Данные ддя подтверждения оплаты заказа | |
#CustomerPaymentData
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|----------------------------------------------------|
| publicCode | да | string | Публичный идентификатор кода |
| code | да | string | Полученный плательщиком от системы Инвойсбокс код |
## PayResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/pay/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|------------------------------------------|
| type | да | enum | Тип действия к выполнению: none, message |
| result | да | enum | Статус проверки (см. ниже) |
| resultData | да | object | Объект, в зависимости от типа действия (type) и результата (result), см. ниже |
## Message
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|---------------------|
| title | да | string | Заголовок сообщения |
| message | да | string | Сообщние |
Если type = message, требуется отобразить пользователю информацию от системы Инвойсбокс. Информация будет передана
в объекте resultData и будет содеражать вложенный объект message, пример:
``` json
{
"message": {
"title": "Недостаточно средств",
"message": "Для подтверждения выбранного заказа недостаточно средств. Пожалуйста, восстановите баланс гарантийного фонда."
}
}
```
Возможные статусы:
- alreadyPaid - Оплата заказа уже подтверждена
- wrongCode - Передан неверный код, повторите попытку оплаты
- limitReached - Превышено кол-во попыток оплаты
- notEnoughMoney - Недостаточно средств на счету
- error - Непредвиденная ошибка
- success - Оплата прошла
---
---
# Создание отгрузки
# Создание отгрузки
## Что делает отгрузка
Отгрузка фиксирует факт поставки товара или оказания услуги. По ней формируются отчётные документы и
[фискальный чек](/docs/merchant/fz54/), а у заказов с холдированием — списываются заблокированные на
карте средства.
- Отгрузок по заказу может быть несколько: например, поставка партиями. На каждую оформляются свои
документы.
- Сумма всех отгрузок не превышает сумму заказа.
- Когда в отгрузках закрыты все позиции заказа, деньги списываются целиком. Если часть заказа не
состоялась, последнюю отгрузку отправляют с `final` = `true`: заказ считается выполненным, а остаток
резерва разблокируется — подробнее в [холдировании](/docs/merchant/order/hold/).
Отгрузка создаётся одним запросом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/shipment`
- тело запроса - объект [CreateShipmentRequest](#createshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/billing/api/order/shipment
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"orderId": "0187c6db-1637-c1ca-bef7-f6706799c41e",
"basketItems": [
{
"sku": "01GZ3DP5HADMSBAXRKVCES5FJX",
"name": "iPhone 5s",
"measure": "шт",
"measureCode": "796",
"originCountry": "Россия",
"originCountryCode": "643",
"grossWeight": 1010.55,
"netWeight": 1000.66,
"quantity": 1,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 122.00,
"totalVatAmount": 22.00,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_prepayment"
}
]
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## CreateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| orderId | да | string(36) | Id заказа | `01771534-1a57-f184-dee3-ebeb91dded75` |
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
| final | нет | bool | Завершающая ли отгрузка по заказу, по умолчанию `false` | `true`, `false` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#createshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Платёжные виджеты на сайт
# Платёжные виджеты на сайт
Виджет принимает оплату без разработки: вы вставляете на страницу готовый код, и покупатель
платит, не уходя с сайта. Разработка не нужна, знания веб-технологий тоже: состав заказа и настройки
задаются в конструкторе.
Если сумму и состав определяет только ваш сервер или заказы рождаются в учётной системе, виджета
недостаточно — смотрите [интеграцию по API](/docs/merchant/order/create/) или
[готовые модули CMS](/docs/merchant/cms/). Сравнение путей — в разделе [Виджеты](/widgets/).
## Как это работает
1. **Собрать.** Настройки, живой предпросмотр и готовый код — в
[конструкторе](/widgets/constructor/). Понадобятся идентификатор магазина и региональный код: они
приходят в письме при регистрации, а для пробы конструктор подставит демо-магазин.
2. **Скопировать код.** Один блок с кнопкой — вставляется в любую вёрстку.
3. **Вставить на страницу.** Примеры для обычного сайта, Тильды, WordPress, 1С-Битрикс и мобильного
приложения — в [инструкции по вставке](/widgets/embed/).
## Что подготовить на сайте
| Страница | Зачем нужна |
|---|---|
| Страница с виджетом | здесь стоит код и покупатель вводит свои данные; подойдёт любая, даже главная |
| Страница завершения | сюда виджет вернёт покупателя и после успешной оплаты, и после неудачной. Её адрес указывается в настройках виджета — полезно описать на ней, что делать дальше |
## Настройки виджета
Все параметры задаются в [конструкторе](/widgets/constructor/); ниже — что каждый из них меняет. Если код виджета придётся править руками — например, подставлять номер заказа из своей системы, — смотрите [справочник параметров](/widgets/reference/): там перечислены поля кода, состав заказа и значения, которые они принимают.
| Настройка | Что задаёт | Когда нужна |
|---|---|---|
| Что оплачивают | заранее заданный состав заказа либо свободная сумма | состав — для товаров и услуг с известной ценой; свободная сумма — для пополнения баланса и абонентской платы |
| Текст на кнопке | подпись кнопки виджета | набор текстов расширяется по запросу в [поддержку](https://www.invoicebox.ru/ru/contacts) |
| Дополнительные поля | что покупатель заполнит сам: номер заказа, фамилия и имя, телефон, почта, количество | хотя бы одно из двух — почта или телефон — обязательно: по ним уходят счёт и документы |
| Тип плательщика | физическое лицо, организация или ИП, выбор покупателем | для оплаты от организаций и ИП выбирайте второй вариант: тогда формируется счёт и закрывающие документы |
| Код товара или услуги | ваш идентификатор заказа, договора или артикула | обязателен: по нему вы узнаёте платёж в своей системе |
| Ссылка возврата | адрес страницы завершения оплаты | заполняется всегда, иначе покупателю некуда вернуться |
| Оплачиваемые позиции | название, количество, цена и ставка НДС каждой позиции | минимум одна позиция; ставки — в [справочнике](/docs/dictionary/tag1199/) |
| Выбор одной позиции | покупатель выбирает один вариант из списка | удобно для тарифов: перечислите варианты, покупатель отметит нужный |
| Открывать в новом окне | форма открывается в новой вкладке или в текущей | снимите отметку, если хотите оставить покупателя на странице |
## Что важно знать до вставки
Сумма и состав заказа приходят из браузера покупателя и не подписаны — их можно изменить в браузере
до отправки. Это осознанное упрощение ради быстрого старта, но оно накладывает обязанность: получив
[уведомление об оплате](/docs/merchant/notification/status/), сверяйте сумму с той, которую ожидали.
Если цену определяет только ваш сервер, надёжнее создавать заказы
[через API](/docs/merchant/order/create/). Подробно — [Безопасность виджета](/widgets/security/).
Прежний конструктор на [widget.invoicebox.ru](https://widget.invoicebox.ru/?utm_source=docs)
продолжает работать: код, собранный там и в конструкторе портала, одинаковый.
### Примеры виджетов
Ниже — живые виджеты в песочнице портала: та же форма, что увидит покупатель на вашем сайте.
Собраны они на демо-магазине документации, поэтому оплата ничего не спишет. Свой виджет
собирается в [конструкторе](/widgets/constructor/) — настройки слева, код справа.
**Счёт организации или ИП.** Состав задан заранее, покупатель вводит только реквизиты. Так выставляют счёт за услуги по договору.
**Оплата товара с количеством.** Покупатель меняет количество, сумма пересчитывается на месте.
**Выбор из нескольких позиций.** Покупатель выбирает тариф или товар из списка.
**Пополнение баланса.** Сумму вводит покупатель — подходит для депозитов и абонентской платы.
---
---
# Модули для CMS
# Готовые модули для CMS
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления сайтом (CMS) | Версия | Лицензия CMS/Модуля | Детали
|------------------------------------------------------------------|---------------|-------------------------------| ---------------------------------
| 
| > 16.x | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/1c-bitrix/)
| | > 1.2.x | Платная | [Смотреть »](/docs/merchant/cms/aspro/)
| | > 6.1.x | Бесплатный | [Смотреть »](/docs/merchant/cms/woocommerce/)
| | Все | Условно-бесплатный/Бесплатный | [Смотреть »](/docs/merchant/cms/tilda/)
| 
| InSales | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/insales/)
| 
| VirtualityCMS | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/vicms/)
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| > 5.* | Бесплатный |[Смотреть »](/docs/merchant/cms/joomshopping/)
| | Virtuema rt | Бесплатный |[Смотреть »](/docs/merchant/cms/virtuemart/)
| 
| --- | --- |
| 
| --- | --- |
| | 2.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv2/)
| | 3.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv3/)
| 
| --- | --- |
| 
| 8.X | Бесплатный |[Смотреть »](/docs/merchant/cms/prestashop/)
| 
| --- | --- |
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
## Читайте также
- [Требования к разработке расширений](/docs/merchant/cms/requirements/)
---
# Получение отгрузки
# Получение отгрузки
Отгрузки читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/billing/api/order/shipment`
- тело ответа - коллекция объектов [ShipmentResponse](/docs/merchant/order/shipment_create/#shipmentresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
#### Пример запроса и ответа
```http
GET /v3/billing/api/order/shipment?id=371723
```
Пример запроса с фильтром по id заказа
```http
GET /v3/billing/api/order/shipment?orderId=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по id магазина
```http
GET /v3/billing/api/order/shipment?merchantId=21827364-196a-1178-839a-82469489d6d7
```
---
Ответ:
``` json
{
"data": [
{
"id": 616095,
"orderId": "019e51e2-3970-9852-e8c8-803c16ac9c74",
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"basketItems": [
{
"sku": "baaa27aee304c4",
"name": "Мягкая игрушка Винни Пух",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 14162,
"amountWoVat": 11608.2,
"totalAmount": 14162,
"totalVatAmount": 2553.8,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_payment"
}
],
"createdAt": "2026-05-22T23:10:55+00:00",
"type": "shipment",
"status": "completed",
"amount": 14162,
"vatAmount": 2553.8,
"final": true
}
]
}
```
---
# Модули для CRM
# Готовые модули для CRM
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления клиентами (CRM) | Версия | Лицензия CRM/Модуля | Детали
|-----------------------------------------------|------------|---------------------| ---------------------------------
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/amocrm/)
|  | любая | Платная | [Смотреть »](/docs/merchant/crm/sportcrm/)
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/retailcrm/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Изменение отгрузки
# Изменение отгрузки
Отгрузка меняется по своему идентификатору:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/shipment/:uuid` - где `:uuid` это идентификатор отгрузки
> [!NOTE]
> Идентификатор заказа при изменении не передаётся — отгрузка уже связана с заказом. Признак завершающей отгрузки задаётся при создании.
- тело запроса - объект [UpdateShipmentRequest](#updateshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/shipment/{id}
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"amount": 100.5,
"vatAmount": 100.5,
"documentNumber": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#updateshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Virtuemart
# Virtuemart (joomla)
Расширение Virtuemart для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/Virtuemart-3)
Также полезно будет установить [русификатор для расширения](https://virtuemart.net/community/translations/virtuemart/ru-RU)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Устанавливается расширение через админ панель, в пункте "загрузить и установить"
1. Перейдите в компонент "Virtuemart" —> "Способы оплаты";
2. Добавьте новый метод оплаты "Invoicebox" и заполните поля. Нажмите «Сохранить»;
3. Зайти в раздел Администрирование -> Способы оплаты, добавить новый метод оплаты с процессором invoicebox;
4. Заполнить настройки на вкладке "Общее";
5. Перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
6. Выберите необходимые статусы заказа;
7. Нажмите на кнопку "Сохранить".
### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Принятая валюта - выберите валюту рубли.
Страны - если этот параметр не важен, не изменяйте его, если вы продаете на несколько стран, то возможно вам стоит ограничить показать платежного плагина, и выбрать только для "России".
Минимальная сумма - минимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Максимальная сумма - максимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Плата за транзакцию - дополнительный фиксированный сбор при выборе данного платежного метода.
Плата или возврат процента от общей суммы - дополнительный сбор в процентах при выборе данного платежного метода.
Налог - налоговые правила для данного платежного метода.
---
# Модули для ERP
# Готовые модули для ERP-систем
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей.
| ERP-система | Версия | Лицензия ERP/Модуля | Детали
| ---------------------------------------| ---------| ------------------------------------------------------- | ---------------------------------
|  | >= 7.9.7 | Платная/Платный/Наличие лицензии api payment (21016318) | [Смотреть »](/docs/merchant/erp/iiko/)
|  | --- | Платная/Платный | [Смотреть »](/docs/merchant/erp/bnovo/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Смена магазина
Для управления выплатами и реквизитами, по которым их следует осуществить,
вы можете воспользоваться методом смены магазина. Изменить магазин можно как
у оплаченного заказа, так и у не оплаченного. При этом, изначальный магазин
должен иметь специальный тип, позволяющий в дальнейшем вносить такие изменения
в заказ.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/order-merchant-move`
- тело запроса - объект [UpdateOrderMerchantRequest](#updateordermerchantrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/order-merchant-move
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateOrderMerchantRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-----------------|-------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| orderId | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
---
---
# Joomshopping
# JoomShopping
Расширение JoomShopping для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия Joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/JoomShopping-4)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка плагина
В админ-панели пройдите в "Компоненты" —> "JoomShoppping" —> "Установка и Обновление". Выберите файл "invoicebox_joomshoppping_5.zip" и нажмите на кнопку "Загрузить".
## Настройка модуля
1. Перейдите в компонент "JoomShoppping" —> "Опции" —> "Способ оплаты";
2. Выберите способ оплаты "InvoiceBox" (Инвойсбокс) и перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
3. Выберите необходимые статусы заказа в опции "Статус заказа для успешных транзакций";
4. Нажмите на кнопку "Сохранить".
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Изображения URL - ссылка на картинку, которая выводится вместе с платежной системой.
Цена - дополнительный сбор (в процентах или фиксированная сумма) при выборе данного платежного метода.
Выберите налог - налоговые правила для данного платежного метода.
### Настройка панели Инвойсбокс:
1. Для настройки панели управления Инвойсбокс, перейдите по [ссылке](https://login.invoicebox.ru/)
2. Авторизуйтесь и пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/index.php?option=com_jshopping&controller=checkout&task=step7&act=notify&js_paymentclass=pm_invoicebox&no_lang=1&tmpl=component`
5. Сохраните изменения.
---
# Смена статуса заказа
Изменение статуса возможно только у [не процессинговых заказов](/docs/merchant/order/non-processable-order/),
а именно у заказов со свойством `processable = false`. Для изменения статуса, вы можете воспользоваться соответствующим
методом.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/:uuid/status` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderStatusRequest](#updateorderstatusrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9/status
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"status": "completed"
}
```
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "completed",
"amount": 19658.45,
"currencyId": "RUB",
"paidAt": "2026-08-01T12:31:00+03:00"
}
}
```
## UpdateOrderStatusRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|------------|-------------------------------------------|---------------------------------------------------|
| status | да | enum(4) | Статус заказа | `created`, `completed`, `expired`, `canceled` |
---
---
# Интеграции с PSS/GDS
# Готовые интеграции с PSS/GDS
Обращаем ваше внимание, что представленный перечень отлаженных интеграций неполный и содержит только наиболее актуальные варианты.
| PSS/GDS | Наименование | Детали
| ------------------------------------| ---------------------------| --------------------------------------------
|  | Сирена-Тревел/МПС (EgoPay) | [Смотреть »](/docs/merchant/pss/mps/)
|  | ТАИС TravelShop | [Смотреть »](/docs/merchant/pss/tais/)
Если вы не нашли подходящую интеграцию, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы
поможем вам соориентироваться.
---
# InSales
# Расширение Инвойсбокс для InSales
**Расширение доступно на тарифах Омни и Премиум.**
1. Чтобы подключить расширение Инвойсбокс, напишите на [почту](mailto:c-support@invbox.ru) и указать в письме номер личного кабинета InSales
2. После добавления, расширение будет доступно в личном кабинете в разделе "Расширения"
3. Нужно ввести данные для интеграции, которые будут находиться в [личном кабинете](https://business.invoicebox.ru) после регистрации и заключения договора.
Потребуется: Идентификатор магазина, Авторизационный токен (API токен в ЛК) и Ключ для проверки подписи запроса (API ключ в ЛК)
Данные для тестирования
- Идентификатор магазина
- Авторизационный токен
- Ключ для проверки подписи запроса
Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Ставка НДС должна совпадать с вашим режимом налогообложения и ставкой указанной в настройках магазина.
Остальные настройки заполняются по умолчанию, если они не заполнены в магазине.
4. В пункте “настройка” - “оформление заказа” - “оплата” появится новый вид оплаты “Инвойсбокс”
5. В настройках нужно привязать способ оплаты к способам доставки, а также выставить тип плательщиков: физ.лицо и/или юр.лицо. Если ни один способ доставки не будет привязан, то вид оплаты не появится на странице оформления заказа. По желанию сменить название и установить наценку
6. Для включения возможности оплаты юр.лицам передите в "настройки" -> "оформление заказа" -> "перейти к редактированию полей клиента" и включить пункт "Организация". ИНН — обязательное поле
Остальные настройки будут заполнены автоматически и не требуют изменений.
7. В случае успешной оплаты, покупатель будет переадресован на страницу нового заказа со статусом “оплачен”.
В случае возникновения ошибки при оплате, покупатель будет перенаправлен в магазин на страницу оформления заказа , где у него будет возможность заново перейти к оплате
---
# Prestashop
# Описание платёжного модуля для Prestashop
Платёжный модуль для интеграции платёжной системы «Инвойсбокс» и PrestaShop v8.1.2.
Реализована поддержка платёжного API. Протестировано на CMS PrestaShop v8.1.2.
Скачать модуль можно по [ссылке](https://github.com/InvoiceBox/PrestaShop-1.7)
Модуль поддерживает работы с 2 версией АПИ
Версию вашего подключения уточняйте у вашего персонального менеджера или в [службе поддержки](https://www.invoicebox.ru/ru/contacts) системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. В админ панели сайта выбираем пункт "Модули"->"Module manager"->"Загрузить модуль"
2. Далее необходимо настроить модуль
3. Здесь необходимо указать 3 обязательных параметра: id магазина для версии API v2, региональный код и ключ подписи запроса для обработки уведомлений об оплате.
4. Все необходимые параметры находится в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
### Настройка панели Инвойсбокс:
1. Авторизуйтесь в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
2. Пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/modules/invoicebox/callback.php`
5. Сохраните изменения.
---
---
# Рекуррентные платежи
# Рекуррентные платежи
При оплате заказа физическим лицом есть возможность применить рекуррентные платежи. Это позволит
сохранить токен банковской карты пользователя, для последующего списания с неё средств без участия
клиента, например, для списания средств по подписке.
## Почему для организаций регулярность устроена иначе
Списание по сохранённой карте работает, и дело не в поддержке. Владелец карты — всегда физическое
лицо: даже корпоративная карта оформлена на сотрудника. Значит расход ложится на человека, и потом
ему отчитываться перед бухгалтерией — сохранить чек, обосновать трату, приложить её к отчёту. Для
регулярных корпоративных расходов это неудобно, и чем больше сотрудников, тем неудобнее.
Поэтому организациям и ИП адресована подписка — шаблон платежа: правила, по которым покупателю
уходит счёт. Правило задаёт период, конкретный день или условие — например, снижение баланса до
порога. Дальше есть два пути:
- **заказы создаёт ваша система** — по своему расписанию вызывает
[создание заказа](/docs/merchant/order/create/), и счёт уходит покупателю как обычно;
- **заказ-подписка** — создаётся один раз с параметрами периода и условий, клиент подписывается на
неё, и счета приходят ему в нужное время без новых вызовов с вашей стороны.
Счёт по подписке доходит покупателю привычным каналом: письмом, ссылкой или
[Запросом о платеже](/docs/scenarios/rtp/) в приложение банка.
> [!NOTE]
> Параметры заказа-подписки настраиваются при подключении: публичного описания полей в контракте пока
> нет, поэтому состав правил уточняйте у [технической поддержки](https://www.invoicebox.ru/ru/contacts).
> Как только описание появится, оно встанет на эту страницу.
## Привязка карты
### Схема получения токена карты
## Данные бронирования авиабилетов
Для передачи данных бронирования авиаперелётов, в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [FlightReservation](https://schema.org/FlightReservation). Для каждого из сегментов полёта,
а также для каждого из пассажиров передаётся отдельный объект [FlightReservation](https://schema.org/FlightReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "FlightReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "Flight",
"flightNumber": "NDJ37S",
"provider": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"seller": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"departureAirport": {
"@type": "Airport",
"name": "Москва (Шерементьево)",
"iataCode": "SVO"
},
"departureTime": "2022-03-04T20:15:00+03:00",
"departureGate": "11",
"departureTerminal": "C",
"arrivalAirport": {
"@type": "Airport",
"name": "Санкт-Петербург (Пулково)",
"iataCode": "LED"
},
"arrivalTime": "2022-03-05T21:30:00+03:00",
"arrivalGate": "11",
"arrivalTerminal": "1"
},
"airplaneSeat": "1A",
"airplaneSeatClass": {
"@type": "AirplaneSeatClass",
"name": "Business"
},
"ticketNumber": "111-1231231239",
"ticketToken": "qrCode:AB34",
"checkinUrl": "https://checkmytrip.ru/onlinecheckin.html",
"reservedTicket": {
"@type": "flightTicket",
"underName": {
"@type": "Person",
"name": "MAKAROV ANDREY"
},
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}]
}
```
## Данные бронирования железнодорожных билетов
Для передачи данных бронирования железнодорожных билетов, в полях элементов корзины `metaData`
необходимо передать объект [TrainReservation](https://schema.org/TrainReservation) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (билета) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "trainTicket",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"gender": "male",
"nationality": "RUS",
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"coachNumber": "04",
"coachType": "Плацкартный",
"serviceClass": "3Э",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketNumber": "74363372056286",
"ticketStatus": "Оформлен",
"ticketIssueTime": "2021-05-15T12:30:21+01:00",
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
#### Пример объекта элемента корзины (услуги) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "baggageCheck",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"ticketNumber": "44363452345662",
"declaredName": "Велосипед",
"declaredValue": 100.00,
"note": "Малогабаритный багаж в специализированном купе",
"fare": 57.00,
"valueFee": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
## Данные бронирования места проживания
Для передачи данных бронирования места проживания (отель, хостел, апартаменты и пр.), в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [LodgingReservation](https://schema.org/LodgingReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Гранд Отель Европа",
"address": {
"@type": "PostalAddress",
"streetAddress": "ул. Михайловская, д. 1/7",
"addressLocality": "Санкт-Петербург",
"addressRegion": "Санкт-Петербург",
"postalCode": "191186",
"addressCountry": "ru"
},
"telephone": "+7 (812) 329-6000"
},
"checkinTime": "2021-02-21T16:00:00-08:00",
"checkoutTime": "2021-02-23T11:00:00-08:00"
}]
}
```
## Данные подписки
Для передачи данных о подписке, в полях элементов корзины `metaData`
необходимо передать объект [PaymentPlan](https://schema.org/) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (подписки) PaymentPlan
``` json
{
"@context": "https://schema.org",
"@type": "PaymentPlan",
"name": "Pro-подписка на сервис Экспресс Клиент",
"description": "Доступ к премиум-функциям в течение 1 года с ежемесячными платежами",
"billingPeriod": "P1M",
"billingIncrement": "1",
"contractStartDate": "2025-01-01",
"contractEndDate": "2026-01-01",
"price": "2990.00",
"priceCurrency": "RUB",
"provider": {
"@type": "Organization",
"name": "Экспресс Клиент",
"url": "https://expressclient.ru"
}
}
```
---
---
# Требования
# Требования к разработке расширений «Инвойсбокс» для систем управления сайтами
## Используемый протокол обмена данными (API)
Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина)
для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу:
[Инвойсбокс API v3](https://docs.invoicebox.ru).
Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен
соответствовать описанному в API. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок,
модуль должен отобразить соответствующее сообщение пользователю, данные не должны отправляться в платёжный шлюз.
В модуле должны быть предусмотрены следующие функции:
1. Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
2. Callback-скрипт для получения информации об оплате заказа;
3. Функции оформления возврата по заказу.
## Множество способов оплаты
В тех CMS, где это технически возможно, модуль должен поддерживать оформление двух способов оплаты, а именно -
оплата для физических лица (банковские карты, интернет банки и т.д.), а также оплата для юридических лиц
(оплата по счёту для организаций и ИП). В настройках модуля должна быть предусмотрена возможность выбора
используемых способов оплаты.
При выборе способа оплаты для организаций и ИП, по API должны передаваться данные организации - ИНН, КПП,
наименование, юридический адрес (при наличие данных в заказе).
Т.е. в результате установки модуля, в CMS должно появится два способа оплаты. Там где это невозможно,
способ оплаты выбирается на странице платёжного шлюза системы «Инвойсбокс».
## Идентификация модуля
Важно обратить внимание на формирование идентификатора приложения и модуля при работе с API.
В API v3 идентификатор приложения передаётся в HTTP-заголовке User-Agent.
В API v2, в параметрах платёжной формы, в обязательном порядке должно присутствовать поле с идентификатором
приложения - itransfer_cms_name.
## Параметры заказа (счёта)
Модуль обязательно должен передавать тип позиции в заказе - товар или услуга, для API V3 - более детальное
значение [см. справочник](/docs/dictionary/tag2108/);
## Callback для получения информации об оплате
Смена статуса заказа в CMS магазина происходит по факту получения информации об оплате в формате,
описанном по адресу:
Для API v3: [Уведомление по умолчанию](/docs/merchant/notification/status/);
Для API v2: [HTTP-уведомления о переводах](https://www.invoicebox.ru/ru/integration/webapi/notify/defaulthttp/).
При получении информации об оплате, модуль должен сверить подпись запроса, идентификатор магазина, валюту заказа,
сумму оплаты с суммой заказа. В случае расхождения, статус заказа менять не нужно, модуль должен
вернуть детальное описание ошибки в соответствии с форматом ответа API.
В модуле должно быть реализовано получение тестового запроса с информацией об оплате, при котором модуль
должен выдать успешный ответ в случае корректной передачи подписи запроса и идентификатора магазина.
Тестовый запрос используется для проверки корректность установки модуля и не должен приводить к смене статуса
какого-либо из заказов.
Для API v3, описание тестового запроса расположено на странице [уведомление по умолчанию](/docs/merchant/notification/status/) (раздел Система мониторинга и автоматическое тестирование интеграции);
Для API v2, в тестовом запросе передаётся номер счёта (ucode) равный: 00000-00000-00000-00000.
## Настройки модуля
Обязательным набором настроек модуля, которые пользователь может менять, являются:
- Идентификатор магазина (для API v2, v3);
- Региональный код магазина (для API v2);
- API ключ магазина (для API v2, v3);
- Включить/выключить тестовый режим (для API v2);
- Описание способа оплаты (текст, который отображается в описании способа оплаты в процессе выбора способа оплаты при оформлении заказа в магазине, для API v2, v3).
Опционально, в настройках модуля может быть предусмотрен статус, на который следует изменить статус заказа, при получении информации
об оплате, а также адрес эл. почты администратора магазина, на который следует отправлять отчёты, в случае возникновения ошибок в работе модуля.
При наличие технической возможности CMS, модуль должен поддерживать несколько настроек таким образом, чтобы для каждой группы товара
или отдельного товара можно было бы задать параметр - какие настройки использовать для оплаты. Это требования необходимо там, где
разные товары и услуги могут быть оплачены от разных организаций.
Модуль должен поддерживать 2 языка – русский и английский.
## Прочие сведения
Логотип системы для использования в модуле: [Логотипы системы «Инвойсбокс»](https://www.invoicebox.ru/ru/press.html)
Комплект модуля
В состав модуля должны входить следующие элементы:
- Файлы модуля (архив ZIP), включая файл version.txt, в котором должна быть отражена версия модуля;
- Информация о модуле – версия(ии) CMS для которой модуль предназначен, версия(ии) CMS, на которой модуль был протестирован;
- Логотип CMS (SVG);
- Пошаговая инструкция по установке модуля включая шаги, необходимые для установки модуля, изображения, сопровождающие описательную часть;
- Пошаговая инструкция по настройке модуля, необходимые для настройки модуля, изображения, сопровождающие описательную часть;
- URL, которую следует указать в личном кабинете системы «Инвойсбокс» для передачи информации об оплате.
Исходные коды модуля должны быть загружены на github:
- [github.com/InvoiceBox](https://github.com/InvoiceBox).
Информация о модуле и инструкции должны быть размещены на ресурсах:
- [Документаиця. Готовые модули для CMS](https://docs.invoicebox.ru/docs/merchant/cms).
## phpSDK
Для упрощенной разработки и поддержания модулей в актуальном состоянии, рекомендуется использование [phpSDK](/docs/merchant/sdk/php/).
## Общие требования к обновлению старых версий модулей
1. Обновление модулей в соответствии с актуальными версиями CMS;
2. Обновление логотип и наименование платёжной системы - Инвойсбокс, Инвойсбокс (б, b - маленькие);
3. Обновление инструкций по установке и настройке модулей;
4. Реализация функций возврата платежа, если такие функции поддерживает CMS;
---
[Проект на github](https://github.com/InvoiceBox/)
## Что подготовить на сайте
| Страница | Зачем нужна |
|---|---|
| Страница с виджетом | здесь стоит код и покупатель вводит свои данные; подойдёт любая, даже главная |
| Страница завершения | сюда виджет вернёт покупателя и после успешной оплаты, и после неудачной. Её адрес указывается в настройках виджета — полезно описать на ней, что делать дальше |
## Настройки виджета
Все параметры задаются в [конструкторе](/widgets/constructor/); ниже — что каждый из них меняет. Если код виджета придётся править руками — например, подставлять номер заказа из своей системы, — смотрите [справочник параметров](/widgets/reference/): там перечислены поля кода, состав заказа и значения, которые они принимают.
| Настройка | Что задаёт | Когда нужна |
|---|---|---|
| Что оплачивают | заранее заданный состав заказа либо свободная сумма | состав — для товаров и услуг с известной ценой; свободная сумма — для пополнения баланса и абонентской платы |
| Текст на кнопке | подпись кнопки виджета | набор текстов расширяется по запросу в [поддержку](https://www.invoicebox.ru/ru/contacts) |
| Дополнительные поля | что покупатель заполнит сам: номер заказа, фамилия и имя, телефон, почта, количество | хотя бы одно из двух — почта или телефон — обязательно: по ним уходят счёт и документы |
| Тип плательщика | физическое лицо, организация или ИП, выбор покупателем | для оплаты от организаций и ИП выбирайте второй вариант: тогда формируется счёт и закрывающие документы |
| Код товара или услуги | ваш идентификатор заказа, договора или артикула | обязателен: по нему вы узнаёте платёж в своей системе |
| Ссылка возврата | адрес страницы завершения оплаты | заполняется всегда, иначе покупателю некуда вернуться |
| Оплачиваемые позиции | название, количество, цена и ставка НДС каждой позиции | минимум одна позиция; ставки — в [справочнике](/docs/dictionary/tag1199/) |
| Выбор одной позиции | покупатель выбирает один вариант из списка | удобно для тарифов: перечислите варианты, покупатель отметит нужный |
| Открывать в новом окне | форма открывается в новой вкладке или в текущей | снимите отметку, если хотите оставить покупателя на странице |
## Что важно знать до вставки
Сумма и состав заказа приходят из браузера покупателя и не подписаны — их можно изменить в браузере
до отправки. Это осознанное упрощение ради быстрого старта, но оно накладывает обязанность: получив
[уведомление об оплате](/docs/merchant/notification/status/), сверяйте сумму с той, которую ожидали.
Если цену определяет только ваш сервер, надёжнее создавать заказы
[через API](/docs/merchant/order/create/). Подробно — [Безопасность виджета](/widgets/security/).
Прежний конструктор на [widget.invoicebox.ru](https://widget.invoicebox.ru/?utm_source=docs)
продолжает работать: код, собранный там и в конструкторе портала, одинаковый.
### Примеры виджетов
Ниже — живые виджеты в песочнице портала: та же форма, что увидит покупатель на вашем сайте.
Собраны они на демо-магазине документации, поэтому оплата ничего не спишет. Свой виджет
собирается в [конструкторе](/widgets/constructor/) — настройки слева, код справа.
**Счёт организации или ИП.** Состав задан заранее, покупатель вводит только реквизиты. Так выставляют счёт за услуги по договору.
**Оплата товара с количеством.** Покупатель меняет количество, сумма пересчитывается на месте.
**Выбор из нескольких позиций.** Покупатель выбирает тариф или товар из списка.
**Пополнение баланса.** Сумму вводит покупатель — подходит для депозитов и абонентской платы.
---
---
# Модули для CMS
# Готовые модули для CMS
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления сайтом (CMS) | Версия | Лицензия CMS/Модуля | Детали
|------------------------------------------------------------------|---------------|-------------------------------| ---------------------------------
| | > 16.x | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/1c-bitrix/)
| | > 1.2.x | Платная | [Смотреть »](/docs/merchant/cms/aspro/)
| | > 6.1.x | Бесплатный | [Смотреть »](/docs/merchant/cms/woocommerce/)
| | Все | Условно-бесплатный/Бесплатный | [Смотреть »](/docs/merchant/cms/tilda/)
| | InSales | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/insales/)
| | VirtualityCMS | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/vicms/)
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | > 5.* | Бесплатный |[Смотреть »](/docs/merchant/cms/joomshopping/)
| | Virtuema rt | Бесплатный |[Смотреть »](/docs/merchant/cms/virtuemart/)
| | --- | --- |
| | --- | --- |
| | 2.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv2/)
| | 3.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv3/)
| | --- | --- |
| | 8.X | Бесплатный |[Смотреть »](/docs/merchant/cms/prestashop/)
| | --- | --- |
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
## Читайте также
- [Требования к разработке расширений](/docs/merchant/cms/requirements/)
---
# Получение отгрузки
# Получение отгрузки
Отгрузки читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/billing/api/order/shipment`
- тело ответа - коллекция объектов [ShipmentResponse](/docs/merchant/order/shipment_create/#shipmentresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
#### Пример запроса и ответа
```http
GET /v3/billing/api/order/shipment?id=371723
```
Пример запроса с фильтром по id заказа
```http
GET /v3/billing/api/order/shipment?orderId=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по id магазина
```http
GET /v3/billing/api/order/shipment?merchantId=21827364-196a-1178-839a-82469489d6d7
```
---
Ответ:
``` json
{
"data": [
{
"id": 616095,
"orderId": "019e51e2-3970-9852-e8c8-803c16ac9c74",
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"basketItems": [
{
"sku": "baaa27aee304c4",
"name": "Мягкая игрушка Винни Пух",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 14162,
"amountWoVat": 11608.2,
"totalAmount": 14162,
"totalVatAmount": 2553.8,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_payment"
}
],
"createdAt": "2026-05-22T23:10:55+00:00",
"type": "shipment",
"status": "completed",
"amount": 14162,
"vatAmount": 2553.8,
"final": true
}
]
}
```
---
# Модули для CRM
# Готовые модули для CRM
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления клиентами (CRM) | Версия | Лицензия CRM/Модуля | Детали
|-----------------------------------------------|------------|---------------------| ---------------------------------
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/amocrm/)
|  | любая | Платная | [Смотреть »](/docs/merchant/crm/sportcrm/)
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/retailcrm/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Изменение отгрузки
# Изменение отгрузки
Отгрузка меняется по своему идентификатору:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/shipment/:uuid` - где `:uuid` это идентификатор отгрузки
> [!NOTE]
> Идентификатор заказа при изменении не передаётся — отгрузка уже связана с заказом. Признак завершающей отгрузки задаётся при создании.
- тело запроса - объект [UpdateShipmentRequest](#updateshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/shipment/{id}
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"amount": 100.5,
"vatAmount": 100.5,
"documentNumber": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#updateshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Virtuemart
# Virtuemart (joomla)
Расширение Virtuemart для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/Virtuemart-3)
Также полезно будет установить [русификатор для расширения](https://virtuemart.net/community/translations/virtuemart/ru-RU)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Устанавливается расширение через админ панель, в пункте "загрузить и установить"
1. Перейдите в компонент "Virtuemart" —> "Способы оплаты";
2. Добавьте новый метод оплаты "Invoicebox" и заполните поля. Нажмите «Сохранить»;
3. Зайти в раздел Администрирование -> Способы оплаты, добавить новый метод оплаты с процессором invoicebox;
4. Заполнить настройки на вкладке "Общее";
5. Перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
6. Выберите необходимые статусы заказа;
7. Нажмите на кнопку "Сохранить".
### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Принятая валюта - выберите валюту рубли.
Страны - если этот параметр не важен, не изменяйте его, если вы продаете на несколько стран, то возможно вам стоит ограничить показать платежного плагина, и выбрать только для "России".
Минимальная сумма - минимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Максимальная сумма - максимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Плата за транзакцию - дополнительный фиксированный сбор при выборе данного платежного метода.
Плата или возврат процента от общей суммы - дополнительный сбор в процентах при выборе данного платежного метода.
Налог - налоговые правила для данного платежного метода.
---
# Модули для ERP
# Готовые модули для ERP-систем
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей.
| ERP-система | Версия | Лицензия ERP/Модуля | Детали
| ---------------------------------------| ---------| ------------------------------------------------------- | ---------------------------------
|  | >= 7.9.7 | Платная/Платный/Наличие лицензии api payment (21016318) | [Смотреть »](/docs/merchant/erp/iiko/)
|  | --- | Платная/Платный | [Смотреть »](/docs/merchant/erp/bnovo/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Смена магазина
Для управления выплатами и реквизитами, по которым их следует осуществить,
вы можете воспользоваться методом смены магазина. Изменить магазин можно как
у оплаченного заказа, так и у не оплаченного. При этом, изначальный магазин
должен иметь специальный тип, позволяющий в дальнейшем вносить такие изменения
в заказ.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/order-merchant-move`
- тело запроса - объект [UpdateOrderMerchantRequest](#updateordermerchantrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/order-merchant-move
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateOrderMerchantRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-----------------|-------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| orderId | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
---
---
# Joomshopping
# JoomShopping
Расширение JoomShopping для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия Joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/JoomShopping-4)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка плагина
В админ-панели пройдите в "Компоненты" —> "JoomShoppping" —> "Установка и Обновление". Выберите файл "invoicebox_joomshoppping_5.zip" и нажмите на кнопку "Загрузить".
## Настройка модуля
1. Перейдите в компонент "JoomShoppping" —> "Опции" —> "Способ оплаты";
2. Выберите способ оплаты "InvoiceBox" (Инвойсбокс) и перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
3. Выберите необходимые статусы заказа в опции "Статус заказа для успешных транзакций";
4. Нажмите на кнопку "Сохранить".
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Изображения URL - ссылка на картинку, которая выводится вместе с платежной системой.
Цена - дополнительный сбор (в процентах или фиксированная сумма) при выборе данного платежного метода.
Выберите налог - налоговые правила для данного платежного метода.
### Настройка панели Инвойсбокс:
1. Для настройки панели управления Инвойсбокс, перейдите по [ссылке](https://login.invoicebox.ru/)
2. Авторизуйтесь и пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/index.php?option=com_jshopping&controller=checkout&task=step7&act=notify&js_paymentclass=pm_invoicebox&no_lang=1&tmpl=component`
5. Сохраните изменения.
---
# Смена статуса заказа
Изменение статуса возможно только у [не процессинговых заказов](/docs/merchant/order/non-processable-order/),
а именно у заказов со свойством `processable = false`. Для изменения статуса, вы можете воспользоваться соответствующим
методом.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/:uuid/status` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderStatusRequest](#updateorderstatusrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9/status
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"status": "completed"
}
```
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "completed",
"amount": 19658.45,
"currencyId": "RUB",
"paidAt": "2026-08-01T12:31:00+03:00"
}
}
```
## UpdateOrderStatusRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|------------|-------------------------------------------|---------------------------------------------------|
| status | да | enum(4) | Статус заказа | `created`, `completed`, `expired`, `canceled` |
---
---
# Интеграции с PSS/GDS
# Готовые интеграции с PSS/GDS
Обращаем ваше внимание, что представленный перечень отлаженных интеграций неполный и содержит только наиболее актуальные варианты.
| PSS/GDS | Наименование | Детали
| ------------------------------------| ---------------------------| --------------------------------------------
|  | Сирена-Тревел/МПС (EgoPay) | [Смотреть »](/docs/merchant/pss/mps/)
|  | ТАИС TravelShop | [Смотреть »](/docs/merchant/pss/tais/)
Если вы не нашли подходящую интеграцию, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы
поможем вам соориентироваться.
---
# InSales
# Расширение Инвойсбокс для InSales
**Расширение доступно на тарифах Омни и Премиум.**
1. Чтобы подключить расширение Инвойсбокс, напишите на [почту](mailto:c-support@invbox.ru) и указать в письме номер личного кабинета InSales
2. После добавления, расширение будет доступно в личном кабинете в разделе "Расширения"
3. Нужно ввести данные для интеграции, которые будут находиться в [личном кабинете](https://business.invoicebox.ru) после регистрации и заключения договора.
Потребуется: Идентификатор магазина, Авторизационный токен (API токен в ЛК) и Ключ для проверки подписи запроса (API ключ в ЛК)
Данные для тестирования
- Идентификатор магазина
- Авторизационный токен
- Ключ для проверки подписи запроса
Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Ставка НДС должна совпадать с вашим режимом налогообложения и ставкой указанной в настройках магазина.
Остальные настройки заполняются по умолчанию, если они не заполнены в магазине.
4. В пункте “настройка” - “оформление заказа” - “оплата” появится новый вид оплаты “Инвойсбокс”
5. В настройках нужно привязать способ оплаты к способам доставки, а также выставить тип плательщиков: физ.лицо и/или юр.лицо. Если ни один способ доставки не будет привязан, то вид оплаты не появится на странице оформления заказа. По желанию сменить название и установить наценку
6. Для включения возможности оплаты юр.лицам передите в "настройки" -> "оформление заказа" -> "перейти к редактированию полей клиента" и включить пункт "Организация". ИНН — обязательное поле
Остальные настройки будут заполнены автоматически и не требуют изменений.
7. В случае успешной оплаты, покупатель будет переадресован на страницу нового заказа со статусом “оплачен”.
В случае возникновения ошибки при оплате, покупатель будет перенаправлен в магазин на страницу оформления заказа , где у него будет возможность заново перейти к оплате
---
# Prestashop
# Описание платёжного модуля для Prestashop
Платёжный модуль для интеграции платёжной системы «Инвойсбокс» и PrestaShop v8.1.2.
Реализована поддержка платёжного API. Протестировано на CMS PrestaShop v8.1.2.
Скачать модуль можно по [ссылке](https://github.com/InvoiceBox/PrestaShop-1.7)
Модуль поддерживает работы с 2 версией АПИ
Версию вашего подключения уточняйте у вашего персонального менеджера или в [службе поддержки](https://www.invoicebox.ru/ru/contacts) системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. В админ панели сайта выбираем пункт "Модули"->"Module manager"->"Загрузить модуль"
2. Далее необходимо настроить модуль
3. Здесь необходимо указать 3 обязательных параметра: id магазина для версии API v2, региональный код и ключ подписи запроса для обработки уведомлений об оплате.
4. Все необходимые параметры находится в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
### Настройка панели Инвойсбокс:
1. Авторизуйтесь в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
2. Пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/modules/invoicebox/callback.php`
5. Сохраните изменения.
---
---
# Рекуррентные платежи
# Рекуррентные платежи
При оплате заказа физическим лицом есть возможность применить рекуррентные платежи. Это позволит
сохранить токен банковской карты пользователя, для последующего списания с неё средств без участия
клиента, например, для списания средств по подписке.
## Почему для организаций регулярность устроена иначе
Списание по сохранённой карте работает, и дело не в поддержке. Владелец карты — всегда физическое
лицо: даже корпоративная карта оформлена на сотрудника. Значит расход ложится на человека, и потом
ему отчитываться перед бухгалтерией — сохранить чек, обосновать трату, приложить её к отчёту. Для
регулярных корпоративных расходов это неудобно, и чем больше сотрудников, тем неудобнее.
Поэтому организациям и ИП адресована подписка — шаблон платежа: правила, по которым покупателю
уходит счёт. Правило задаёт период, конкретный день или условие — например, снижение баланса до
порога. Дальше есть два пути:
- **заказы создаёт ваша система** — по своему расписанию вызывает
[создание заказа](/docs/merchant/order/create/), и счёт уходит покупателю как обычно;
- **заказ-подписка** — создаётся один раз с параметрами периода и условий, клиент подписывается на
неё, и счета приходят ему в нужное время без новых вызовов с вашей стороны.
Счёт по подписке доходит покупателю привычным каналом: письмом, ссылкой или
[Запросом о платеже](/docs/scenarios/rtp/) в приложение банка.
> [!NOTE]
> Параметры заказа-подписки настраиваются при подключении: публичного описания полей в контракте пока
> нет, поэтому состав правил уточняйте у [технической поддержки](https://www.invoicebox.ru/ru/contacts).
> Как только описание появится, оно встанет на эту страницу.
## Привязка карты
### Схема получения токена карты
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель->>Инвойсбокс: Подтверждение оплаты счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате и токен карты
Магазин-->>Инвойсбокс: Вызов метода отгрузки для разблокировки средств
end
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/) с указанием параметров `savePaymentData` и `clientId`.
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения подтверждает оплату.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа с указанием токена.
1. Магазин сохраняет и привязывает полученный токен к пользователю.
1. Магазин передаёт в систему «Инвойсбокс» информацию об отгрузке [через метод API](/docs/merchant/order/shipment_create/) для разблокировки средств.
### Создание заказа
Карта привязывается к покупателю в момент оплаты: [создайте заказ](/docs/merchant/order/create/) с такими
параметрами —
- `savePaymentData`, `clientId`, `paymentMethodCode` `paymentMethodAutosubmit` в [invoiceSetting](/docs/merchant/order/create/#invoicesetting)
Если заказ нужен только для привязки карты, включите режим холдирования средств — подтип заказа
`subtype` = `hold`, — чтобы затем разблокировать их.
Для оплаты товаров и услуг, эту опцию так же можно использовать, если этого требуют бизнес-процессы.
Пример:
```json
{
....
"subtype": "hold",
"invoiceSetting": {
"savePaymentData": true,
"clientId": "client-12345",
"paymentMethodCode":"acquiring",
"paymentMethodAutosubmit": true
}
}
```
Далее, клиента следует перенаправить на страницу оплаты по ссылке, полученной в параметре `paymentUrl` в
[ответе](/docs/merchant/order/create/#orderresponse) на запрос создания заказа.
После успешного холдирования (блокировки) средств, магазину будет направлено [уведомление об оплате](/docs/merchant/notification),
в котром будет находится информация о платеже в объекте [PaymentInfo](/docs/merchant/order/create/#paymentinfo), в том числе параметр
`paymentToken`, который необходимо сохранить и привязать к плательщику (пользователю) для последующего проведения платежей.
Пример:
```json
{
....
"paymentInfo": {
"paymentToken": "token-abc123",
"cardholderName": "CARDHOLDER NAME",
"expiration": "13/26",
"maskedPan": "220071**6742",
"paymentSystem": "MIR"
}
}
```
Если заказ был инициирован только для привязки карты, то необходимо разблокировать средства, путём
[создания отгрузки](/docs/merchant/order/shipment_create) с пустым набором `basketItems` и флагом `final` = `true`.
> [!IMPORTANT]
> Для заказов, используемых только для привязки карты, рекомендуется использовать небольшие суммы заказа, например,
до 1 рубля.
## Подтверждение оплаты заказов с использованием токена
Теперь можно использовать сохранённый токен для подтверждения оплаты в последующих заказах.
Для этого [создаем заказ](/docs/merchant/order/create/) и получаем его идентификатор, а затем вызываем метод подтверждения
платежа с указанием платёжного токена:
- метод: `POST`
- ресурс: `/v3/billing/api/payment/confirm`
- тело запроса - объект [ConfirmRequest](#confirmrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
## ConfirmRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|--------------|--------------|--------------|-------------------------------|----------------------------------------|
| orderId | да | string | Идентификатор заказа | `0193690f-a122-d2cd-ac46-9da9e848723c` |
| type | да | string, enum | Тип подтверждения оплаты | `paymentToken` |
| paymentToken | да | string | Платёжный токен карты клиента | `cc11a4881764e0e02573f83c99811ed9` |
В случае успешной оплаты `status` заказа станет `completed`, а для подтипа `hold` — `hold`. Статуса `paid` в контракте нет: оплаченным считается только `completed` (полный перечень — на странице [работы с заказом](/docs/merchant/order/)).
## Ошибки
При использовании метода могут возникнуть следующие ошибки:
#### Пример ошибки при попытке списания средств ошибочным токеном
```json
{
"error": {
"message": "Ошибка списания средств",
"code": "invalid_argument",
"fields": []
}
}
```
#### Пример ошибки при попытке списания средств по уже оплаченному заказу
```json
{
"error": {
"message": "Заказ уже оплачен",
"code": "already_paid",
"fields": []
}
}
```
### Удаление привязанной карты
- метод: `POST`
- ресурс: `/v3/processing/api/payment-token/delete`
- тело запроса - объект [DeletePaymentTokenRequest](#deletepaymenttokenrequest)
## DeletePaymentTokenRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|--------------|--------------|--------------|-------------------------------|------------------------------------|
| clientId | да | string | Идентификатор клиента | `client-12345` |
| paymentToken | да | string | Платёжный токен карты клиента | `cc11a4881764e0e02573f83c99811ed9` |
Пример ответа в случае успешного удаления
```json
{
"data": {},
"extendedData": []
}
```
#### Пример ошибки удаления токена
```json
{
"error": {
"message": "Неверное состояние связки",
"code": "invalid_argument",
"fields": []
}
}
```
#### Пример ошибки, когда токен не найден
```json
{
"error": {
"message": "Error",
"code": "not_found",
"fields": []
}
}
```
---
# VirtualityCMS
# Расширение Инвойсбокс для VirtualityCMS
Для получения и настройки модуля, ознакомьтесь с [инструкцией на сайте VirtualityCMS](https://vicms.ru/article/invoicebox).
## Читайте также
- [Данные для интеграции](/docs/merchant/integrationdata/)
---
# Метаданные
# Метаданные заказа/элемента корзины
Передача расширенного набора данных по заказу или элементу корзины выполняется заполнением свойства заказа или элемента
корзины `metaData` в запросе [создания заказа](/docs/merchant/order/create/) и [оформления возврата](/docs/merchant/refund/create/).
По умолчанию, свойство заполняется в формате [json-ld](https://json-ld.org/). Система поддерживат типы объектов, описанные на
сайте [https://schema.org/](https://schema.org/).
## Данные бронирования авиабилетов
Для передачи данных бронирования авиаперелётов, в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [FlightReservation](https://schema.org/FlightReservation). Для каждого из сегментов полёта,
а также для каждого из пассажиров передаётся отдельный объект [FlightReservation](https://schema.org/FlightReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "FlightReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "Flight",
"flightNumber": "NDJ37S",
"provider": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"seller": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"departureAirport": {
"@type": "Airport",
"name": "Москва (Шерементьево)",
"iataCode": "SVO"
},
"departureTime": "2022-03-04T20:15:00+03:00",
"departureGate": "11",
"departureTerminal": "C",
"arrivalAirport": {
"@type": "Airport",
"name": "Санкт-Петербург (Пулково)",
"iataCode": "LED"
},
"arrivalTime": "2022-03-05T21:30:00+03:00",
"arrivalGate": "11",
"arrivalTerminal": "1"
},
"airplaneSeat": "1A",
"airplaneSeatClass": {
"@type": "AirplaneSeatClass",
"name": "Business"
},
"ticketNumber": "111-1231231239",
"ticketToken": "qrCode:AB34",
"checkinUrl": "https://checkmytrip.ru/onlinecheckin.html",
"reservedTicket": {
"@type": "flightTicket",
"underName": {
"@type": "Person",
"name": "MAKAROV ANDREY"
},
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}]
}
```
## Данные бронирования железнодорожных билетов
Для передачи данных бронирования железнодорожных билетов, в полях элементов корзины `metaData`
необходимо передать объект [TrainReservation](https://schema.org/TrainReservation) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (билета) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "trainTicket",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"gender": "male",
"nationality": "RUS",
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"coachNumber": "04",
"coachType": "Плацкартный",
"serviceClass": "3Э",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketNumber": "74363372056286",
"ticketStatus": "Оформлен",
"ticketIssueTime": "2021-05-15T12:30:21+01:00",
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
#### Пример объекта элемента корзины (услуги) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "baggageCheck",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"ticketNumber": "44363452345662",
"declaredName": "Велосипед",
"declaredValue": 100.00,
"note": "Малогабаритный багаж в специализированном купе",
"fare": 57.00,
"valueFee": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
## Данные бронирования места проживания
Для передачи данных бронирования места проживания (отель, хостел, апартаменты и пр.), в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [LodgingReservation](https://schema.org/LodgingReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Гранд Отель Европа",
"address": {
"@type": "PostalAddress",
"streetAddress": "ул. Михайловская, д. 1/7",
"addressLocality": "Санкт-Петербург",
"addressRegion": "Санкт-Петербург",
"postalCode": "191186",
"addressCountry": "ru"
},
"telephone": "+7 (812) 329-6000"
},
"checkinTime": "2021-02-21T16:00:00-08:00",
"checkoutTime": "2021-02-23T11:00:00-08:00"
}]
}
```
## Данные подписки
Для передачи данных о подписке, в полях элементов корзины `metaData`
необходимо передать объект [PaymentPlan](https://schema.org/) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (подписки) PaymentPlan
``` json
{
"@context": "https://schema.org",
"@type": "PaymentPlan",
"name": "Pro-подписка на сервис Экспресс Клиент",
"description": "Доступ к премиум-функциям в течение 1 года с ежемесячными платежами",
"billingPeriod": "P1M",
"billingIncrement": "1",
"contractStartDate": "2025-01-01",
"contractEndDate": "2026-01-01",
"price": "2990.00",
"priceCurrency": "RUB",
"provider": {
"@type": "Organization",
"name": "Экспресс Клиент",
"url": "https://expressclient.ru"
}
}
```
---
---
# Требования
# Требования к разработке расширений «Инвойсбокс» для систем управления сайтами
## Используемый протокол обмена данными (API)
Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина)
для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу:
[Инвойсбокс API v3](https://docs.invoicebox.ru).
Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен
соответствовать описанному в API. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок,
модуль должен отобразить соответствующее сообщение пользователю, данные не должны отправляться в платёжный шлюз.
В модуле должны быть предусмотрены следующие функции:
1. Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
2. Callback-скрипт для получения информации об оплате заказа;
3. Функции оформления возврата по заказу.
## Множество способов оплаты
В тех CMS, где это технически возможно, модуль должен поддерживать оформление двух способов оплаты, а именно -
оплата для физических лица (банковские карты, интернет банки и т.д.), а также оплата для юридических лиц
(оплата по счёту для организаций и ИП). В настройках модуля должна быть предусмотрена возможность выбора
используемых способов оплаты.
При выборе способа оплаты для организаций и ИП, по API должны передаваться данные организации - ИНН, КПП,
наименование, юридический адрес (при наличие данных в заказе).
Т.е. в результате установки модуля, в CMS должно появится два способа оплаты. Там где это невозможно,
способ оплаты выбирается на странице платёжного шлюза системы «Инвойсбокс».
## Идентификация модуля
Важно обратить внимание на формирование идентификатора приложения и модуля при работе с API.
В API v3 идентификатор приложения передаётся в HTTP-заголовке User-Agent.
В API v2, в параметрах платёжной формы, в обязательном порядке должно присутствовать поле с идентификатором
приложения - itransfer_cms_name.
## Параметры заказа (счёта)
Модуль обязательно должен передавать тип позиции в заказе - товар или услуга, для API V3 - более детальное
значение [см. справочник](/docs/dictionary/tag2108/);
## Callback для получения информации об оплате
Смена статуса заказа в CMS магазина происходит по факту получения информации об оплате в формате,
описанном по адресу:
Для API v3: [Уведомление по умолчанию](/docs/merchant/notification/status/);
Для API v2: [HTTP-уведомления о переводах](https://www.invoicebox.ru/ru/integration/webapi/notify/defaulthttp/).
При получении информации об оплате, модуль должен сверить подпись запроса, идентификатор магазина, валюту заказа,
сумму оплаты с суммой заказа. В случае расхождения, статус заказа менять не нужно, модуль должен
вернуть детальное описание ошибки в соответствии с форматом ответа API.
В модуле должно быть реализовано получение тестового запроса с информацией об оплате, при котором модуль
должен выдать успешный ответ в случае корректной передачи подписи запроса и идентификатора магазина.
Тестовый запрос используется для проверки корректность установки модуля и не должен приводить к смене статуса
какого-либо из заказов.
Для API v3, описание тестового запроса расположено на странице [уведомление по умолчанию](/docs/merchant/notification/status/) (раздел Система мониторинга и автоматическое тестирование интеграции);
Для API v2, в тестовом запросе передаётся номер счёта (ucode) равный: 00000-00000-00000-00000.
## Настройки модуля
Обязательным набором настроек модуля, которые пользователь может менять, являются:
- Идентификатор магазина (для API v2, v3);
- Региональный код магазина (для API v2);
- API ключ магазина (для API v2, v3);
- Включить/выключить тестовый режим (для API v2);
- Описание способа оплаты (текст, который отображается в описании способа оплаты в процессе выбора способа оплаты при оформлении заказа в магазине, для API v2, v3).
Опционально, в настройках модуля может быть предусмотрен статус, на который следует изменить статус заказа, при получении информации
об оплате, а также адрес эл. почты администратора магазина, на который следует отправлять отчёты, в случае возникновения ошибок в работе модуля.
При наличие технической возможности CMS, модуль должен поддерживать несколько настроек таким образом, чтобы для каждой группы товара
или отдельного товара можно было бы задать параметр - какие настройки использовать для оплаты. Это требования необходимо там, где
разные товары и услуги могут быть оплачены от разных организаций.
Модуль должен поддерживать 2 языка – русский и английский.
## Прочие сведения
Логотип системы для использования в модуле: [Логотипы системы «Инвойсбокс»](https://www.invoicebox.ru/ru/press.html)
Комплект модуля
В состав модуля должны входить следующие элементы:
- Файлы модуля (архив ZIP), включая файл version.txt, в котором должна быть отражена версия модуля;
- Информация о модуле – версия(ии) CMS для которой модуль предназначен, версия(ии) CMS, на которой модуль был протестирован;
- Логотип CMS (SVG);
- Пошаговая инструкция по установке модуля включая шаги, необходимые для установки модуля, изображения, сопровождающие описательную часть;
- Пошаговая инструкция по настройке модуля, необходимые для настройки модуля, изображения, сопровождающие описательную часть;
- URL, которую следует указать в личном кабинете системы «Инвойсбокс» для передачи информации об оплате.
Исходные коды модуля должны быть загружены на github:
- [github.com/InvoiceBox](https://github.com/InvoiceBox).
Информация о модуле и инструкции должны быть размещены на ресурсах:
- [Документаиця. Готовые модули для CMS](https://docs.invoicebox.ru/docs/merchant/cms).
## phpSDK
Для упрощенной разработки и поддержания модулей в актуальном состоянии, рекомендуется использование [phpSDK](/docs/merchant/sdk/php/).
## Общие требования к обновлению старых версий модулей
1. Обновление модулей в соответствии с актуальными версиями CMS;
2. Обновление логотип и наименование платёжной системы - Инвойсбокс, Инвойсбокс (б, b - маленькие);
3. Обновление инструкций по установке и настройке модулей;
4. Реализация функций возврата платежа, если такие функции поддерживает CMS;
---
[Проект на github](https://github.com/InvoiceBox/)