API подписок в SmartPay

Обновлено 15 декабря 2023

SmartPay

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

Авторизация

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

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

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

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

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

https://smartpay.devices.sberbank.ru/api/subscription-market/

Список доступных подписок

Вы можете отображать пользователю список подписок, которые он может оформить в смартапе. Для этого используйте метод GET /v2/products.

Параметры заголовка

Поле		Описание
token Обязательное		string Токен для авторизации запроса. Подробнее в разделе Получение токена
user_id Обязательное		object Блок с информацией о пользователе. Передается для получения информации о покупках конкретного пользователя
	partner_client_id	string Уникальный идентификатор клиента в вашем бэкенде. Обязательный, если не указан encrypted_sub_id
	encrypted_sub_id	string Идентификатор пользователя, полученный с помощью сценария. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub. Обязательный, если не указан partner_client_id

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

Параметр	Описание
serviceId Обязательное	string Идентификатор сервиса, который вы получили в письме о подключении подписок. Подробнее в разделе Доступ к подпискам

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

curl --location --request GET 'https://smartpay.devices.sberbank.ru/api/subscription-market/v2/products?serviceId=127' \
--header 'token: eyJhbGci...' \
--header 'user_id: {"encrypted_sub_id": "lhIq..."}' \
--header 'Content-Type: application/json' \

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

Поле			Описание
success			boolean Результат обработки запроса. Значения: true — данные получены false — данные не получены
message			string Текстовое описание ошибки
body			array Блок с информацией о подписках
	productId		numeric Идентификатор продукта подписки. Выдается при запросе доступа к подпискам
	name		string Наименование продукта подписки. Передается значение из заявки на получение доступа к подпискам
	description		string Описание подписки. Передается значение из заявки на получение доступа к подпискам
	productCode		string Артикул (код подписки у провайдера). Передается значение из заявки на получение доступа к подпискам
	tariffParams		array Блок с параметрами тарифа
		tariffId	numeric Идентификатор тарифа. Выдается при запросе доступа к подпискам
		partnerName	string Наименование тарифа
		periodName	string Название периода списания за подписку: • PROMO — бесплатный либо за 1 рубль • START — с пониженной стоимостью • STANDARD — период по умолчанию, действует до конца подписки • GRACE — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент не блокируется • HOLD — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент блокируется
		periodType	string Единица измерения продолжительности периода подписки: • DAY — дни • MONTH — месяцы
		periodDuration	numeric Продолжительность периода подписки
		periodPrice	string Стоимость периода подписки. Указывается в копейках

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

{
    "success": true,
    "message": "",
    "body": [
        {
            "productId": 1,
            "name": "Тариф Middle",
            "description": "Тариф Middle - базовое предложение...",
            "productCode": "Middle",
            "tariffParams": [
                {
                    "tariffId": 1,
                    "partnerName": "Тариф Middle",
                    "periodName": "PROMO | START | STANDARD | GRACE | HOLD",
                    "periodType": "MINUTE | HOUR | DAY | MONTH | YEAR",
                    "periodDuration": 30,
                    "periodPrice": "10000"
                }
            ]
        }
    ]
}

Подключение подписки

Для подключения используйте метод POST /v2/subscriptions.

Для этого вам понадобится идентификатор тарифа (tariffId), полученный методом GET /v2/products.

Формат данных application/json запроса задается в заголовке запроса:

Content-Type: application/json

Параметры заголовка

Поле		Описание
token Обязательное		string Токен для авторизации запроса. Подробнее в разделе Получение токена
user_id Обязательное		object Блок с информацией о пользователе
	encrypted_sub_id Обязательное	string Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub

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

Параметр	Описание
tariffId Обязательное	number Идентификатор тарифа, полученный по запросу GET /v2/products
addParameters	string(1000) Json-объект, в котором можно передать любую информацию по подписке. Информация будет отправляться в callback-уведомлениях при наступлении событий (активация, отмена, продление подписки)
contact	string(10) Тип контакта пользователя. Варианты значений: EMAIL, PHONE
email	string(255) Электронная почта пользователя
phone	string(255) Телефон пользователя
reservationId	string(255) Идентификатор резерва по подписке на стороне провайдера
deviceId	string(255) Идентификатор устройства. Обязательно передать, если был передан в запросе GET /v2/products при получении тарифа
deviceType	string(255) Тип устройства
recurrent	boolean Признак автоматического продления подписки: • true — подписка продлевается автоматически (по умолчанию), • false — подписка закрывается после истечения первого периода

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

curl -X POST 'https://.../v2/subscriptions' \
-H  'accept: /' \
-H  'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…' \
-H  'user_id: { "encrypted_sub_id": "123" }' \
-H  'Content-Type: application/json' \
-d '{"tariffId" : 162,
    "addParameters" : "

{\"provider\":\"prime\",\"token\":null,\"authType\":null,\"contentId\":\"162\",\"deviceId\":\"SBB01Y10AB02...\",\"deviceManufacturer\":\"SberDevices\",\"deviceModel\":\"sberbox\",\"deviceSoftware\":\"1.73.11\",\"ipAddress\":\"109.252...\",\"recurrent\":true,\"contentType\":\"subscription\",\"contentСount\":0,\"externalStoreId\":\"Подписка Middle на месяц с промо-периодом\",\"deviceType\":\" SberBox\",\"timezoneId\":\"Europe/Moscow\",\"user_id\":\"u1234\",\"phone\":null,\"subId\":\"d75644b...\"}
",
  "contact" : "EMAIL | PHONE",
  "email" : "sberbank@sberbank.ru",
  "phone" : "79123456789 | +79123456789 | 89123456789 | +7-(912)-345-67-89 | +7 (912) 345 67 89 | или комбинация приведенных примеров",
  "reservationId" : "qwerty1234",
  "deviceId" : "SBB01Y10AB02...",
  "deviceType" : "SberBox",
  "recurrent" : true}'

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

Поле		Описание
success		boolean Результат обработки запроса. Значения: true — данные получены false — данные не получены
message		string Текстовое описание ошибки
body		object Блок с информацией о подписках
	orderId	numeric Идентификатор созданной подписки
	invoiceId	string Идентификатор платежа для оформления подписки
	name	string Наименование подписки. Передается значение из заявки на получение доступа к подпискам
	description	string Описание подписки. Передается значение из заявки на получение доступа к подпискам
	price	numeric Цена первого периода подписки. Указывается в копейках: • Если есть PROMO период — цена 0 • Если нет PROMO, но есть START — цена стартового периода • Если предусмотрен только STANDARD — цена стандартного периода
	currency	string Валюта списания. По умолчанию возвращается значение RUB
	periodType	string Единица измерения продолжительности периода подписки: • DAY — дни • MONTH — месяцы
	periodDuration	numeric Продолжительность периода подписки
	state	string Текущий статус подписки. В ответе будет возвращаться статус ACCEPTED

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

{
    "success": true,
    "message": "",
    "body": {
        "orderId": 999,
        "invoiceId": "b702aae8-13df-11eb-a058-b...",
        "name": "Тариф Middle",
        "description": "Тариф Middle - базовое предложение...",
        "price": 10000,
        "currency": "RUB",
        "periodType": "DAY",
        "periodDuration": 30,
        "state": "ACCEPTED"
    }
}

Защита от дублированных платежей

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

Если пользователь оплатил подписку, повторное оформление по тому же тарифу невозможно, пока подписка не закончится.

Оплата подписки

В ответ на запрос POST /v2/subscriptions придет параметр invoiceId — это идентификатор платежа для оформления подписки. Даже если для подписки предусмотрен бесплатный PROMO период, необходимо провести платеж для привязки карты. В этом случае средства не списываются — пользователь просто указывает реквизиты банковской карты для последующих списаний.

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

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

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

Запрос статуса платежа аналогичен запросу статуса при проведении разового платежа. Подробнее в разделе Получение статуса.