ym88659208ym87991671
API подписок в SmartPay | Документация для разработчиков

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

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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.