Прием платежей через SmartApp API

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

  1. Создание счета.
  2. Проведение платежа (только при создании смартапа через webhook).
  3. Получение статуса.
  4. Завершение оплаты (только для двухстадийной оплаты).
  5. Отмена платежа.
  6. Возврат платежа: полный и частичный.
Для смартапов, созданных через SmartApp API, доступно подключение одностадийных и двухстадийных платежей.

Перед подключением

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

В заголовке каждого запроса необходимо передавать токен API Key в следующем формате:

  • Тип токена: Bearer
  • Имя заголовка: Authorization

Подробнее о получении параметров авторизации в разделе Проект SmartPay.

URL для запросов

Все запросы необходимо отправлять на следующий URL:

https://smartmarket.online.sberbank.ru/smartpay/v1/

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

Для создания счета на проведение платежа используйте следующий запрос: 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_id ID зарегистрированной оплаты

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

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

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

Если вы подключаете сценарий через Webhook, то для проведения платежей вы можете использовать следующие команды SmartApp API:

  • POLICY_RUN_APP — запрос на проведение платежа.
  • PAY_DIALOG_FINISHED — событие о завершении платежа.

POLICY_RUN_APP

Для вызова платежного сценария и проведения оплаты используйте команду POLICY_RUN_APP.

Пример вызова:

{
    "command": "POLICY_RUN_APP",
    "nodes": {
      "server_action": {
        "app_info": {
          "systemName": "payment_app"
        },
        "parameters": {
          "invoice_id": "3000",
          "app_info": {
            "projectId": "0da9a4a0-cb52-4490-afce-4f535c9d1eb5"
          }
        }
      }
    }
  }

В параметре projectId укажите идентификатор вашего смартапа в SmartMarket Studio. В параметре invoice_id укажите идентификатор счета.

Для оплаты счета используйте запрос 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_url URL платежной формы, на который надо перенаправить браузер клиента
deeplink Deeplink, на который надо перенаправить клиента для оплаты в мобильном приложении

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

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

PAY_DIALOG_FINISHED

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

В событии передается response_code с кодом ответа. Этот код является информационным и говорит о наиболее вероятном состоянии оплаты. После получения кода ответа нужно отправить запрос на проверку статуса счета, затем можно принимать решение о формировании ответа клиенту и дальнейших шагах. В случае одностадийного платежа процесс оплаты завершается после получения этого стауса. Возможные значения response_code:

  • 0 — успешная оплата;
  • 1 — неожиданная ошибка;
  • 2 — пользователь закрыл смартап. При получении этого кода необходимо дополнительно отправить запрос на проверку статуса платежа, чтобы отобразить результат пользователю;
  • 3 — невозможно начать оплату, так как отображается другой сценарий оплаты;
  • 4 — время оплаты счета истекло;
  • 5 — оплата отклонена бэкендом;
  • 6 — состояние оплаты неизвестно;
  • 7 — оплата для данной поверхности недоступна.
Чтобы принять решение о формировании заказа необходимо дополнительно отправить запрос на проверку статуса счета, т.к. получение события PAY_DIALOG_FINISHED не означает, что счет перешел в финальный статус.

Пример сообщения:

"payload": {
    ...
    "server_action": {
      "action_id": "PAY_DIALOG_FINISHED",
      "parameters": {
        "payment_response":
            {
                "response_code": 0,
                "invoice_id": "***ID****"
            }
        "app_info":
            {
                "projectId": "**",
                "systemName": "**"
            }
        }
      }
    }
    ...
}

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

После создания счета вы можете проверить, успешно ли прошел платеж. Для этого используйте следующий запрос: 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
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки

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

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