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

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

  1. Регистрация платежа.
  2. Проведение платежа (только при создании смартапа через webhook).
  3. Получение статуса.
  4. Завершение платежа (только для двухстадийной оплаты).
  5. Отмена платежа.
  6. Возврат платежа.

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

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

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

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

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

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

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

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

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

Регистрация платежа

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

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

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


Название

Тип

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

Описание

ptype

integer

Да

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

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

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

invoice

object

Да

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

    purchaser

object

Нет

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

        email

string

Да, если передан блок `purchaser`

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

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

        phone

string

Да, если не передан параметр `email`

Телефон покупателя. Максимальная длина — 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 символов

    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

Да

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

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

        currency

string

Да

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

        purpose

string

Да

Наименование вашего юридического лица. Например: ООО «Ромашка»

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

        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 символов

            quantity

object

Да

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

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

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

                value

number

Да

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

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

                measure

string

Да

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

            item_amount

integer

Да

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

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

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

            currency

string

Да

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

            item_code

string

Да

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

            item_price

integer

Да

Цена одной единицы (value) данной товарной позиции (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 укажите идентификатор заказа.

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 ID счета, по которому был направлен запрос
invoice_date Дата и время создания счета
invoice_status Текущий статус счета. Возможные значения читайте в разделе Статусы платежа

invoice

В этом блоке передается вся информация о регистрируемой покупке. Передается только для кода ответа 200

    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": {
        "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 string Да Единица измерения количества для значения из поля 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.

Название Тип Обязательный Описание
invoice_id string Да Передается как path параметр в адресе запроса.

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

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

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

Коды ответа

В ответ на каждый запрос могут возвращаться следующие коды:

Код ответа
Описание
200
Запрос обработан успешно
400
Один из параметров в запросе передан в некорректном формате, либо формат запроса некорректный
403
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки

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

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