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

Управление подписками в SmartPay

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

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

Авторизация

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

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

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

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

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

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

Продление подписки

Продление подписки происходит автоматически без участия смартапа и пользователя. При наступлении даты очередного платежа сервис подписок инициирует списание средств с привязанной карты. Информация о результатах списания приходит в смартап в виде callback-уведомлений.

Отмена продления подписки

Для отмены продления подписки используйте метод DELETE /subscriptions/{id}. Отмена означает, что автоматическое продление подписки отменится и, когда наступит дата продления, средства не спишутся с карты пользователя. По окончании текущего периода подписка будет закрыта и в смартап придет callback-уведомление с типом CLOSED.


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


ПолеОписание
token

Обязательное

string

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

user_id

Обязательное

object

Блок с информацией о пользователе


encrypted_sub_id

Обязательное

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


ПараметрОписание

id

Обязательное

numeric

Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы:
• POST /v2/subscriptions — параметр orderId
• GET /subscriptions — параметр subscriptionId


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

curl -X DELETE 'https://.../subscriptions/123'
-H  'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H  'user_id: {   "encrypted_sub_id": "123" }'

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


ПолеОписание
success

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

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

{
    "success": false,
    "message": "Неизвестная ошибка"
}

Список подписок пользователя

Вы можете получить список активных и неактивных подписок пользователя. Для этого используйте метод GET /subscriptions.


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


ПолеОписание
token

Обязательное

string

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

user_id

Обязательное

object

Блок с информацией о пользователе


encrypted_sub_id

Обязательное

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


ПараметрОписание

serviceId

numeric

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

present

boolean

Признак активности подписки:
• true — вернутся активные подписки в статусах DEPOSITED, ACTIVATED, REPEATING, CONNECT_TO_PROVIDER
• false — вернутся неактивные подписки в статусах ACCEPTED, CLOSED, CANCELLED, REFUNDED, DECLINED, ERROR

Подробнее о статусах в разделе Статусы подписок

dateFrom

string

Фильтр по дате создания подписки — начало выборки. Передается в формате yyyy-mm-dd. Например: 2020-10-30

dateTo

string

Фильтр по дате создания подписки — окончание выборки. Передается в формате yyyy-mm-dd. Например: 2020-11-30

page

string

Номер запрашиваемой страницы с результатами выборки подписок

size

numeric

Количество записей на одной странице

sort

string

Параметр сортировки результата. Допустимые значения:
• ASC — по возрастанию
• DESC — по убыванию
Пример передачи параметра: sort=created, DESC


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

curl -X 'GET' 'https://.../subscriptions?serviceId=1&present=true&dateFrom=2021-03-24&dateTo=2021-03-25&page=0&size=20&sort=created%2CDESC' \
-H  'accept: /' \
-H  'token: eyJhbGciOiJIUzUxMiIsI…' \
-H  'user_id: { "encrypted_sub_id": "123" }'

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


ПолеОписание
success

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

body

object

Блок с информацией о подписках


content

array

Список найденных подписок



serviceName

string

Наименование смартапа, к которому привязана подписка
subscriptionId

numeric

Идентификатор подписки пользователя
addParameters

object

Список дополнительных параметров, которые передавались в запросе на подключение подписки
productId

numeric

Идентификатор параметров подписки. Выдается при запросе доступа к подпискам
productName

string

Наименование подписки. Передается значение из заявки на получение доступа к подпискам
productCode

string

Код подписки. Передается значение из заявки на получение доступа к подпискам
recurrent

boolean

Признак автоматического продления подписки:
• true — подписка продлевается автоматически (по умолчанию)
• false — подписка отменяется после истечения первого периода или при отмене
countOfDay

numeric

Количество дней, оставшихся до следующего регулярного платежа
periodType

string

Единица измерения продолжительности периода подписки:
• DAY — дни
• MONTH — месяцы
periodDuration

numeric

Продолжительность периода подписки
nextPaymentDate

string

Дата следующего продления подписки. Указывается в формате yyyy-mm-dd
price

numeric

Стоимость периода подписки. Указывается в копейках:
• Если есть PROMO период — цена 0
• Если нет PROMO, но есть START — цена стартового периода
• Если предусмотрен только STANDARD — цена стандартного периода
currency

string

Валюта списания. По умолчанию возвращается значение RUB
state

string

Текущий статус подписки. Подробнее в разделе Статусы подписок
currentPeriod

string

Название текущего периода подписки:
• PROMO — бесплатный
• START — с пониженной стоимостью
• STANDARD — период по умолчанию, действует до конца подписки


totalElements

numeric

Общее количество найденных записей


totalPages

numeric

Количество страниц для отображения результатов


number

numeric

Номер текущей отображаемой страницы


sort

object

Информация о сортировке вывода результатов
unsorted

boolean

Признак сортировки списка:
• true — список не отсортирован
• false — список отсортирован
sorted

boolean

Признак сортировки списка:
• true — список отсортирован
• false — список не отсортирован
empty

boolean

Признак пустоты списка:
• true — список пустой, параметр sort не передавался в запросе
• false — список непустой


size

numeric

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


numberOfElements

numeric

Общее количество найденных записей


first

boolean

Признак первой страницы:
• true — получена информация с первой страницы
• false — получена информация не с первой страницы


last

boolean

Признак последней страницы:
• true — получена информация с последней страницы
• false — получена информация не с последней страницы


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


{
    "success": false,
    "message": "Неизвестная ошибка",
    "body": {
        "totalPages": 0,
        "totalElements": 0,
        "sort": {
            "sorted": true,
            "unsorted": true,
            "empty": true
        },
        "first": true,
        "number": 0,
        "size": 0,
        "content": [
            {
                "serviceName": "Фирма 1",
                "subscriptionId": 100,
                "addParameters": "{\"something\":\"unknown\"}",
                "productId": 1,
                "productType": "string",
                "productName": "Тариф Middle",
                "productCode": "Middle",
                "recurrent": false,
                "countOfDay": 10,
                "periodType": "DAY | MONTH",
                "periodDuration": 30,
                "nextPaymentDate": "2021-03-23",
                "price": 10000,
                "currency": "RUB",
                "state": "ACCEPTED | DEPOSITED | DECLINED | CANCELED | ACTIVATED | CLOSED | REPEATING | REFUNDED | ERROR",
                "currentPeriod": "PROMO"
            }
        ],
        "numberOfElements": 0,
        "last": true
    }
}

Информация об одной подписке

Вы можете получить информацию по конкретной подписке пользователя. Для этого используйте метод GET /subscriptions/{id}.


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


ПолеОписание
token

Обязательное

string

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

user_id

Обязательное

object

Блок с информацией о пользователе


encrypted_sub_id

Обязательное

string

Идентификатор пользователя. Передается для получения информации о покупках конкретного пользователя. Идентификатор можно получить из переменной $request.rawRequest.uuid.sub


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


ПараметрОписание

id

numeric

Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы:
• POST /v2/subscriptions — параметр orderId
• GET /subscriptions — параметр subscriptionId


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

curl -X GET 'https://.../subscriptions/123'
-H  'token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9…'
-H  'user_id: {"encrypted_sub_id": "123"}'

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


ПолеОписание
success

boolean

Результат обработки запроса. Значения:

  • true — данные получены
  • false — данные не получены
message

string

Текстовое описание ошибки

body

object

Блок с информацией о подписках


serviceName

string

Наименование смартапа, к которому привязана подписка


subscriptionId

numeric

Идентификатор подписки пользователя


addParameters

object

Список дополнительных параметров, которые передавались в запросе на подключение подписки


productId

numeric

Идентификатор параметров подписки. Выдается при запросе доступа к подпискам


productName

string

Наименование подписки. Передается значение из заявки на получение доступа к подпискам


productCode

string

Код подписки. Передается значение из заявки на получение доступа к подпискам


recurrent

boolean

Признак автоматического продления подписки:
• true — подписка продлевается автоматически (по умолчанию)
• false — подписка отменяется после истечения первого периода или при отмене


countOfDay

numeric

Количество дней, оставшихся до следующего регулярного платежа


periodType

string

Единица измерения продолжительности периода подписки:
• DAY — дни
• MONTH — месяцы


periodDuration

numeric

Продолжительность периода подписки


nextPaymentDate

string

Дата следующего продления подписки. Указывается в формате yyyy-mm-dd


price

numeric

Стоимость периода подписки. Указывается в копейках:
• Если есть PROMO период — цена 0 или 100
• Если нет PROMO, но есть START — цена стартового периода
• Если предусмотрен только STANDARD — цена стандартного периода


currency

string

Валюта списания. По умолчанию возвращается значение RUB


state

string

Текущий статус подписки. Подробнее в разделе Статусы подписок


currentPeriod

string

Название текущего периода подписки:
• PROMO — бесплатный
• START — с пониженной стоимостью
• STANDARD — период по умолчанию, действует до конца подписки
• GRACE — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент не блокируется
• HOLD — период повторных попыток списания с карты пользователя в случае неуспешной оплаты при продлении подписки. В течение периода контент блокируется


description

string

Описание подписки. Передается значение из заявки на получение доступа к подпискам


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


{
    "success": true,
    "message": "",
    "body": {
        "serviceName": "Фирма 1",
        "subscriptionId": 100500,
        "addParameters": "{\"something\":\"unknown\"}",
        "productId": 1,
        "productType": "string",
        "productName": "Тариф Middle",
        "productCode": "Middle",
        "recurrent": false,
        "countOfDay": 10,
        "periodType": "DAY | MONTH",
        "periodDuration": 30,
        "nextPaymentDate": "2021-03-23",
        "price": 10000,
        "currency": "RUB",
        "state": "NEW | ACCEPTED | DEPOSITED | DECLINED | CANCELED | ACTIVATED | CLOSED | REPEATING | REFUNDED | ERROR",
        "currentPeriod": "PROMO",
        "description": "Тариф Middle — базовое предложение..."
    }
}

Коды ошибок

КодОписание
400Некорректный запрос.
Например:
• в запросе отсутствует авторизационный токен смартапа,
• указан некорректный идентификатор пользователя («Invalid user_id header received»),
• токену смартапа не предоставлены права на запрашиваемый ресурс,
• токен недействителен («The Token has expired on dd.mm.yyyy»)
403Запрещенная операция. Например, некорректно заполнен параметр encrypted_sub_id или сервису не удалось расшифровать sub_id
404Данные не найдены
502Недоступен сетевой шлюз или ошибка на стороне сервиса подписок
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.