Cash Register API
version: 1.0.0
API для интеграции с кассовым ПО и проведения платежей через статический или динамический QR-код от Яндекс Пэй в розничных точках продаж.
В этом разделе описаны методы API. Пошаговые инструкции см. в разделе Самостоятельная интеграция.
Важно
Сейчас тестовая среда недоступна — используйте боевую среду.
Для безопасного тестирования в боевой среде менеджер интеграции предоставит вам тестовый магазин и готовый идентификатор зарегистрированного в СБП QR-кода (qrcId).
Вывод в боевую среду только после подписания договора.
Аутентификация запросов
В каждом запросе передавайте в HTTP-заголовки:
|
|
Заголовок: Выпустите его личном кабинете по инструкции. |
|
|
Заголовок: Токен кассового ПО. Получите его у менеджера интеграции. |
Если в запросе отсутствуют или переданы недействительные токены, сервер вернет статус 401 Unauthorized.
Пример запроса:
curl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \
--header 'Authorization: Api-Key <YandexPayApiKey>' \
--header 'Software-Authorization: <SoftwareAuthorization>' \
Схема взаимодействия
Подробное описание каждого шага см. в разделе Самостоятельная интеграция.
Sequence diagram
Sections
Specification
Open API
{
"openapi": "3.1.1",
"info": {
"title": "Cash Register API",
"version": "1.0.0",
"description": "API для интеграции с кассовым ПО и проведения платежей через статический или динамический [QR-код от Яндекс Пэй](../../../qr-code/index.md) в розничных точках продаж.\n\nВ этом разделе описаны методы API. Пошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../qr-code/api.md).\n\n{% note warning %}\n\nСейчас тестовая среда недоступна — используйте боевую среду.\n\nДля безопасного тестирования в боевой среде менеджер интеграции предоставит вам тестовый магазин и готовый идентификатор зарегистрированного в СБП QR-кода (`qrcId`).\n\nВывод в боевую среду только после подписания договора.\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```\n\n## Схема взаимодействия {#scheme}\n\nПодробное описание каждого шага см. в разделе [Самостоятельная интеграция](../../../qr-code/api.md).\n\n{% cut \"Sequence diagram\" %}\n\n\n\n{% endcut %}"
},
"servers": [
{
"url": "https://sandbox.pay.yandex.ru/api/merchant/cash-register",
"description": "Sandbox"
},
{
"url": "https://pay.yandex.ru/api/merchant/cash-register",
"description": "Production"
}
],
"security": [
{
"YandexPayApiKey": [],
"SoftwareAuthorization": []
}
],
"tags": [
{
"name": "Заказы",
"description": "Активация и деактивация QR-кода. Управление заказом."
},
{
"name": "QR-таблички",
"description": "Получение списка QR-табличек продавца."
}
],
"paths": {
"/v1/orders": {
"post": {
"tags": [
"Заказы"
],
"operationId": "createOrder",
"summary": "Создать заказ со статическим QR-кодом",
"description": "Активирует статический QR-код, после чего его можно отсканировать и оплатить заказ.\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"availablePaymentMethods": {
"type": "array",
"items": {
"type": "string",
"description": "Методы оплаты, которые будут доступны покупателю в платежной форме Яндекс Пэй.\n\nНе передавайте это поле, если нет необходимости отключать методы оплаты.\n\nВозможные варианты:\n- поле не передано — доступны все методы;\n- `[\"CARD\", \"SPLIT\"]` — доступны все методы;\n- `[\"SPLIT\"]` — доступны все методы;\n- `[\"CARD\"]` — доступны все методы, кроме Сплита.\n\nЕсли Сплит отключен в [личном кабинете](https://console.pay.yandex.ru), он не будет доступен для оплаты, даже если указан в `availablePaymentMethods`.",
"enum": [
"CARD",
"SPLIT"
]
},
"minItems": 1
},
"billingPhone": {
"type": "string",
"description": "Номер телефона клиента.\n\nИспользуется для упрощения авторизации, а также может увеличить вероятность одобрения по Сплиту.\n\nНомер телефона должен начинаться с +7, далее 10 цифр.",
"minLength": 12,
"maxLength": 12,
"example": "+79999999999",
"pattern": "^\\+7\\d{10}$"
},
"extensions": {
"type": "object",
"description": "Дополнительные параметры для оформления заказа:\n\n- `billingReport` — информация о месте и авторе оформления заказа;\n- `branchId` — идентификатор точки продаж в системе продавца;\n- `managerId` — идентификатор кассира в системе продавца.\n\n```json\n{\n \"extensions\": {\n \"billingReport\": {\n \"branchId\": \"01967cb8-f2c4-7293-9027-2976830c9485\",\n \"managerId\": \"01967cb9-67b9-7942-99c2-bf95331d137d\"\n }\n }\n}\n```",
"properties": {
"billingReport": {
"type": "object",
"description": "Информация о месте и авторе оформления заказа.",
"properties": {
"branchId": {
"type": "string",
"description": "Идентификатор точки продаж в системе продавца.",
"maxLength": 2048,
"example": "01967cb8-f2c4-7293-9027-2976830c9485"
},
"managerId": {
"type": "string",
"description": "Идентификатор кассира в системе продавца.",
"maxLength": 2048,
"example": "01967cb9-67b9-7942-99c2-bf95331d137d"
}
}
}
}
},
"orderSource": {
"type": "string",
"description": "Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.\n\n- `WEBSITE` — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.\n\n- `APP` — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.\n\n- `CRM` — Ссылка на оплату сформирована менеджером в CRM или другой админке.\n\n- `CASH_REGISTER` — Ссылка на оплату сформирована для отображения на оффлайн-кассе.\n\n- `CMS_PLUGIN` — Ссылка на оплату сформирована в плагине для CMS.",
"enum": [
"WEBSITE",
"APP",
"CRM",
"CASH_REGISTER",
"CMS_PLUGIN"
]
},
"purpose": {
"type": "string",
"description": "Назначение платежа.",
"maxLength": 140,
"example": "Оплата по заказу 12345"
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
},
{
"type": "object",
"required": [
"qrcId"
],
"properties": {
"qrcId": {
"type": "string",
"description": "Идентификатор зарегистрированного в СБП QR-кода.",
"maxLength": 32,
"example": "AD1000670LSS7DN18SJQDNP4B05KLJL2"
},
"ttl": {
"type": "integer",
"description": "Время жизни QR-кода в секундах.",
"minimum": 180,
"maximum": 1200,
"default": 600
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Заказ создан.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "`paymentUrl` — ссылка на оплату заказа.\n\n```json\n{\n \"data\": {\n \"paymentUrl\": \"https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3\"\n }\n}\n```",
"required": [
"paymentUrl"
],
"properties": {
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
}
}
},
"code": {
"type": "integer",
"format": "int64",
"default": 200
},
"status": {
"type": "string",
"default": "success"
}
}
}
}
}
},
"400": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
},
"/v1/orders/dynamic": {
"post": {
"tags": [
"Заказы"
],
"operationId": "createDynamicOrder",
"summary": "Создать заказ с динамическим QR-кодом",
"description": "Генерирует и активирует динамический QR-код. Выведите QR-код на экран или распечатайте, после этого покупатель отсканирует его и оплатит заказ.\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"availablePaymentMethods": {
"type": "array",
"items": {
"type": "string",
"description": "Методы оплаты, которые будут доступны покупателю в платежной форме Яндекс Пэй.\n\nНе передавайте это поле, если нет необходимости отключать методы оплаты.\n\nВозможные варианты:\n- поле не передано — доступны все методы;\n- `[\"CARD\", \"SPLIT\"]` — доступны все методы;\n- `[\"SPLIT\"]` — доступны все методы;\n- `[\"CARD\"]` — доступны все методы, кроме Сплита.\n\nЕсли Сплит отключен в [личном кабинете](https://console.pay.yandex.ru), он не будет доступен для оплаты, даже если указан в `availablePaymentMethods`.",
"enum": [
"CARD",
"SPLIT"
]
},
"minItems": 1
},
"billingPhone": {
"type": "string",
"description": "Номер телефона клиента.\n\nИспользуется для упрощения авторизации, а также может увеличить вероятность одобрения по Сплиту.\n\nНомер телефона должен начинаться с +7, далее 10 цифр.",
"minLength": 12,
"maxLength": 12,
"example": "+79999999999",
"pattern": "^\\+7\\d{10}$"
},
"extensions": {
"type": "object",
"description": "Дополнительные параметры для оформления заказа:\n\n- `billingReport` — информация о месте и авторе оформления заказа;\n- `branchId` — идентификатор точки продаж в системе продавца;\n- `managerId` — идентификатор кассира в системе продавца.\n\n```json\n{\n \"extensions\": {\n \"billingReport\": {\n \"branchId\": \"01967cb8-f2c4-7293-9027-2976830c9485\",\n \"managerId\": \"01967cb9-67b9-7942-99c2-bf95331d137d\"\n }\n }\n}\n```",
"properties": {
"billingReport": {
"type": "object",
"description": "Информация о месте и авторе оформления заказа.",
"properties": {
"branchId": {
"type": "string",
"description": "Идентификатор точки продаж в системе продавца.",
"maxLength": 2048,
"example": "01967cb8-f2c4-7293-9027-2976830c9485"
},
"managerId": {
"type": "string",
"description": "Идентификатор кассира в системе продавца.",
"maxLength": 2048,
"example": "01967cb9-67b9-7942-99c2-bf95331d137d"
}
}
}
}
},
"orderSource": {
"type": "string",
"description": "Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.\n\n- `WEBSITE` — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.\n\n- `APP` — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.\n\n- `CRM` — Ссылка на оплату сформирована менеджером в CRM или другой админке.\n\n- `CASH_REGISTER` — Ссылка на оплату сформирована для отображения на оффлайн-кассе.\n\n- `CMS_PLUGIN` — Ссылка на оплату сформирована в плагине для CMS.",
"enum": [
"WEBSITE",
"APP",
"CRM",
"CASH_REGISTER",
"CMS_PLUGIN"
]
},
"purpose": {
"type": "string",
"description": "Назначение платежа.",
"maxLength": 140,
"example": "Оплата по заказу 12345"
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
},
{
"type": "object",
"properties": {
"ttl": {
"type": "integer",
"description": "Время жизни QR-кода в секундах.",
"minimum": 180,
"maximum": 43200,
"default": 600
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Заказ создан.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "`paymentUrl` — ссылка на оплату заказа.\n\n```json\n{\n \"data\": {\n \"paymentUrl\": \"https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3\"\n }\n}\n```",
"required": [
"paymentUrl"
],
"properties": {
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
}
}
},
"code": {
"type": "integer",
"format": "int64",
"default": 200
},
"status": {
"type": "string",
"default": "success"
}
}
}
}
}
},
"400": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
},
"/v1/orders/{orderId}": {
"get": {
"tags": [
"Заказы"
],
"operationId": "getOrder",
"summary": "Получить информацию о заказе",
"description": "{% note info %}\n\nОсновной способ получения информации об изменении заказа — нотификации [/webhook](../../../../custom/backend/merchant-api/webhook.md).\n\nЕсли получение нотификаций невозможно, настройте поллинг этого метода как резервный способ.\n\n{% endnote %}\n\nМетод возвращает информацию о заказе и его текущем статусе. Используйте его после создания заказа методом [/orders](./createOrder.md) или [/orders/dynamic](./createDynamicOrder.md).\n\n**Рекомендации по частоте опроса:**\n\n- Первый запрос — через 5–10 секунд после создания заказа.\n- Последующие запросы — не чаще одного раза в секунду.\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```",
"parameters": [
{
"name": "orderId",
"description": "Уникальный идентификатор заказа на стороне продавца. Должен совпадать с `orderId`, который вы передали в метод [/orders](../../../backend/cash-register/Zakazy/createOrder.md) или [/orders/dynamic](../../../backend/cash-register/Zakazy/createDynamicOrder.md).",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 45
}
}
],
"responses": {
"200": {
"description": "Информация о заказе.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"operations",
"order"
],
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
},
"order": {
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId",
"paymentStatus",
"paymentUrl"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderAmount": {
"type": "string",
"format": "double",
"description": "Полная стоимость заказа к оплате с учетом возвратов, доставки, скидок и промокодов.",
"example": "123.45"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"paymentMethod": {
"type": "object",
"description": "Данные о карте и методе оплаты.",
"required": [
"methodType"
],
"properties": {
"methodType": {
"type": "string",
"description": "Тип платежного метода:\n\n- `CARD` — карта\n- `SPLIT` — Сплит\n- `SBP` — СБП через сервисы Яндекса\n- `SPLIT_SBP` — Сплит, платежи по которому будут списываться по СБП\n- `UNIQR_REUSABLE` — Оплата статическим QR в стороннем банковском приложении\n- `UNIQR_ONETIME` — Оплата динамическим QR в стороннем банковском приложении",
"enum": [
"CARD",
"SPLIT",
"SBP",
"SPLIT_SBP",
"UNIQR_REUSABLE",
"UNIQR_ONETIME"
]
},
"cardLast4": {
"type": "string",
"description": "Последние 4 цифры номера карты."
},
"cardNetwork": {
"type": "string",
"description": "Платежная система.\n\n`UNKNOWN`, `UNDEFINED` — неизвестная платежная система. Разницы между значениями нет.",
"enum": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"MAESTRO",
"VISAELECTRON",
"VISA",
"MIR",
"UNIONPAY",
"UZCARD",
"HUMOCARD",
"UNKNOWN",
"UNDEFINED"
]
}
}
},
"paymentStatus": {
"type": "string",
"description": "Статус платежа.",
"enum": [
"PENDING",
"CAPTURED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"FAILED"
]
},
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
},
"reason": {
"type": "string",
"description": "Причина ошибки для статуса `FAILED`.",
"maxLength": 2048
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
}
}
},
"code": {
"type": "integer",
"format": "int64",
"default": 200
},
"status": {
"type": "string",
"default": "success"
}
}
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"404": {
"description": "Объект не найден.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `ORDER_NOT_FOUND` — Заказ не найден.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"ORDER_NOT_FOUND"
],
"example": "ORDER_NOT_FOUND"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
},
"/v1/orders/{orderId}/deactivate": {
"put": {
"tags": [
"Заказы"
],
"operationId": "deactivateOrder",
"summary": "Деактивировать заказ",
"description": "Деактивирует заказ и QR-код.\n\nЕсли заказ деактивирован, метод ничего не делает и возвращает успешный ответ [200 OK](#200-ok).\n\nЕсли заказ уже оплачен, возвращает [400 Bad Request](#400-bad-request) с ошибкой `ORDER_ALREADY_CAPTURED`. В таком случае [проведите возврат](../../../../qr-code/api.md#refund) методом [/orders/{orderId}/refund](./refundOrder.md).\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```",
"parameters": [
{
"name": "orderId",
"description": "Уникальный идентификатор заказа на стороне продавца. Должен совпадать с `orderId`, который вы передали в метод [/orders](../../../backend/cash-register/Zakazy/createOrder.md) или [/orders/dynamic](../../../backend/cash-register/Zakazy/createDynamicOrder.md).",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 45
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"externalOperationId"
],
"properties": {
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "0196578f-82e8-79a8-be85-53a78df70f79"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Заказ успешно деактивирован.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
},
"/v1/orders/{orderId}/refund": {
"put": {
"tags": [
"Заказы"
],
"operationId": "refundOrder",
"summary": "Вернуть деньги за заказ",
"description": "Производит [полный или частичный возврат](#refund-types) платежа. Создает операцию возврата, которая будет исполнена через некоторое время.\n\nМетод является асинхронным.\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```\n\n## Статусы и ограничения {#statuses}\n\nВозвраты доступны для платежей в одном из статусов `paymentStatus`:\n\n- `CAPTURED` — заказ успешно оплачен, средства списаны со счета плательщика;\n- `PARTIALLY_REFUNDED` — совершен частичный возврат средств за заказ.\n\nПосле успешного выполнения возврата статус платежа `paymentStatus` изменится:\n\n- на `REFUNDED`, если был произведен полный возврат;\n- на `PARTIALLY_REFUNDED`, если после совершения возврата в заказе остались позиции.\n\nЧтобы узнать результат возврата, настройте получение нотификаций [/webhook](../../../../custom/backend/merchant-api/webhook.md). Если получение нотификаций невозможно, настройте поллинг метода [/order/\\{order_id\\}/](../Zakazy/getOrder.md). \n\nНаходите нужную вам операцию по `externalOperationId` и проверяйте ее статус `status`:\n\n #|\n|| `PENDING` | Операция возврата не завершена. Запросите статус позже. ||\n|| `SUCCESS` | Операция возврата запущена успешно. Фискализируйте чек возврата. ||\n|| `FAIL` | Операция возврата не запущена. Повторно инициируйте возврат методом [/orders/{orderId}/refund](../Zakazy/refundOrder.md). ||\n|#\n\n{% note warning \"Нельзя оформить возврат, если:\" %}\n\n- сумма возврата меньше 1 рубля;\n- после возврата в заказе останется меньше 1 рубля.\n\n{% endnote %}\n\n## Виды возвратов {#refund-types}\n\nДоступен полный или частичный возврат платежа.\n\n### Полный возврат\n\nДля выполнения полного возврата передайте:\n\n- `externalOperationId` — уникальный идентификатор операции на стороне продавца;\n- `refundAmount` — сумма к возврату.\n\nКорзину возвращаемых позиций `refundCart` можно не указывать, так как возврат осуществляется на всю корзину.\n\n### Частичный возврат\n\nДля выполнения частичного возврата передайте:\n\n- `externalOperationId` — уникальный идентификатор операции на стороне продавца;\n- `refundAmount` — сумма к возврату. Должна быть равна сумме возвращаемых позиций из `refundCart`;\n- `refundCart` — корзина возвращаемых позиций.\n\nФормат `refundCart` зависит от логики возвратов, которая была выбрана при создании заказа.\n\n## Две логики возвратов {#refund-logics}\n\nCash Register API поддерживает две логики работы с возвратами. Логика определяется при [создании заказа](#create-order) по наличию в позициях корзины `cart` цены за единицу товара `unitPrice`.\n\n{% note warning \"Ограничения\" %}\n\nЕсли заказ уже создан, логика не может быть изменена.\n\nНельзя смешивать логики в одном заказе.\n\n{% endnote %}\n\nРазличия проявляются при **частичных возвратах** — когда в `refundCart` указываются конкретные позиции для возврата.\n\n#|\n|| **Виды логики** | **Базовая** | **Расширенная** ||\n|| **Когда использовать** | В корзине только позиции с целыми ценами | В корзине есть позиции с нецелыми ценами, весовые товары ||\n|| **Как включить** | В `CartItem` не указывать `unitPrice` | В `CartItem` указать `unitPrice` ||\n|| **Какие поля**\n**указывать в `refundCart`** |\n\nОдно из двух:\n\n- `quantityCount` — количество единиц товара для возврата;\n- `price` — на сколько уменьшить цену за единицу товара.\n\n|\n\n- `quantityCount` или `price`;\n- `total` — точная сумма возврата за позицию.\n\n Сумма возврата `refundAmount` должна быть равна сумме всех `total` в `refundCart.items`.\n\n||\n|| **Сумма возврата** | Считается автоматически, могут быть проблемы с округлением | Вы указываете точную сумму в `total` ||\n|#\n\n## Примеры {#refund-examples}\n\n### Базовая логика (без unitPrice) {#refund-examples-basic}\n\nРассмотрим на примере заказа `orderId = Order-123` со следующей корзиной без `unitPrice`:\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"50\", // 10 ручек по 5 рублей\n \"quantity\": {\n \"count\": \"10\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"400\", // 2 блокнота по 200 рублей\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\nВыполним несколько возвратов по очереди:\n\n- [{#T}](#refund-basic-quantity);\n- [{#T}](#refund-basic-price);\n- [{#T}](#refund-basic-full).\n\n#### Частичный возврат по количеству {#refund-basic-quantity}\n\nВернуть 2 ручки:\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-123/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-123_refund_1\",\n \"refundAmount\": \"10\",\n \"refundCart\": {\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"quantityCount\": \"2\"\n }\n ]\n }\n }'\n```\n\n**Результат:**\n\n- Возвращено: 2 ручки (`quantityCount`) на сумму 10 рублей (`refundAmount`).\n- Осталось в заказе: 8 ручек (40 рублей) и 2 блокнота (400 рублей).\n- Параметр `price` пропущен, но можно указать его прежнее значение.\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"50\",\n \"quantity\": {\n \"count\": \"10\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"40\",\n \"quantity\": {\n \"count\": \"8\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\n||\n|#\n\n#### Частичный возврат по цене {#refund-basic-price}\n\nУменьшить цену каждого блокнота на 30 рублей:\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-123/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-123_refund_2\",\n \"refundAmount\": \"60\",\n \"refundCart\": {\n \"items\": [\n {\n \"productId\": \"id-2\",\n \"price\": \"30\"\n }\n ]\n }\n }'\n```\n\n**Результат:**\n\n- Цена блокнота уменьшилась с 200 до 170 рублей — на 30 рублей (`price`).\n- Возвращено: 30 рублей * 2 блокнота = 60 рублей (`refundAmount`).\n- Осталось в заказе: 8 ручек (40 рублей) и 2 блокнота (340 рублей).\n- Параметр `quantityCount` пропущен, но можно указать его прежнее значение.\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"40\",\n \"quantity\": {\n \"count\": \"8\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"40\",\n \"quantity\": {\n \"count\": \"8\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"340\",\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\n||\n|#\n\n#### Полный возврат {#refund-basic-full}\n\nПосле двух частичных возвратов в заказе осталось: 8 ручек на сумму 40 рублей и 2 блокнота на сумму 340 рублей — всего 380 рублей.\n\nВернуть оставшуюся сумму (380 рублей):\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-123/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-123_refund_3\",\n \"refundAmount\": \"380\"\n }'\n```\n\n**Результат:** корзина пустая, возвращена вся сумма заказа.\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"40\",\n \"quantity\": {\n \"count\": \"8\"\n }\n },\n {\n \"productId\": \"id-2\",\n \"title\": \"Блокнот\",\n \"total\": \"340\",\n \"quantity\": {\n \"count\": \"2\"\n }\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": []\n}\n```\n\n||\n|#\n\n### Расширенная логика (с unitPrice) {#refund-examples-extended}\n\nРассмотрим на примере заказа `orderId = Order-456` со следующей корзиной с `unitPrice`:\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"10\", // 3 ручки по 3.33 рубля\n \"quantity\": {\n \"count\": \"3\"\n },\n \"unitPrice\": \"3.33\" // цена одной ручки\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"400\", // 500 грамм по 800 руб./кг.\n \"quantity\": {\n \"count\": \"0.5\" // 500 грамм = 0.5 кг.\n },\n \"unitPrice\": \"800\" // цена за килограмм\n }\n ]\n}\n```\n\nВыполним несколько возвратов по очереди:\n\n- [{#T}](#refund-extended-quantity);\n- [{#T}](#refund-extended-weight);\n- [{#T}](#refund-extended-price).\n\n#### Частичный возврат по количеству {#refund-extended-quantity}\n\nВернуть 1 ручку:\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-456/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-456_refund_1\",\n \"refundAmount\": \"3.33\",\n \"refundCart\": {\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"quantityCount\": \"1\",\n \"total\": \"3.33\"\n }\n ]\n }\n }'\n```\n\n**Результат:**\n\n- Возвращено: 1 ручка на сумму 3.33 рубля (`refundAmount`, `total`).\n- Осталось в заказе: 2 ручки (6.67 рубля) и 0.5 кг говядины (400 рублей).\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"10\",\n \"quantity\": {\n \"count\": \"3\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"0.5\"\n },\n \"unitPrice\": \"800\"\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"6.67\",\n \"quantity\": {\n \"count\": \"2\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"0.5\"\n },\n \"unitPrice\": \"800\"\n }\n ]\n}\n```\n\n||\n|#\n\n#### Частичный возврат весового товара {#refund-extended-weight}\n\nВернуть 100 г = 0.1 кг говядины:\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-456/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-456_refund_2\",\n \"refundAmount\": \"80\",\n \"refundCart\": {\n \"items\": [\n {\n \"productId\": \"id-3\",\n \"quantityCount\": \"0.1\",\n \"total\": \"80\"\n }\n ]\n }\n }'\n```\n\n**Результат:**\n\n- Возвращено: 0.1 кг \\* 800 руб/кг = 80 рублей (`refundAmount`, `total`).\n- Осталось в заказе: 2 ручки (6.67 рубля) и 0.4 кг говядины (320 рублей).\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"6.67\",\n \"quantity\": {\n \"count\": \"2\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"400\",\n \"quantity\": {\n \"count\": \"0.5\"\n },\n \"unitPrice\": \"800\"\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"6.67\",\n \"quantity\": {\n \"count\": \"2\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"320\",\n \"quantity\": {\n \"count\": \"0.4\"\n },\n \"unitPrice\": \"800\"\n }\n ]\n}\n```\n\n||\n|#\n\n#### Частичный возврат по цене {#refund-extended-price}\n\nУменьшить цену говядины на 100 руб/кг:\n\n```bash\ncurl -X PUT 'https://pay.yandex.ru/api/merchant/cash-register/v1/orders/Order-456/refund' \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"externalOperationId\": \"Order-456_refund_3\",\n \"refundAmount\": \"40\",\n \"refundCart\": {\n \"items\": [\n {\n \"productId\": \"id-3\",\n \"price\": \"100\",\n \"total\": \"40\"\n }\n ]\n }\n }'\n```\n\n**Результат:**\n\n- Цена говядины уменьшилась с 800 до 700 руб/кг — на 100 руб/кг (`price`).\n- Возвращено: 0.4 кг \\* 100 руб/кг = 40 рублей (`refundAmount`, `total`).\n- Осталось в заказе: 2 ручки (6.67 рубля) и 0.4 г говядины (280 рублей).\n\n#|\n|| **До возврата** | **После возврата** ||\n||\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"6.67\",\n \"quantity\": {\n \"count\": \"2\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"320\",\n \"quantity\": {\n \"count\": \"0.4\"\n },\n \"unitPrice\": \"800\"\n }\n ]\n}\n```\n\n|\n\n```json\n{\n \"items\": [\n {\n \"productId\": \"id-1\",\n \"title\": \"Шариковая ручка\",\n \"total\": \"6.67\",\n \"quantity\": {\n \"count\": \"2\"\n },\n \"unitPrice\": \"3.33\"\n },\n {\n \"productId\": \"id-3\",\n \"title\": \"Говядина\",\n \"total\": \"280\",\n \"quantity\": {\n \"count\": \"0.4\"\n },\n \"unitPrice\": \"700\"\n }\n ]\n}\n```\n\n||\n|#",
"parameters": [
{
"name": "orderId",
"description": "Уникальный идентификатор заказа на стороне продавца. Должен совпадать с `orderId`, который вы передали в метод [/orders](../../../backend/cash-register/Zakazy/createOrder.md) или [/orders/dynamic](../../../backend/cash-register/Zakazy/createDynamicOrder.md).",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 45
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"externalOperationId",
"refundAmount"
],
"properties": {
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "0196578f-c97d-78fa-a58b-ba483e05cc44"
},
"refundAmount": {
"type": "string",
"format": "double",
"description": "Сумма к возврату. Минимальная сумма возврата — 1 рубль.\n\nДля частичного возврата, `refundAmount` должен быть равен сумме возвращаемых позиций из `refundCart`.\n\nДля полного возврата `refundAmount` должен быть равен остатку суммы заказа, `refundCart` можно не указывать.",
"example": "123.45"
},
"refundCart": {
"description": "Корзина возвращаемых позиций. Можно не указывать для полного возврата.",
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"productId"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор возвращаемого товара в системе продавца.",
"maxLength": 2048,
"example": "1234567890"
},
"price": {
"type": "string",
"format": "double",
"description": "На сколько уменьшить цену за единицу товара после выполнения операции.\n\nМожет быть полезным, если необходимо вернуть часть денег за товар без изменения количества.\n\nЕсли не указывать это поле в запросе, то считается, что цена осталась прежней.\n\n**Пример:**\n\n1. Заказ состоит из одной позиции: `quantityCount: \"0.5\", price: \"100\"` — итого 50 рублей.\n2. Происходит возврат с параметром `price: \"10\"`: каждая позиция уменьшается на 10 рублей.\n3. Вернется `quantityCount * price = 5 рублей`, заказ станет состоять из одной позиции, `quantityCount: \"0.5\", price: \"90\"` — итого 45 рублей.",
"example": "123.45"
},
"quantityCount": {
"type": "string",
"format": "double",
"description": "Количество единиц товара, которое необходимо вернуть. Если не указывать это поле в запросе, то считается, что количество не изменилось.",
"example": "123.45"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма возврата за позицию. Используется в [расширенной логике возвратов](#refund-logics).",
"example": "123.45"
}
}
},
"minItems": 1
}
}
},
"branchId": {
"type": "string",
"description": "Идентификатор точки продаж в системе продавца.",
"maxLength": 2048,
"example": "01967cb8-f2c4-7293-9027-2976830c9485"
},
"managerId": {
"type": "string",
"description": "Идентификатор менеджера в системе продавца.",
"maxLength": 2048,
"example": "01967cb9-67b9-7942-99c2-bf95331d137d"
},
"motive": {
"type": "string",
"description": "Причина возврата.",
"maxLength": 2048
}
}
}
}
}
},
"responses": {
"200": {
"description": "Операция возврата успешно запущена.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
},
"/v1/accounts": {
"get": {
"tags": [
"QR-таблички"
],
"operationId": "getAccounts",
"summary": "Получить список активных QR табличек",
"description": "Возвращает список активных QR-табличек.\n\nЕсли в ответе статус `5XX`, повторите запрос.\n\n{% note tip %}\n\nПошаговые инструкции см. в разделе [Самостоятельная интеграция](../../../../qr-code/api.md).\n\nСкачайте OpenAPI-спецификацию в разделе [{#T}](../index.md#specification).\n\n{% endnote %}\n\n## Аутентификация запросов {#auth}\n\nВ каждом запросе передавайте в HTTP-заголовки:\n\n#|\n|| `YandexPayApiKey` | Заголовок: `Authorization: Api-Key <ключ>`.\n\nВыпустите его [личном кабинете](https://console.pay.yandex.ru/settings) по [инструкции](../../../../qr-code/api#merchant-api-keys). ||\n|| `SoftwareAuthorization` | Заголовок: `Software-Authorization: <ключ>`.\n\nТокен кассового ПО. Получите его у менеджера интеграции. ||\n|#\n\nЕсли в запросе отсутствуют или переданы недействительные токены, сервер вернет статус `401 Unauthorized`.\n\n**Пример запроса:**\n\n```bash\ncurl https://pay.yandex.ru/api/merchant/cash-register/v1/accounts \\\n --header 'Authorization: Api-Key <YandexPayApiKey>' \\\n --header 'Software-Authorization: <SoftwareAuthorization>' \\\n```",
"responses": {
"200": {
"description": "Список активных QR-табличек продавца.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "Список активных QR-табличек продавца.",
"items": {
"type": "object",
"description": "QR-табличка.",
"required": [
"qrcId",
"name"
],
"properties": {
"qrcId": {
"type": "string",
"description": "Идентификатор зарегистрированного в СБП QR-кода.",
"maxLength": 32,
"example": "AD1000670LSS7DN18SJQDNP4B05KLJL2"
},
"name": {
"type": "string",
"description": "Название QR-таблички.",
"example": "QR табличка - ID 123456"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"401": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"429": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"500": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
}
},
"components": {
"schemas": {
"QrcId": {
"type": "string",
"description": "Идентификатор зарегистрированного в СБП QR-кода.",
"maxLength": 32,
"example": "AD1000670LSS7DN18SJQDNP4B05KLJL2"
},
"Currency": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"OrderSource": {
"type": "string",
"description": "Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.\n\n- `WEBSITE` — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.\n\n- `APP` — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.\n\n- `CRM` — Ссылка на оплату сформирована менеджером в CRM или другой админке.\n\n- `CASH_REGISTER` — Ссылка на оплату сформирована для отображения на оффлайн-кассе.\n\n- `CMS_PLUGIN` — Ссылка на оплату сформирована в плагине для CMS.",
"enum": [
"WEBSITE",
"APP",
"CRM",
"CASH_REGISTER",
"CMS_PLUGIN"
]
},
"PaymentMethod": {
"type": "object",
"description": "Данные о карте и методе оплаты.",
"required": [
"methodType"
],
"properties": {
"methodType": {
"type": "string",
"description": "Тип платежного метода:\n\n- `CARD` — карта\n- `SPLIT` — Сплит\n- `SBP` — СБП через сервисы Яндекса\n- `SPLIT_SBP` — Сплит, платежи по которому будут списываться по СБП\n- `UNIQR_REUSABLE` — Оплата статическим QR в стороннем банковском приложении\n- `UNIQR_ONETIME` — Оплата динамическим QR в стороннем банковском приложении",
"enum": [
"CARD",
"SPLIT",
"SBP",
"SPLIT_SBP",
"UNIQR_REUSABLE",
"UNIQR_ONETIME"
]
},
"cardLast4": {
"type": "string",
"description": "Последние 4 цифры номера карты."
},
"cardNetwork": {
"type": "string",
"description": "Платежная система.\n\n`UNKNOWN`, `UNDEFINED` — неизвестная платежная система. Разницы между значениями нет.",
"enum": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"MAESTRO",
"VISAELECTRON",
"VISA",
"MIR",
"UNIONPAY",
"UZCARD",
"HUMOCARD",
"UNKNOWN",
"UNDEFINED"
]
}
}
},
"PaymentStatus": {
"type": "string",
"description": "Статус платежа.",
"enum": [
"PENDING",
"CAPTURED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"FAILED"
]
},
"AvailablePaymentMethod": {
"type": "string",
"description": "Методы оплаты, которые будут доступны покупателю в платежной форме Яндекс Пэй.\n\nНе передавайте это поле, если нет необходимости отключать методы оплаты.\n\nВозможные варианты:\n- поле не передано — доступны все методы;\n- `[\"CARD\", \"SPLIT\"]` — доступны все методы;\n- `[\"SPLIT\"]` — доступны все методы;\n- `[\"CARD\"]` — доступны все методы, кроме Сплита.\n\nЕсли Сплит отключен в [личном кабинете](https://console.pay.yandex.ru), он не будет доступен для оплаты, даже если указан в `availablePaymentMethods`.",
"enum": [
"CARD",
"SPLIT"
]
},
"Error": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
"BadRequestErrorReasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"NotFoundErrorReasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `ORDER_NOT_FOUND` — Заказ не найден.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"ORDER_NOT_FOUND"
],
"example": "ORDER_NOT_FOUND"
},
"UnauthorizedErrorReasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"Cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"CartTotal": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
},
"CartItem": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
},
"ItemQuantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"CreateOrder": {
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"availablePaymentMethods": {
"type": "array",
"items": {
"type": "string",
"description": "Методы оплаты, которые будут доступны покупателю в платежной форме Яндекс Пэй.\n\nНе передавайте это поле, если нет необходимости отключать методы оплаты.\n\nВозможные варианты:\n- поле не передано — доступны все методы;\n- `[\"CARD\", \"SPLIT\"]` — доступны все методы;\n- `[\"SPLIT\"]` — доступны все методы;\n- `[\"CARD\"]` — доступны все методы, кроме Сплита.\n\nЕсли Сплит отключен в [личном кабинете](https://console.pay.yandex.ru), он не будет доступен для оплаты, даже если указан в `availablePaymentMethods`.",
"enum": [
"CARD",
"SPLIT"
]
},
"minItems": 1
},
"billingPhone": {
"type": "string",
"description": "Номер телефона клиента.\n\nИспользуется для упрощения авторизации, а также может увеличить вероятность одобрения по Сплиту.\n\nНомер телефона должен начинаться с +7, далее 10 цифр.",
"minLength": 12,
"maxLength": 12,
"example": "+79999999999",
"pattern": "^\\+7\\d{10}$"
},
"extensions": {
"type": "object",
"description": "Дополнительные параметры для оформления заказа:\n\n- `billingReport` — информация о месте и авторе оформления заказа;\n- `branchId` — идентификатор точки продаж в системе продавца;\n- `managerId` — идентификатор кассира в системе продавца.\n\n```json\n{\n \"extensions\": {\n \"billingReport\": {\n \"branchId\": \"01967cb8-f2c4-7293-9027-2976830c9485\",\n \"managerId\": \"01967cb9-67b9-7942-99c2-bf95331d137d\"\n }\n }\n}\n```",
"properties": {
"billingReport": {
"type": "object",
"description": "Информация о месте и авторе оформления заказа.",
"properties": {
"branchId": {
"type": "string",
"description": "Идентификатор точки продаж в системе продавца.",
"maxLength": 2048,
"example": "01967cb8-f2c4-7293-9027-2976830c9485"
},
"managerId": {
"type": "string",
"description": "Идентификатор кассира в системе продавца.",
"maxLength": 2048,
"example": "01967cb9-67b9-7942-99c2-bf95331d137d"
}
}
}
}
},
"orderSource": {
"type": "string",
"description": "Поверхность, на которой инициализировали создание заказа. Необходимо для последующей аналитики.\n\n- `WEBSITE` — Кнопка размещена на сайте. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя на сайте.\n\n- `APP` — Кнопка размещена в мобильном приложении. Ссылка на оплату сформировалась после действий (нажатия кнопки) пользователя в приложении.\n\n- `CRM` — Ссылка на оплату сформирована менеджером в CRM или другой админке.\n\n- `CASH_REGISTER` — Ссылка на оплату сформирована для отображения на оффлайн-кассе.\n\n- `CMS_PLUGIN` — Ссылка на оплату сформирована в плагине для CMS.",
"enum": [
"WEBSITE",
"APP",
"CRM",
"CASH_REGISTER",
"CMS_PLUGIN"
]
},
"purpose": {
"type": "string",
"description": "Назначение платежа.",
"maxLength": 140,
"example": "Оплата по заказу 12345"
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
},
"GetOrderResultData": {
"type": "object",
"required": [
"operations",
"order"
],
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
},
"order": {
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId",
"paymentStatus",
"paymentUrl"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderAmount": {
"type": "string",
"format": "double",
"description": "Полная стоимость заказа к оплате с учетом возвратов, доставки, скидок и промокодов.",
"example": "123.45"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"paymentMethod": {
"type": "object",
"description": "Данные о карте и методе оплаты.",
"required": [
"methodType"
],
"properties": {
"methodType": {
"type": "string",
"description": "Тип платежного метода:\n\n- `CARD` — карта\n- `SPLIT` — Сплит\n- `SBP` — СБП через сервисы Яндекса\n- `SPLIT_SBP` — Сплит, платежи по которому будут списываться по СБП\n- `UNIQR_REUSABLE` — Оплата статическим QR в стороннем банковском приложении\n- `UNIQR_ONETIME` — Оплата динамическим QR в стороннем банковском приложении",
"enum": [
"CARD",
"SPLIT",
"SBP",
"SPLIT_SBP",
"UNIQR_REUSABLE",
"UNIQR_ONETIME"
]
},
"cardLast4": {
"type": "string",
"description": "Последние 4 цифры номера карты."
},
"cardNetwork": {
"type": "string",
"description": "Платежная система.\n\n`UNKNOWN`, `UNDEFINED` — неизвестная платежная система. Разницы между значениями нет.",
"enum": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"MAESTRO",
"VISAELECTRON",
"VISA",
"MIR",
"UNIONPAY",
"UZCARD",
"HUMOCARD",
"UNKNOWN",
"UNDEFINED"
]
}
}
},
"paymentStatus": {
"type": "string",
"description": "Статус платежа.",
"enum": [
"PENDING",
"CAPTURED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"FAILED"
]
},
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
},
"reason": {
"type": "string",
"description": "Причина ошибки для статуса `FAILED`.",
"maxLength": 2048
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
}
}
},
"RefundOrderResultData": {
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
}
},
"RefundCart": {
"type": "object",
"required": [
"items"
],
"description": "Корзина возвращаемых позиций. Можно не указывать для полного возврата.",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"productId"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор возвращаемого товара в системе продавца.",
"maxLength": 2048,
"example": "1234567890"
},
"price": {
"type": "string",
"format": "double",
"description": "На сколько уменьшить цену за единицу товара после выполнения операции.\n\nМожет быть полезным, если необходимо вернуть часть денег за товар без изменения количества.\n\nЕсли не указывать это поле в запросе, то считается, что цена осталась прежней.\n\n**Пример:**\n\n1. Заказ состоит из одной позиции: `quantityCount: \"0.5\", price: \"100\"` — итого 50 рублей.\n2. Происходит возврат с параметром `price: \"10\"`: каждая позиция уменьшается на 10 рублей.\n3. Вернется `quantityCount * price = 5 рублей`, заказ станет состоять из одной позиции, `quantityCount: \"0.5\", price: \"90\"` — итого 45 рублей.",
"example": "123.45"
},
"quantityCount": {
"type": "string",
"format": "double",
"description": "Количество единиц товара, которое необходимо вернуть. Если не указывать это поле в запросе, то считается, что количество не изменилось.",
"example": "123.45"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма возврата за позицию. Используется в [расширенной логике возвратов](#refund-logics).",
"example": "123.45"
}
}
},
"minItems": 1
}
}
},
"RefundCartItem": {
"type": "object",
"required": [
"productId"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор возвращаемого товара в системе продавца.",
"maxLength": 2048,
"example": "1234567890"
},
"price": {
"type": "string",
"format": "double",
"description": "На сколько уменьшить цену за единицу товара после выполнения операции.\n\nМожет быть полезным, если необходимо вернуть часть денег за товар без изменения количества.\n\nЕсли не указывать это поле в запросе, то считается, что цена осталась прежней.\n\n**Пример:**\n\n1. Заказ состоит из одной позиции: `quantityCount: \"0.5\", price: \"100\"` — итого 50 рублей.\n2. Происходит возврат с параметром `price: \"10\"`: каждая позиция уменьшается на 10 рублей.\n3. Вернется `quantityCount * price = 5 рублей`, заказ станет состоять из одной позиции, `quantityCount: \"0.5\", price: \"90\"` — итого 45 рублей.",
"example": "123.45"
},
"quantityCount": {
"type": "string",
"format": "double",
"description": "Количество единиц товара, которое необходимо вернуть. Если не указывать это поле в запросе, то считается, что количество не изменилось.",
"example": "123.45"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма возврата за позицию. Используется в [расширенной логике возвратов](#refund-logics).",
"example": "123.45"
}
}
},
"Order": {
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId",
"paymentStatus",
"paymentUrl"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderAmount": {
"type": "string",
"format": "double",
"description": "Полная стоимость заказа к оплате с учетом возвратов, доставки, скидок и промокодов.",
"example": "123.45"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"paymentMethod": {
"type": "object",
"description": "Данные о карте и методе оплаты.",
"required": [
"methodType"
],
"properties": {
"methodType": {
"type": "string",
"description": "Тип платежного метода:\n\n- `CARD` — карта\n- `SPLIT` — Сплит\n- `SBP` — СБП через сервисы Яндекса\n- `SPLIT_SBP` — Сплит, платежи по которому будут списываться по СБП\n- `UNIQR_REUSABLE` — Оплата статическим QR в стороннем банковском приложении\n- `UNIQR_ONETIME` — Оплата динамическим QR в стороннем банковском приложении",
"enum": [
"CARD",
"SPLIT",
"SBP",
"SPLIT_SBP",
"UNIQR_REUSABLE",
"UNIQR_ONETIME"
]
},
"cardLast4": {
"type": "string",
"description": "Последние 4 цифры номера карты."
},
"cardNetwork": {
"type": "string",
"description": "Платежная система.\n\n`UNKNOWN`, `UNDEFINED` — неизвестная платежная система. Разницы между значениями нет.",
"enum": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"MAESTRO",
"VISAELECTRON",
"VISA",
"MIR",
"UNIONPAY",
"UZCARD",
"HUMOCARD",
"UNKNOWN",
"UNDEFINED"
]
}
}
},
"paymentStatus": {
"type": "string",
"description": "Статус платежа.",
"enum": [
"PENDING",
"CAPTURED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"FAILED"
]
},
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
},
"reason": {
"type": "string",
"description": "Причина ошибки для статуса `FAILED`.",
"maxLength": 2048
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
},
"OrderOperation": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
},
"Account": {
"type": "object",
"description": "QR-табличка.",
"required": [
"qrcId",
"name"
],
"properties": {
"qrcId": {
"type": "string",
"description": "Идентификатор зарегистрированного в СБП QR-кода.",
"maxLength": 32,
"example": "AD1000670LSS7DN18SJQDNP4B05KLJL2"
},
"name": {
"type": "string",
"description": "Название QR-таблички.",
"example": "QR табличка - ID 123456"
}
}
}
},
"securitySchemes": {
"YandexPayApiKey": {
"type": "apiKey",
"description": "API-ключ Yandex Pay API - https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/#auth",
"name": "Authorization",
"in": "header"
},
"SoftwareAuthorization": {
"type": "apiKey",
"description": "API-ключ кассового программного обеспечения (КПО). Для получения такого ключа необходимо обратиться в поддержку",
"name": "Software-Authorization",
"in": "header"
}
},
"parameters": {
"OrderID": {
"name": "orderId",
"description": "Уникальный идентификатор заказа на стороне продавца. Должен совпадать с `orderId`, который вы передали в метод [/orders](../../../backend/cash-register/Zakazy/createOrder.md) или [/orders/dynamic](../../../backend/cash-register/Zakazy/createDynamicOrder.md).",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 45
}
}
},
"responses": {
"CreateOrderResult": {
"description": "Заказ создан.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "`paymentUrl` — ссылка на оплату заказа.\n\n```json\n{\n \"data\": {\n \"paymentUrl\": \"https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3\"\n }\n}\n```",
"required": [
"paymentUrl"
],
"properties": {
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
}
}
},
"code": {
"type": "integer",
"format": "int64",
"default": 200
},
"status": {
"type": "string",
"default": "success"
}
}
}
}
}
},
"GetOrderResult": {
"description": "Информация о заказе.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"operations",
"order"
],
"properties": {
"operations": {
"type": "array",
"items": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
},
"order": {
"type": "object",
"required": [
"cart",
"currencyCode",
"orderId",
"paymentStatus",
"paymentUrl"
],
"properties": {
"cart": {
"type": "object",
"description": "Корзина.\n\nЕсли в корзине есть позиции с нецелыми ценами (3 ручки за 10 рублей) или весовые товары (500 г. говядины), **для всех позиций в корзине** добавьте цену за единицу товара `unitPrice`. Это избавит от проблем с округлением, например, при возврате.",
"required": [
"items",
"total"
],
"properties": {
"items": {
"type": "array",
"description": "Список позиций в заказе.",
"minItems": 1,
"items": {
"type": "object",
"required": [
"productId",
"quantity",
"title",
"total"
],
"properties": {
"productId": {
"type": "string",
"description": "Идентификатор товара в системе продавца. В заказе все `productId` должны быть уникальными.",
"maxLength": 2048,
"example": "1234567890"
},
"quantity": {
"type": "object",
"description": "Количество единиц товара в позиции.",
"required": [
"count"
],
"properties": {
"count": {
"type": "string",
"format": "double",
"description": "Количество единиц товара в позиции.",
"example": "123.45"
}
}
},
"title": {
"type": "string",
"description": "Наименование товара.",
"maxLength": 2048,
"example": "Хлеб"
},
"total": {
"type": "string",
"format": "double",
"description": "Сумма позиции с учетом скидок.",
"example": "123.45"
},
"description": {
"type": "string",
"description": "Описание товара.",
"maxLength": 2048
},
"unitPrice": {
"type": "string",
"format": "double",
"description": "Цена за единицу товара. Используется в [расширенной логике возвратов](#refund-logics).\n\nПримеры: \n\n- `5.50` — 5 рублей 50 копеек за 1 ручку;\n- `800` — 800 рублей за килограмм мяса.",
"example": "123.45"
}
}
}
},
"total": {
"type": "object",
"description": "Итоговая информация о стоимости заказа.",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"format": "double",
"description": "Сумма корзины с учетом всех скидок. Должна быть больше или равна 1.",
"example": "123.45",
"minimum": 1
}
}
}
}
},
"currencyCode": {
"type": "string",
"description": "Трехбуквенный код валюты (ISO 4217).",
"enum": [
"RUB"
],
"default": "RUB",
"example": "RUB"
},
"orderAmount": {
"type": "string",
"format": "double",
"description": "Полная стоимость заказа к оплате с учетом возвратов, доставки, скидок и промокодов.",
"example": "123.45"
},
"orderId": {
"type": "string",
"description": "Идентификатор заказа в системе продавца.",
"maxLength": 45,
"example": "01963e94-7457-74da-8739-fa7ea310a255"
},
"paymentMethod": {
"type": "object",
"description": "Данные о карте и методе оплаты.",
"required": [
"methodType"
],
"properties": {
"methodType": {
"type": "string",
"description": "Тип платежного метода:\n\n- `CARD` — карта\n- `SPLIT` — Сплит\n- `SBP` — СБП через сервисы Яндекса\n- `SPLIT_SBP` — Сплит, платежи по которому будут списываться по СБП\n- `UNIQR_REUSABLE` — Оплата статическим QR в стороннем банковском приложении\n- `UNIQR_ONETIME` — Оплата динамическим QR в стороннем банковском приложении",
"enum": [
"CARD",
"SPLIT",
"SBP",
"SPLIT_SBP",
"UNIQR_REUSABLE",
"UNIQR_ONETIME"
]
},
"cardLast4": {
"type": "string",
"description": "Последние 4 цифры номера карты."
},
"cardNetwork": {
"type": "string",
"description": "Платежная система.\n\n`UNKNOWN`, `UNDEFINED` — неизвестная платежная система. Разницы между значениями нет.",
"enum": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"MAESTRO",
"VISAELECTRON",
"VISA",
"MIR",
"UNIONPAY",
"UZCARD",
"HUMOCARD",
"UNKNOWN",
"UNDEFINED"
]
}
}
},
"paymentStatus": {
"type": "string",
"description": "Статус платежа.",
"enum": [
"PENDING",
"CAPTURED",
"REFUNDED",
"PARTIALLY_REFUNDED",
"FAILED"
]
},
"paymentUrl": {
"type": "string",
"description": "Ссылка на оплату заказа.",
"maxLength": 2048,
"example": "https://qr.nspk.ru/AD10006C35FBF1GA9IUAGIF6JCU23NVE?type=02&bank=100000000061&sum=2200&cur=RUB&crc=04A3"
},
"reason": {
"type": "string",
"description": "Причина ошибки для статуса `FAILED`.",
"maxLength": 2048
},
"metadata": {
"type": "string",
"description": "Произвольные данные по заказу для внутреннего использования.",
"maxLength": 2048
}
}
}
}
},
"code": {
"type": "integer",
"format": "int64",
"default": 200
},
"status": {
"type": "string",
"default": "success"
}
}
}
}
}
},
"DeactivateOrderResult": {
"description": "Заказ успешно деактивирован.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"RefundOrderResult": {
"description": "Операция возврата успешно запущена.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"operation"
],
"properties": {
"operation": {
"type": "object",
"description": "Операция заказа.",
"required": [
"operationId",
"operationType",
"status",
"amount"
],
"properties": {
"operationId": {
"type": "string",
"format": "uuid",
"description": "Уникальный идентификатор операции.",
"example": "019647c1-f086-750a-9b2f-7ed0fcce69d2"
},
"operationType": {
"type": "string",
"description": "Тип операции.",
"enum": [
"AUTHORIZE",
"REFUND"
]
},
"externalOperationId": {
"type": "string",
"description": "Уникальный идентификатор операции на стороне продавца.",
"maxLength": 45,
"example": "019647c2-8283-7ebe-85c8-b57c66ddc5e3"
},
"status": {
"type": "string",
"description": "Статус операции.",
"enum": [
"PENDING",
"SUCCESS",
"FAIL"
]
},
"amount": {
"type": "string",
"format": "double",
"description": "Сумма операции в фиатной валюте.",
"example": "123.45"
},
"reason": {
"type": "string",
"description": "Причина ошибки.",
"maxLength": 2048
}
}
}
}
}
}
}
}
}
},
"GetAccountsResult": {
"description": "Список активных QR-табличек продавца.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "Список активных QR-табличек продавца.",
"items": {
"type": "object",
"description": "QR-табличка.",
"required": [
"qrcId",
"name"
],
"properties": {
"qrcId": {
"type": "string",
"description": "Идентификатор зарегистрированного в СБП QR-кода.",
"maxLength": 32,
"example": "AD1000670LSS7DN18SJQDNP4B05KLJL2"
},
"name": {
"type": "string",
"description": "Название QR-таблички.",
"example": "QR табличка - ID 123456"
}
}
}
}
}
}
}
}
},
"BadRequest": {
"description": "Ошибка валидации или бизнес-логики.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `VALIDATION_ERROR` — Ошибка валидации. Тело или параметры запроса не соответствуют спецификации.\n- `QRC_ID_NOT_FOUND` — QR-код не найден, QR-табличка не привязана к продавцу.\n- `ORDER_COLLISION` — Заказ с таким идентификатором уже существует, при этом его параметры отличаются от указанных в запросе.\n- `ORDER_NOT_FOUND` — Заказ не найден.\n- `ORDER_ALREADY_CAPTURED` — Заказ уже оплачен.\n- `ORDER_NOT_CAPTURED` — Заказ не оплачен.\n- `ORDER_REFUND_COLLISION` — Операция возврата заказа уже существует, при этом ее параметры отличаются от указанных в запросе.\n- `ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND` — Запрос на частичный возврат без указания корзины. Для проведения частичного возврата заполните поле `refundCart`.\n- `ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID` — `productId` отсутствует в корзине заказа.\n- `ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID` — `productId` должен быть уникальным.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY` — Некорректная комбинация цены и количества единиц товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_PRICE_RANGE` — Неверно задана цена за единицу товара для возврата.\n- `ORDERUPDATE_INVALID_ITEM_QUANTITY` — Неверно задано количество единиц товара для возврата.\n- `ANOTHER_REFUND_IN_PROGRESS` — Другой возврат уже в процессе, дождитесь его завершения.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"VALIDATION_ERROR",
"QRC_ID_NOT_FOUND",
"ORDER_COLLISION",
"ORDER_NOT_FOUND",
"ORDER_ALREADY_CAPTURED",
"ORDER_NOT_CAPTURED",
"ORDER_REFUND_COLLISION",
"ORDER_REFUND_WITHOUT_CART_FOR_PARTIAL_REFUND",
"ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID",
"ORDERUPDATE_DUPLICATE_ITEM_PRODUCT_ID",
"ORDERUPDATE_INVALID_ITEM_PRICE_RANGE",
"ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY",
"ORDERUPDATE_INVALID_ITEM_QUANTITY",
"ANOTHER_REFUND_IN_PROGRESS"
],
"example": "VALIDATION_ERROR"
},
"reason": {
"type": "string",
"example": "Invalid cart item parameter: total = 200.5004"
}
}
}
]
}
}
}
},
"NotFound": {
"description": "Объект не найден.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `ORDER_NOT_FOUND` — Заказ не найден.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"ORDER_NOT_FOUND"
],
"example": "ORDER_NOT_FOUND"
}
}
}
]
}
}
}
},
"Unauthorized": {
"description": "Ошибка авторизации.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"fail"
],
"default": "fail"
},
"reason": {
"type": "string",
"description": "Описание ошибки."
}
}
},
{
"type": "object",
"required": [
"reasonCode"
],
"properties": {
"reasonCode": {
"type": "string",
"description": "Код ошибки:\n\n- `AUTHENTICATION_ERROR` — Ошибка авторизации. Повторно получите API-ключ.\n\nСписок кодов ошибок открытый и будет дополняться, необходимо уметь обрабатывать неизвестные коды ошибок.",
"enum": [
"AUTHENTICATION_ERROR"
],
"example": "AUTHENTICATION_ERROR"
},
"reason": {
"type": "string",
"example": "Authorization header is missing"
}
}
}
]
}
}
}
},
"TooManyRequests": {
"description": "Слишком много запросов, повторите запрос позже.\n\nЕсли ошибка сохраняется при разумном использовании API, обратитесь в поддержку."
},
"InternalServerError": {
"description": "Внутренняя ошибка сервера. Тело ответа может отсутствовать или иметь произвольный формат.\n\nПри получении статуса `5XX`, повторите запрос."
}
}
}
}
Была ли статья полезна?
Предыдущая
Следующая