API подписок в SmartPay

Обновлено 19 февраля 2025

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` Идентификатор сервиса, который вы получили в письме о подключении подписок. Подробнее в разделе Доступ к подпискам

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

Поле

Описание

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, с которым был инициирован платеж.

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

API подписок в SmartPay

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

Авторизация﻿

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

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

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

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

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

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

Авторизация

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

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

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

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

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