API SmartPay
Независимо от способа создания смартапа (через SmartApp Code, SmartApp Graph, webhook и т. д.), вы можете использовать следующие методы для подключения приема платежей:
- Создание счета.
- Проведение платежа.
- Получение статуса.
- Подтверждение оплаты.
- Отмена счеты.
- Возврат платежа: полный и частичный.
Создание счета
Для создания счета на проведение платежа используйте запрос POST /invoices
.
Формат запроса
Параметры тела запроса:
Наименование | Описание |
---|---|
Обязательный |
Тип оплаты счета: • 0 – одностадийная оплата • 1 – двухстадийная оплата Подробнее о видах оплаты счета |
Обязательный |
В этом блоке передается вся информация о создаваемом счете |
|
Блок информации о покупателе |
Обязательный, если не передан параметр |
Email покупателя, на который будет отправлен фискальный чек (при условии, что покупатель не укажет иной email при оплате по QR-коду). Максимальная длина — 100 символов |
Обязательный, если не передан параметр |
Телефон покупателя. Максимальная длина — 50 символов |
|
Дополнительный способ связи с покупателем. Максимальная длина — 50 символов |
|
Блок информации о параметрах доставки |
Обязательный, если передается блок |
Блок, содержащий набор параметров с адресом покупателя |
Обязательный, если передается блок |
Код страны доставки в формате ISO 3166. Максимальная длина — 2 символа |
Обязательный, если передается блок |
Город покупателя. Максимальная длина — 100 символов |
Обязательный, если передается блок |
Адрес покупателя (улица, дом, квартира и т. д.). Максимальная длина — 255 символов |
Обязательный, если передается блок |
Тип доставки. Например, курьер. Максимальная длина — 50 символов |
|
Дополнительное описание для доставки. Максимальная длина — 255 символов |
|
Блок, содержащий дополнительные параметры по счету, которые можно получить потом в ответе. Можно использовать для ограничения вариантов оплаты, для задания лимитов в случае оплаты счета с предавторизацией и др. |
Обязательный, если передается блок |
Название передаваемого параметра. Максимальная длина — 100 символов |
Обязательный, если передается блок |
Значение передаваемого параметра. Максимальная длина — 500 символов Если 1. Если 2. Если 3. Если не указан Если 1. Если указано 2. Если не указано |
Обязательный |
Блок информации о заказе |
Обязательный |
Идентификатор заказа. Должен быть уникален в рамках выделенного для приложения service_id, иначе не будет создан новый invoice_id. Используется для защиты от дублирующих запросов. Максимальная длина — 50 символов |
Обязательный |
Дата и время заказа. Пример: 2020-04-29T08:17:03+03 |
|
Номер заказа для отображения покупателю и отслеживания статуса заказа. Рекомендуем сделать его максимально понятным и простым для восприятия. Максимальная длина — 50 символов |
Обязательный |
Идентификатор сервиса, полученный при выдаче токена для авторизации запроса |
Обязательный |
Сумма счета (без разделителя, в копейках). Если в запросе указывается корзина товаров, то это поле должно быть равно сумме стоимости всех товаров в корзине sum ( Например, 1 рубль передается в этом поле как 100 |
Обязательный |
Код валюты. Поддерживается только значение RUB |
Обязательный |
Краткое назначение платежа, отображается при оплате/подтверждении безакцепного списания клиентом |
Обязательный |
Описание платежа для отображения плательщику. Максимальная длина — 500 символов |
Обязательный |
Язык для текстовых полей. Поддерживается только значение ru-RU |
|
Дата истечения срока оплаты. По умолчанию на оплату отводится 20 минут от момента регистрации платежа. Если есть необходимость увеличить или уменьшить это время, нужно передать данное поле. Пример: 2020-04-29T08:17:03+03 |
|
Система налогообложения: • 0 – общая. • 1 – упрощенная, доход. • 2 – упрощенная, доход минус расход. • 3 – единый налог на вмененный доход. • 4 – единый сельскохозяйственный налог. • 5 – патентная система налогообложения. Не требуется указывать, например, при создании счета на предавторизацию. Для счетов на оплату при соответствующих настройках мерчанта можно взять значение оттуда. Рекомендуется всегда указывать для надежной оплаты |
|
Описание корзины покупок для передачи в налоговую и формирования фискального чека. Не требуется заполнять, например, при создании счета на предавторизацию. Обязательно нужно указывать в счетах на оплату, иначе оплата не состоится. Максимальная длина — 500 символов |
Обязательный |
Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа |
Обязательный |
Наименование или описание товарной позиции |
|
Дополнительные параметры, уточняющие товарную позицию |
Обязательный, если передается блок |
Название передаваемого параметра. Максимальная длина — 100 символов |
Обязательный, если передается блок |
Значение передаваемого параметра. Максимальная длина — 500 символов. Если Если Если • 1 - банковский платёжный агент; • 2 - банковский платёжный субагент; • 3 - платёжный агент; • 4 - платёжный субагент; • 5 - поверенный; • 6 - комиссионер; • 7 - иной агент |
Обязательный |
Описывает количественные характеристики определенной позиции корзины. Максимальная длина — 20 символов |
Обязательный |
Количество товаров в позиции. Для разделителя используйте точку |
Обязательный |
Единица измерения количества для значения из поля value |
Обязательный |
Стоимость определенной товарной позиции корзины (без разделителя, в копейках). Сумма стоимостей всех товарных позиций должна совпасть с общей суммой счета (order.amount). Рассчитывается как |
Обязательный |
Код валюты. Поддерживается только значение RUB |
Обязательный |
Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса |
Обязательный |
Цена одной единицы данной товарной позиции (position_id). Указывается без разделителя, в копейках |
|
Тип скидки на товарную позицию Пример: percent Максимальная длина — 20 символов |
|
Значение скидки на товарную позицию Используется для формирования фискального чека, сумму рассчитывает разработчик |
|
Тип агентской комиссии за продажу товара (применимо только для агентской схемы). Пример: agentPercent. Максимальная длина — 20 символов |
|
Значение агентской комиссии за продажу товара (применимо только для агентской схемы) |
Обязательно |
Значение ставки НДС: • 0 - без НДС • 1 - НДС по ставке 0% • 2 - НДС по ставке 10% • 3 - НДС по ставке 18% • 4 - НДС по ставке 10/110 • 5 - НДС по ставке 18/118 • 6 - НДС по ставке 20% • 7 - НДС по ставке 20/120 Значение «НДС по ставке 0%» отличается от варианта «без НДС» только формированием чека в зависимости от системы налогооблажения. По сумме налога разницы нет |
|
Сумма налога, посчитанная продавцом (без разделителя, в копейках) |
Пример тела запроса:
{
"ptype": 1,
"invoice": {
"purchaser": {
"email": "test@test.ru",
"phone": "71111111111",
"contact": "phone"
},
"delivery_info": {
"address": {
"country": "RU",
"city": "Москва",
"address": "Кутузовский проспект, 32"
},
"delivery_type": "courier",
"description": "Спросить '''Где тут Сбердевайсы?'''"
},
"invoice_params": [
{
"key": "packageName",
"value": "SbERdeVICEs"
},
{
"key": "packageKey",
"value": "ru.sberdevices.test"
}
],
"order": {
"order_id": "a952b7ee-c928-4586-bd05-d932c21f749",
"order_number": "1952",
"order_date": "2021-04-07T08:24:37.729Z",
"service_id": "13",
"amount": 79900,
"currency": "RUB",
"purpose": "Покупка продуктов",
"description": "Заказ № 22-1952. Покупка продуктов",
"language": "ru-RU",
"tax_system": 0,
"order_bundle": [
{
"position_id": 1,
"name": "Транзистор",
"item_params": [
{
"key": "_itemAttributes_supplier_info.name",
"value": "ООО Ромашка"
},
{
"key": "_itemAttributes_supplier_info.inn",
"value": "5009053292"
},
{
"key": "_itemAttributes_nomenclature",
"value": "Å\u001e13622200005881"
},
{
"key": "_itemAttributes_agent_info.type",
"value": "7"
}
],
"quantity": {
"value": 1,
"measure": "шт."
},
"item_amount": 79801,
"currency": "RUB",
"item_code": "21ff407a-fa98-11e8-80c5-0cc47a817926",
"item_price": 79801,
"discount_type": "amount",
"discount_value": 17687,
"tax_type": 6
},
{
"position_id": 2,
"name": "Тиристор",
"item_params": [
{
"key": "code",
"value": "123значение321"
},
{
"key": "pack",
"value": "100"
},
{
"key": "_itemAttributes_supplier_info.name",
"value": "ООО Платежи"
},
{
"key": "_itemAttributes_supplier_info.inn",
"value": "7730253720"
}
],
"quantity": {
"value": 1,
"measure": "шт."
},
"item_amount": 99,
"currency": "RUB",
"item_code": "21ff407c-fa98-11e8-80c5-0cc47a817926",
"item_price": 99,
"discount_type": "amount",
"discount_value": 21,
"tax_type": 6
}
]
}
}
}
Формат ответа
Параметры ответа:
Наименование | Описание |
---|---|
error | Блок, содержащий описание ошибки или ответа |
user_message | Описание кода ответа |
error_description | Техническое описание кода ответа |
error_code | Код ответа |
invoice_id | ID зарегистрированной оплаты |
Пример ответа:
{
"error": {
"error_code": "0",
"error_description": "",
"user_message": ""
},
"invoice_id": "38705"
}
Проведение платежа
Для оплаты счета используйте запрос POST /invoices/{invoice_id}
.
Параметры запроса
Наименование | Описание |
---|---|
Обязательный |
Передается как path параметр в адресе запроса. ID покупки, полученный при создании счета |
Параметры тела запроса
Наименование | Описание |
---|---|
|
Идентификаторы пользователя Обязательно указать один из идентификаторов, даже если указан user_channel: • sub_id • encrypted_sub_id • partner_client_id |
|
Канал клиента |
|
Sub клиента |
|
Зашифрованный sub клиента |
|
Идентификатор клиента, совершающего оплату в смартапе партнера |
Обязательный |
Список операций по счету |
Обязательный |
Тип операции: • payment — платежный инструмент; • prepare_payment — доступное действие клиента при оплате на платежной форме; • payment_loyalty_points — сумма лимита по заказу в копейках • recurrent_loyalty_points — сумма лимита по заказу в копейках |
|
Сервисный код операции. Зависит от типа операции. Для operation=payment указывается вариант оплаты, выбранный клиентом, например "card". Для operation=payment_loyalty_points указывается код бонусной программы, например "sbrf_spasibo". Может принимать значения: • «new» – создание нового заказа RBS; • «card» – оплата сохраненной картой; • «QR» – создание нового заказа RBS, оплата по QR; • «app2sbol» – создание заказа в СБОЛ, с переходом в СБОЛ из МП; • «invoice» – безакцептное списание • код бонусной программы |
|
Значение, соответствующее сервисному коду Для operation=payment указывается идентификатор, например для «card» указывается ID выбранной карты. Для operation=payment_loyalty_points сумма бонусных баллов, которая должна быть использована при совершении операции. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
|
Информация об устройстве |
|
Наименование операционной системы устройства. Например, iOS |
|
Версия операционной системы устройства. Например, 13.6.1 |
|
Модель устройства. Например, iPhone 7 |
|
Производитель устройства. Например, Apple |
|
Серийный номер устройства (при наличии). Например, 83c3f257-46d8-41fe-951b-f79d04e288c2 |
|
Поверхность, с которой производится вызов. Например, COMPANION |
|
Версия программного обеспечения |
|
Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Используется при "code"="new". Если адрес не указан, то он будет подставлен на стороне платежного сервиса из значения по умолчанию |
|
Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Используется при "code"="new". Если адрес не указан, то он будет подставлен на стороне платежного сервиса из значения по умолчанию |
|
Deeplink, на который требуется перенаправить пользователя после успешной оплаты через мобильное приложение. Указывается либо return_url, либо return_deeplink |
Пример тела запроса
{
"user_id": {
"partner_client_id": "2223"
},
"operations": [
{
"operation": "payment",
"code": "invoice",
"value": "167900"
}
],
"device_info": {
"device_platform_type": "iOS",
"device_platform_version": "13.6.1",
"device_model": "iPhone 7",
"device_manufacturer": "Apple",
"device_id": "83c3f257-46d8-41fe-951b-f79d04e288c2",
"surface": "SBOL",
"surface_version": "11.5.0"
},
"return_url": "https://ok",
"fail_url": "https://fail"
}
Формат ответа
Параметры ответа
Наименование | Описание |
---|---|
error | Блок, содержащий описание ошибки или ответа |
user_message | Описание кода ответа |
error_description | Техническое описание кода ответа |
error_code | Код ответа |
form_url | URL платежной формы, на который надо перенаправить браузер клиента |
deeplink | Deeplink, на который надо перенаправить клиента для оплаты в мобильном приложении |
Пример ответа
{
"error": {
"error_code": "0",
"error_description": "",
"user_message": "Средства захолдированы"
},
"form_url": "38705"
}
При завершении оплаты приходит сообщение PAY_DIALOG_FINISHED
, которое позволяет определить статус счета. Сообщение можно получить независимо от типа платежа — одностадийный или двухстадийный.
Получение статуса
После создания счета вы можете проверить, успешно ли прошел платеж. Для этого используйте следующий запрос: GET /invoices/{invoice_id}
.
Формат запроса
Параметры запроса:
Наименование | Описание |
---|---|
Обязательный |
Передается как path параметр в адресе запроса. Id счета, полученный в шаге 1 |
|
Статус счета для начала отслеживания изменений. Если при вызове запроса счет найден и статус равен значению этого параметра, то ответ отдается только при смене статуса или по таймауту |
|
Время в секундах, которое сервер будет ожидать до смены статуса счета |
Пример запроса:
curl -X GET "https://smartmarket.online.sberbank.ru/smartpay/v1/invoices/ad454ffg-6c54-4b01-90e6-d701748f0851?inv_status=executed&wait=50" -H "accept: application/json"
Формат ответа
Параметры ответа:
Наименование | Описание |
---|---|
error | Блок, содержащий описание ошибки или ответа |
user_message | Сообщение для пользователя |
error_description | Описание ошибки |
error_code | Код ответа |
invoice_id | Идентификатор счета |
invoice_date | Дата счета |
invoice_status | Текущий статус счета. Возможные значения читайте в разделе Статусы счета |
invoice | В этом блоке передается вся информация о счете |
purchaser | Блок информации о покупателе |
email | Email покупателя, на который будет отправлен фискальный чек (при условии, что покупатель не укажет иной email при оплате по QR-коду). Максимальная длина — 100 символов |
phone | Телефон покупателя. Максимальная длина — 50 символов |
contact | Дополнительный способ связи с покупателем. Максимальная длина — 50 символов |
delivery_info | Блок информации о доставке |
address | Блок информации об адресе |
country | Код страны доставки в формате ISO 3166. Максимальная длина — 2 символа |
city | Город покупателя. Максимальная длина — 100 символов |
address | Адрес покупателя (улица, дом, квартира и т.д). Максимальная длина — 255 символов |
delivery_type | Тип доставки. Максимальная длина — 50 символов |
description | Дополнительное описание для доставки. Максимальная длина — 255 символов |
invoice_params | Блок, содержащий дополнительные параметры по счету, которые были указаны в запросе POST /invoices . Используется для ограничения вариантов оплаты, для задания лимитов в случае оплаты счета с предавторизацией и др. |
key | Название параметра. Указывается в запросе POST /invoices . |
value | Значение параметра. Указывается в запросе POST /invoices .Если key=inapp_serviceparam_payment_instruments , то список разрешенных платежных инструментов при оплате счета следующий:
key=inapp_serviceparam_action_name , то название кнопки действия (ActionName) оплаты на платежной форме:
|
order | Блок информации о заказе |
order_id | Идентификатор заказа. Указывается в запросе POST /invoices |
order_number | Номер заказа в системе магазина, для клиента. Указывается в запросе POST /invoices |
order_date | Дата заказа в системе магазина, RFC 3339. Указывается в запросе POST /invoices |
service_id | ID сервиса (настраивается платежной системой и выдается пользователю платежного сервиса). Указывается в запросе POST /invoices |
amount | Сумма в минимальных единицах валюты (в копейках). Например, 123р.00коп. = 12300. Указывается в запросе POST /invoices |
currency | Валюта счета. Указывается в запросе POST /invoices |
purpose | Краткое назначение платежа. Указывается в запросе POST /invoices |
description | Описание счета. Указывается в запросе POST /invoices |
language | Язык текстовых полей. Указывается в запросе POST /invoices |
expiration_date | Дата и время окончания жизни счета, RFC 3339 Указывается в запросе POST /invoices |
payment_info | Блок информации о платеже. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} |
payment_date | Дата оплаты |
payment_id | Идентификатор платежа |
device_info | Блок информация об устройстве. Передается в запросе POST /invoices/{invoice_id} |
user_channel | Канал приема |
device_platform_type | Наименование операционной системы устройства. Указание обязательно, если "code"="app2sbol" |
device_platform_version | Версия операционной системы устройства |
device_model | Модель устройства |
device_manufacturer | Производитель устройства |
device_id | Серийный номер устройства (при наличии) |
surface | Поверхность, с которой производится вызов |
surface_version | Версия ПО |
loyalty_info | Информация по бонусам спасибо. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если при оплате были использованы бонусы спасибо |
service_code | Код бонусной программы |
service_name | Наименование бонусной программы |
change_rate | Коэффициент обмена баллов на рубли. Например, 100 баллов / 1.25 (коэффициент) = 80 руб. Будет списано 100 баллов, сумма платежа уменьшена на 80 руб. |
payment_bonus | Сумма бонусных баллов, использованная при оплате счета. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
award_bonus | Сумма средств, использованных для начисления баллов при оплате заказа. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
image | Ссылка на картинку |
masked_pan | Маскированный номер карты. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
expiry_date | Срок истечения действия карты в формате YYYYMM. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
cardholder | Имя держателя карты, указанное при оплате. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
payment_system | Наименование платёжной системы. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
payment_system_image | Логотип платежной системы |
image | Логотип карты. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
paysys | Наименование платежного оператора. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
paysys_image | Логотип платежного оператора. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
payment_way | Наименование способа оплаты. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
payment_way_code | Код способа оплаты. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
payment_way_logo | Логотип способа оплаты. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
bank_info | Блок с данными банка-эмитента. Появляется только после успешного выполнения запроса POST /invoices/{invoice_id} , если Пользователь оплатил картой |
bank_name | Наименование банка-эмитента |
bank_country_code | Код страны банка-эмитента |
bank_country_name | Наименование страны банка-эмитента |
bank_image | Ссылка на логотип банка |
image | Ссылка на картинку |
payment_methods | Блок информации о доступных Пользователю платежных инструментах |
user_message | Сообщение пользователю (необязательное) |
methods | Блок «Варианты оплаты» |
method | Код |
action | Название кнопки оплаты |
cards | Блок информации о привязанных картах (связки). Возвращается только при запросе токеном Пользователя |
card_id | Идентификатор карты |
name | Алиас карты, указанный клиентом |
loyalty_perhaps | Признак потенциальной возможности использования бонусов при оплате. Если true, то имеет смысл выполнять запрос на получение бонусов по этой карте |
loyalty | Блок с информацией по бонусам |
service_code | Код бонусной программы |
service_name | Наименование бонусной программы |
change_rate | Коэффициент обмена баллов на рубли. Например, 100 баллов / 1.25 (коэффициент) = 80 руб. Будет списано 100 баллов, сумма платежа уменьшена на 80 руб. |
balance | Баланс бонусных баллов для карты. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
min_amount | Минимальная сумма бонусных баллов, которая может быть использована при оплате заказа. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
max_amount | Максимальная сумма бонусных баллов, которая может быть использована при оплате заказа. Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350 |
action | Название кнопки оплаты в случае выбора клиентом оплаты с бонусами |
visual_amount | Отформатированная максимальная сумма бонусных баллов |
visual_label | Отформатированная максимальная сумма бонусных баллов c с текстом для отображения |
image | Ссылка на картинку |
masked_pan | Маскированный номер карты |
expiry_date | Срок истечения действия карты в формате YYYYMM |
cardholder | Имя держателя карты, указанное при оплате |
payment_system | Наименование платежной системы |
payment_system_image | Логотип платежной системы |
image | Логотип карты |
paysys | Наименование платежного оператора |
paysys_image | Логотип платежного оператора |
payment_way | Наименование способа оплаты |
payment_way_code | Код способа оплаты |
payment_way_logo | Логотип способа оплаты |
bank_info | Данные банка-эмитента |
bank_name | Наименование банка-эмитента |
bank_country_code | Код страны банка-эмитента |
bank_country_name | Наименование страны банка-эмитента |
bank_image | Ссылка на логотип банка |
Пример ответа:
{
"invoice": {
"delivery_info": {
"address": {
"country": "RU",
"city": "Москва",
"address": "Кутузовский проспект, 32"
},
"delivery_type": "courier",
"description": "Спросить 'Где тут Сбердевайсы?'"
},
"order": {
"order_id": "a952b7ee-c928-4586-bd05-d932c21f749",
"order_number": "1952",
"order_date": "2021-04-07T11:24:37+03",
"service_id": 13,
"amount": "79900",
"currency": "RUB",
"purpose": "Покупка продуктов",
"description": "Заказ № 22-1952. Покупка продуктов",
"language": "ru-RU",
"expiration_date": "2021-04-09T10:23:51+03",
"autocompletion_date": null,
"tax_system": 0,
"visual_name": "Тестовый платеж",
"trade_name": "Тестовая",
"org_name": "ООО Умные системы",
"org_inn": "1234567890",
"visual_amount": "799 ₽",
"order_bundle": [
{
"position_id": 1,
"name": "Транзистор",
"item_params": [
{
"key": "_itemAttributes_supplier_info.name",
"value": "ООО Ромашка"
},
{
"key": "_itemAttributes_supplier_info.inn",
"value": "5009053292"
},
{
"key": "_itemAttributes_nomenclature",
"value": "Å13622200005881"
},
{
"key": "_itemAttributes_agent_info.type",
"value": "7"
}
],
"quantity": {
"measure": "шт.",
"value": "1"
},
"item_amount": "79801",
"currency": "RUB",
"item_code": "21ff407a-fa98-11e8-80c5-0cc47a817926",
"item_price": "79801",
"discount_type": "amount",
"discount_value": "17687",
"interest_type": null,
"interest_value": null,
"tax_type": 6,
"tax_sum": null,
"image": null
},
{
"position_id": 2,
"name": "Тиристор",
"item_params": [
{
"key": "code",
"value": "123значение321"
},
{
"key": "pack",
"value": "100"
},
{
"key": "_itemAttributes_supplier_info.name",
"value": "ООО Платежи"
},
{
"key": "_itemAttributes_supplier_info.inn",
"value": "7730253720"
}
],
"quantity": {
"measure": "шт.",
"value": "1"
},
"item_amount": "99",
"currency": "RUB",
"item_code": "21ff407c-fa98-11e8-80c5-0cc47a817926",
"item_price": "99",
"discount_type": "amount",
"discount_value": "21",
"interest_type": null,
"interest_value": null,
"tax_type": 6,
"tax_sum": null,
"image": "https://www.belchip.by/sitepics/00014684.jpg"
}
]
},
"purchaser": {
"contact": "phone",
"email": "test@test.ru",
"phone": "71111111111"
},
"invoice_params": [
{
"key": "packageName",
"value": "SbERdeVICEs"
},
{
"key": "packageKey",
"value": "ru.sberdevices.test"
}
]
},
"invoice_id": 38705,
"invoice_status": "paid",
"invoice_date": "2021-04-09T10:03:53+03",
"payment_info": {
"payment_id": 41876,
"card_id": 359,
"masked_pan": "**1111",
"payment_date": "2021-04-09T10:13:29+03",
"expiry_date": "202412",
"cardholder": "CARDHOLDER NAME",
"payment_system": "Visa",
"payment_system_image": "https://i.yapx.ru/H9iML.png",
"image": "https://i.yapx.ru/JMdXX.png",
"paysys": "RBS",
"paysys_image": "https://www.sberbank.ru/portalserver/content/atom/contentRepository/content?id=35f8876c-36fe-48b6-83d0-1ec3388a22f3",
"bank_info": {
"bank_name": "Alfa-Bank",
"bank_country_code": "RU",
"bank_country_name": "Россия",
"bank_image": null
},
"payment_way": "Оплата сохраненной картой",
"payment_way_code": "CARD_BINDING",
"payment_way_logo": "https://static.tildacdn.com/tild6236-3530-4235-b966-326630656238/___14_-removebg-prev.png"
},
"error": {
"user_message": "Счет оплачен",
"error_description": "",
"error_code": "0"
}
}
Подтверждение оплаты
Для успешного завершения двухстадийного платежа по счету используйте запрос PUT /invoices/{invoice_id}
.
Формат запроса
Параметры запроса будут зависеть от того, на полную или не полную сумму делается подтверждение.
Параметры для полной суммы:
Если необходимо завершить покупку на полную сумму, достаточно передать в качестве path-параметра значение для invoice_id
.
Наименование | Описание |
---|---|
Обязательный |
Передается как path-параметр в адресе запроса. Id счета, полученный при создании счета |
Параметры для неполной суммы:
Если завершение делается на неполную сумму и при создании счета товара была передана корзина, при завершении необходимо также передать новую товарную корзину, сумма позиций которой должна совпадать с суммой завершения.
Наименование | Описание |
---|---|
Обязательный |
Передается как path-параметр в адресе запроса. ID покупки, полученный при создании счета |
Обязательный |
В блоке передается вся информация о созданном счете |
Обязательный |
Блок информации о заказе |
Обязательный |
Сумма заказа (без разделителя, в копейках) |
Обязательный |
Код валюты. Поддерживается только значение RUB |
|
Описание корзины покупок для передачи в налоговую инспекцию и формирования фискального чека |
Обязательный |
Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа |
Обязательный, если передается блок |
Наименование или описание товарной позиции |
Обязательный |
Блок внутри списка корзины order_bundle. Описывает количественные характеристики определенной позиции корзины |
Обязательный |
Количество товаров в позиции. Для разделителя используйте "." |
Обязательный |
Единица измерения количества для значения из поля value |
Обязательный |
Цена определенной товарной позиции корзины (без разделителя, в копейках). Сумма всех товарных позиций должна совпадать с общей суммой платежа (order.amount). Рассчитывается как item_price * quantity |
Обязательный |
Код валюты. Поддерживается только значение RUB |
|
Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса |
Обязательный |
Цена одной единицы (value) данной товарной позиции (position_id). Указывается без разделителя, в копейках |
Пример запроса для неполной суммы:
{
"invoice": {
"order": {
"amount": 79801,
"currency": "RUB",
"order_bundle": [
{
"position_id": 1,
"name": "Транзистор",
"quantity": {
"value": 1,
"measure": "шт."
},
"item_amount": 79801,
"currency": "RUB",
"item_code": "21ff407a-fa98-11e8-80c5-0cc47a817926",
"item_price": 79801
}
]
}
}
}
Формат ответа
{
"error": {
"error_code": "0",
"user_message": "Оплата проведена",
"error_description": ""
}
}
Отмена счета
Для отмены счета используйте запрос DELETE /invoices/{invoice_id}
.
Формат запроса
Параметры запроса:
Наименование | Описание |
---|---|
Обязательный |
Передается как path-параметр в адресе запроса. ID покупки, полученный при создании счета |
Формат ответа
{
"error": {
"error_code": "0",
"user_message": "Отмена выполнена",
"error_description": ""
}
}
Полный возврат платежа
Для возврата средств на полную сумму используйте запрос PATCH /invoices/{invoice_id}
.
Формат запроса
Для возврата на полную сумму необходимо передать параметр invoice_id
в качестве path-параметра.
Наименование | Описание |
---|---|
Обязательный |
ID счета Передается как path-параметр в адресе запроса |
Формат ответа
{
"error": {
"error_code": "0",
"user_message": "Возврат выполнен",
"error_description": ""
}
}
Частичный возврат платежа
Для оформления частичного возврата суммы используйте запрос PATCH /invoices/{invoice_id}
. Возврат можно сделать только из статуса confirmed. В рамках одной операции частичные возвраты можно делать неограниченное количество раз. Главное условие — возвращаемый товар должен совпадать по составу и количеству с товаром из корзины.
Формат запроса
Для частичного возврата необходимо передать invoice_id
в качестве path-параметра и корзину возвращаемых товаров в теле запроса.
Параметры запроса:
Наименование | Описание |
---|---|
Обязательный |
ID счета. Передается как path-параметр в адресе запроса |
Параметры тела запроса:
Наименование | Описание |
---|---|
Обязательный |
Блок с информацией о регистрируемой покупке |
Обязательный |
Текущая сумма заказа. Указывается без разделителя, в копейках |
Обязательный |
Блок информации о заказе |
Обязательный |
Общая сумма по всем возвращаемым позициям. Указывается без разделителя, в копейках |
Обязательный |
Код валюты. Поддерживается только значение RUB |
Обязательный |
Описание корзины покупок для передачи в налоговую и формирования фискального чека. Максимальная длина — 500 символов |
Обязательный |
Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа |
Обязательный |
Наименование или описание товарной позиции |
Обязательный |
Блок внутри списка корзины order_bundle. Описывает количественные характеристики определенной позиции корзины. Максимальная длина — 20 символов |
Обязательный |
Количество товаров в позиции. Для разделителя используйте "." |
Обязательный |
Единица измерения количества для значения из поля value |
Обязательный |
Цена определенной товарной позиции корзины (без разделителя, в копейках). Сумма всех товарных позиций должна совпасть с общей суммой платежа (order.current_amount). Рассчитывается как |
Обязательный |
Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса |
Пример тела запроса:
{
"invoice": {
"order": {
"current_amount": 79900,
"refund_amount": 79801,
"currency": "RUB",
"order_bundle": [
{
"position_id": 1,
"name": "Транзистор",
"quantity": {
"value": 1
},
"item_amount": 79801,
"item_code": "21ff407a-fa98-11e8-80c5-0cc47a817926"
}
]
}
}
}
Формат ответа
{
"error": {
"error_code": "0",
"user_message": "Возврат выполнен",
"error_description": ""
}
}
Коды ответа
В ответ на каждый запрос могут возвращаться следующие коды:
Код ответа | Описание |
---|---|
200 | Запрос обработан успешно |
400 | Один из параметров в запросе передан в некорректном формате, либо формат запроса некорректный |
403 | Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки |
Заметили ошибку?
Выделите текст и нажмите Ctrl
+ Enter
, чтобы сообщить нам о ней