ym88659208ym87991671
API SmartPay | Документация SmartMarket
Skip to main content

API SmartPay

Независимо от способа создания смартапа (через SmartApp Code, SmartApp Graph, webhook и т. д.), вы можете использовать следующие методы для подключения приема платежей:

  1. Создание счета.
  2. Проведение платежа.
  3. Получение статуса.
  4. Подтверждение оплаты.
  5. Отмена счеты.
  6. Возврат платежа: полный и частичный.

Создание счета

Для создания счета на проведение платежа используйте запрос POST /invoices.

Формат запроса

Параметры тела запроса:

НаименованиеОписание

ptype

Обязательный

integer

Тип оплаты счета:

• 0 – одностадийная оплата

• 1 – двухстадийная оплата

Подробнее о видах оплаты счета

invoice

Обязательный

object

В этом блоке передается вся информация о создаваемом счете

    purchaser

object

Блок информации о покупателе

        email

        Обязательный,

        если

        не передан

        параметр phone

string

Email покупателя, на который будет отправлен фискальный чек (при условии, что покупатель не укажет иной email при оплате по QR-коду).

Максимальная длина — 100 символов

        phone

        Обязательный,

        если

        не передан

        параметр email

string

Телефон покупателя.

Максимальная длина — 50 символов

        contact

string

Дополнительный способ связи с покупателем.

Максимальная длина — 50 символов

    delivery_info

object

Блок информации о параметрах доставки

        address

        Обязательный,

        если

        передается

        блок

object

Блок, содержащий набор параметров с адресом покупателя

            country

            Обязательный,

            если

            передается

            блок

string

Код страны доставки в формате ISO 3166.

Максимальная длина — 2 символа

            city

            Обязательный,

            если

            передается

            блок

string

Город покупателя.

Максимальная длина — 100 символов

            address

            Обязательный,

            если

            передается

            блок

string

Адрес покупателя (улица, дом, квартира и т. д.).

Максимальная длина — 255 символов

        delivery_type

        Обязательный,

        если

        передается

        блок

string

Тип доставки. Например, курьер.

Максимальная длина — 50 символов

        description

string

Дополнительное описание для доставки.

Максимальная длина — 255 символов

    invoice_params

list

Блок, содержащий дополнительные параметры по счету, которые можно получить потом в ответе. Можно использовать для ограничения вариантов оплаты, для задания лимитов в случае оплаты счета с предавторизацией и др.

        key

        Обязательный,

        если

        передается

        блок

string

Название передаваемого параметра.

Максимальная длина — 100 символов

        value

        Обязательный,

        если

        передается

        блок

string

Значение передаваемого параметра.

Максимальная длина — 500 символов

Если key=inapp_serviceparam_payment_instruments, то список разрешенных платежных инструментов при оплате счета следующий:

1. Если value содержит card, то разрешен code, равный card

2. Если value содержит new, то разрешен code, равный QR или new.

3. Если не указан value, разрешены любые платежные инструменты.

Если key=inapp_serviceparam_action_name, то название кнопки действия (ActionName) оплаты на платежной форме:

1. Если указано value, то ActionName принимает значение value

2. Если не указано value, то ActionName принимает значение «Оплатить»

    order

    Обязательный

object

Блок информации о заказе

        order_id

        Обязательный

string

Идентификатор заказа. Должен быть уникален в рамках выделенного для приложения service_id, иначе не будет создан новый invoice_id. Используется для защиты от дублирующих запросов.

Максимальная длина — 50 символов

        order_date

        Обязательный

string{date/time}

Дата и время заказа.

Пример: 2020-04-29T08:17:03+03

        order_number

string

Номер заказа для отображения покупателю и отслеживания статуса заказа.

Рекомендуем сделать его максимально понятным и простым для восприятия.

Максимальная длина — 50 символов

        service_id

        Обязательный

string

Идентификатор сервиса, полученный при выдаче токена для авторизации запроса

        amount

        Обязательный

integer

Сумма счета (без разделителя, в копейках).

Если в запросе указывается корзина товаров, то это поле должно быть равно сумме стоимости всех товаров в корзине sum (invoice.order и order_bundle.item_amount)

Например, 1 рубль передается в этом поле как 100

        currency

        Обязательный

string

Код валюты. Поддерживается только значение RUB

        purpose

        Обязательный

string

Краткое назначение платежа, отображается при оплате/подтверждении безакцепного списания клиентом

        description

        Обязательный

string

Описание платежа для отображения плательщику.

Максимальная длина — 500 символов

        language

        Обязательный

string

Язык для текстовых полей. Поддерживается только значение ru-RU

        expiration_date

string{date/time}

Дата истечения срока оплаты.

По умолчанию на оплату отводится 20 минут от момента регистрации платежа. Если есть необходимость увеличить или уменьшить это время, нужно передать данное поле.

Пример: 2020-04-29T08:17:03+03

        tax_system

integer

Система налогообложения:

• 0 – общая.

• 1 – упрощенная, доход.

• 2 – упрощенная, доход минус расход.

• 3 – единый налог на вмененный доход.

• 4 – единый сельскохозяйственный налог.

• 5 – патентная система налогообложения.

Не требуется указывать, например, при создании счета на предавторизацию.

Для счетов на оплату при соответствующих настройках мерчанта можно взять значение оттуда.

Рекомендуется всегда указывать для надежной оплаты

        order_bundle

list

Описание корзины покупок для передачи в налоговую и формирования фискального чека.

Не требуется заполнять, например, при создании счета на предавторизацию.

Обязательно нужно указывать в счетах на оплату, иначе оплата не состоится.

Максимальная длина — 500 символов

            position_id

            Обязательный

integer

Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа

            name

            Обязательный

string

Наименование или описание товарной позиции

            item_params

list

Дополнительные параметры, уточняющие товарную позицию

                key

                Обязательный,

                если

                передается

                блок

string

Название передаваемого параметра.

Максимальная длина — 100 символов

                value

                Обязательный,

                если

                передается

                блок

string

Значение передаваемого параметра.

Максимальная длина — 500 символов.

Если key=_itemAttributes_supplier_info, то в поле value необходимо передать наименование организации, которое будет использоваться при формировании агентского чека.

Если key=_itemAttributes_supplier_info.inn, то в поле value необходимо передать ИНН организации, которое будет использоваться при формировании агентского чека.

Если key=_itemAttributes_agent_info.type, то в поле value необходимо передать тип агента, возможно одно из следующих значений:

• 1 - банковский платёжный агент;

• 2 - банковский платёжный субагент;

• 3 - платёжный агент;

• 4 - платёжный субагент;

• 5 - поверенный;

• 6 - комиссионер;

• 7 - иной агент

            quantity

            Обязательный

object

Описывает количественные характеристики определенной позиции корзины.

Максимальная длина — 20 символов

                value

                Обязательный

number

Количество товаров в позиции.

Для разделителя используйте точку

                measure

                Обязательный

string

Единица измерения количества для значения из поля value

            item_amount

            Обязательный

integer

Стоимость определенной товарной позиции корзины (без разделителя, в копейках).

Сумма стоимостей всех товарных позиций должна совпасть с общей суммой счета (order.amount).

Рассчитывается как item_price * quantity.value

            currency

            Обязательный

string

Код валюты. Поддерживается только значение RUB

            item_code

            Обязательный

string

Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса

            item_price

            Обязательный

integer

Цена одной единицы данной товарной позиции (position_id). Указывается без разделителя, в копейках

            discount_type

string

Тип скидки на товарную позицию

Пример: percent

Максимальная длина — 20 символов

            discount_value

number

Значение скидки на товарную позицию

Используется для формирования фискального чека, сумму рассчитывает разработчик

            interest_type

string

Тип агентской комиссии за продажу товара (применимо только для агентской схемы).

Пример: agentPercent.

Максимальная длина — 20 символов

            interest_value

number

Значение агентской комиссии за продажу товара (применимо только для агентской схемы)

            tax_type

            Обязательно

integer

Значение ставки НДС:

• 0 - без НДС

• 1 - НДС по ставке 0%

• 2 - НДС по ставке 10%

• 3 - НДС по ставке 18%

• 4 - НДС по ставке 10/110

• 5 - НДС по ставке 18/118

• 6 - НДС по ставке 20%

• 7 - НДС по ставке 20/120

Значение «НДС по ставке 0%» отличается от варианта «без НДС» только формированием чека в зависимости от системы налогооблажения. По сумме налога разницы нет

            tax_sum

integer

Сумма налога, посчитанная продавцом (без разделителя, в копейках)

Пример тела запроса:

{
    "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_idID зарегистрированной оплаты

Пример ответа:

{
    "error": {
        "error_code": "0",
        "error_description": "",
        "user_message": ""
    },
    "invoice_id": "38705"
}

Проведение платежа

Для оплаты счета используйте запрос POST /invoices/{invoice_id}.

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

НаименованиеОписание

invoice_id

Обязательный

string

Передается как path параметр в адресе запроса.

ID покупки, полученный при создании счета

Параметры тела запроса

НаименованиеОписание

user_id

object

Идентификаторы пользователя

Обязательно указать один из идентификаторов, даже если указан user_channel:

• sub_id

• encrypted_sub_id

• partner_client_id

    user_channel

string

Канал клиента

    sub_id

string

Sub клиента

    encrypted_sub_id

string

Зашифрованный sub клиента

    partner_client_id

string

Идентификатор клиента, совершающего оплату в смартапе партнера

operations

Обязательный

list

Список операций по счету

    operation

Обязательный

string

Тип операции:

• payment — платежный инструмент;

• prepare_payment — доступное действие клиента при оплате на платежной форме;

• payment_loyalty_points — сумма лимита по заказу в копейках

• recurrent_loyalty_points — сумма лимита по заказу в копейках

    code

string

Сервисный код операции. Зависит от типа операции.

Для operation=payment указывается вариант оплаты, выбранный клиентом, например "card".

Для operation=payment_loyalty_points указывается код бонусной программы, например "sbrf_spasibo".

Может принимать значения:

• «new» – создание нового заказа RBS;

• «card» – оплата сохраненной картой;

• «QR» – создание нового заказа RBS, оплата по QR;

• «app2sbol» – создание заказа в СБОЛ, с переходом в СБОЛ из МП;

• «invoice» – безакцептное списание

• код бонусной программы

    value

string

Значение, соответствующее сервисному коду

Для operation=payment указывается идентификатор, например для «card» указывается ID выбранной карты.

Для operation=payment_loyalty_points сумма бонусных баллов, которая должна быть использована при совершении операции.

Указывается в минимальных единицах (в копейках). Например, 123 балла 50 копеек = 12350

device_info

object

Информация об устройстве

    device_platform_type

string

Наименование операционной системы устройства. Например, iOS

    device_platform_version

string

Версия операционной системы устройства. Например, 13.6.1

    device_model

string

Модель устройства. Например, iPhone 7

    device_manufacturer

string

Производитель устройства. Например, Apple

    device_id

string

Серийный номер устройства (при наличии). Например, 83c3f257-46d8-41fe-951b-f79d04e288c2

    surface

string

Поверхность, с которой производится вызов. Например, COMPANION

        surface_version

string

Версия программного обеспечения

return_url

string

Адрес, на который требуется перенаправить пользователя в случае успешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Используется при "code"="new".

Если адрес не указан, то он будет подставлен на стороне платежного сервиса из значения по умолчанию

fail_url

string

Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Используется при "code"="new".

Если адрес не указан, то он будет подставлен на стороне платежного сервиса из значения по умолчанию

return_deeplink

string

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_urlURL платежной формы, на который надо перенаправить браузер клиента
deeplinkDeeplink, на который надо перенаправить клиента для оплаты в мобильном приложении

Пример ответа

{
    "error": {
        "error_code": "0",
        "error_description": "",
        "user_message": "Средства захолдированы"
    },
    "form_url": "38705"
}

При завершении оплаты приходит сообщение PAY_DIALOG_FINISHED, которое позволяет определить статус счета. Сообщение можно получить независимо от типа платежа — одностадийный или двухстадийный.

Получение статуса

После создания счета вы можете проверить, успешно ли прошел платеж. Для этого используйте следующий запрос: GET /invoices/{invoice_id}.

Формат запроса

Параметры запроса:

Наименование
Описание

invoice_id

Обязательный

string

Передается как path параметр в адресе запроса.

Id счета, полученный в шаге 1

inv_status

string

Статус счета для начала отслеживания изменений. Если при вызове запроса счет найден и статус равен значению этого параметра, то ответ отдается только при смене статуса или по таймауту

wait

integer

Время в секундах, которое сервер будет ожидать до смены статуса счета

Пример запроса:

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, то список разрешенных платежных инструментов при оплате счета следующий:
  • Если value содержит "card", разрешен code ="card"
  • Если value содержит "new", разрешены code ="QR" или "new"
  • Если не указан value, разрешены любые платежные инструменты
Если key=inapp_serviceparam_action_name, то название кнопки действия (ActionName) оплаты на платежной форме:
  • Если указано value, то ActionName = value
  • Если не указано value, 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.

НаименованиеОписание

invoice_id

Обязательный

string

Передается как path-параметр в адресе запроса.

Id счета, полученный при создании счета

Параметры для неполной суммы:

Если завершение делается на неполную сумму и при создании счета товара была передана корзина, при завершении необходимо также передать новую товарную корзину, сумма позиций которой должна совпадать с суммой завершения.

Наименование
Описание

invoice_id

Обязательный

string

Передается как path-параметр в адресе запроса.

ID покупки, полученный при создании счета

invoice

Обязательный

object

В блоке передается вся информация о созданном счете

    order

    Обязательный

object

Блок информации о заказе

        amount

        Обязательный

integer

Сумма заказа (без разделителя, в копейках)

        currency

        Обязательный

string

Код валюты. Поддерживается только значение RUB

        order_bundle

order_bundle

Описание корзины покупок для передачи в налоговую инспекцию и формирования фискального чека

            position_id

            Обязательный

integer

Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа

            name

            Обязательный,

            если

            передается

            блок

string

Наименование или описание товарной позиции

            quantity

            Обязательный

object

Блок внутри списка корзины order_bundle.

Описывает количественные характеристики определенной позиции корзины

                value

                Обязательный

number

Количество товаров в позиции.

Для разделителя используйте "."

                measure

                Обязательный

number

Единица измерения количества для значения из поля value

            item_amount

            Обязательный

integer

Цена определенной товарной позиции корзины (без разделителя, в копейках).

Сумма всех товарных позиций должна совпадать с общей суммой платежа (order.amount).

Рассчитывается как item_price * quantity

            currency

            Обязательный

string

Код валюты. Поддерживается только значение RUB

            item_code

string

Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса

            item_price

            Обязательный

integer

Цена одной единицы (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}.

Формат запроса

Параметры запроса:

НаименованиеОписание

invoice_id

Обязательный

string

Передается как path-параметр в адресе запроса.

ID покупки, полученный при создании счета

Формат ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Отмена выполнена",
        "error_description": ""
    }
}

Полный возврат платежа

Для возврата средств на полную сумму используйте запрос PATCH /invoices/{invoice_id}.

Формат запроса

Для возврата на полную сумму необходимо передать параметр invoice_id в качестве path-параметра.

НаименованиеОписание

invoice_id

Обязательный

string

ID счета

Передается как path-параметр в адресе запроса

Формат ответа

{
    "error": {
        "error_code": "0",
        "user_message": "Возврат выполнен",
        "error_description": ""
    }
}

Частичный возврат платежа

Для оформления частичного возврата суммы используйте запрос PATCH /invoices/{invoice_id}. Возврат можно сделать только из статуса confirmed. В рамках одной операции частичные возвраты можно делать неограниченное количество раз. Главное условие — возвращаемый товар должен совпадать по составу и количеству с товаром из корзины.

Формат запроса

Для частичного возврата необходимо передать invoice_id в качестве path-параметра и корзину возвращаемых товаров в теле запроса.


Параметры запроса:

НаименованиеОписание

invoice_id

Обязательный

string

ID счета.

Передается как path-параметр в адресе запроса



Параметры тела запроса:


Наименование
Описание

invoice

Обязательный

object

Блок с информацией о регистрируемой покупке

    order

    Обязательный

object

Текущая сумма заказа. Указывается без разделителя, в копейках

        current_amount

        Обязательный

integer

Блок информации о заказе

        refund_amount

        Обязательный

integer

Общая сумма по всем возвращаемым позициям. Указывается без разделителя, в копейках

        currency

        Обязательный

string

Код валюты. Поддерживается только значение RUB

        order_bundle

        Обязательный

list

Описание корзины покупок для передачи в налоговую и формирования фискального чека.

Максимальная длина — 500 символов

            position_id

            Обязательный

integer

Номер позиции в корзине для добавления в фискальный чек. Должен быть уникален в рамках заказа

            name

            Обязательный

string

Наименование или описание товарной позиции

            quantity

            Обязательный

object

Блок внутри списка корзины order_bundle.

Описывает количественные характеристики определенной позиции корзины.

Максимальная длина — 20 символов

                value

                Обязательный

number

Количество товаров в позиции.

Для разделителя используйте "."

                measure

                Обязательный

string

Единица измерения количества для значения из поля value

            item_amount

            Обязательный

integer

Цена определенной товарной позиции корзины (без разделителя, в копейках).

Сумма всех товарных позиций должна совпасть с общей суммой платежа (order.current_amount).

Рассчитывается как item_price * quantity

            item_code

            Обязательный

string

Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса


Пример тела запроса:

{
    "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
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки
Обновлено 05 мая 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней