Управление подписками в 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

token

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

string

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

user_id

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

object

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

encrypted_sub_id

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

string

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

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

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

Параметр	Описание
`id` Обязательное	`numeric` Идентификатор подписки. Совпадает со значением, которое приходит в ответе на запросы: • `POST /v2/subscriptions` — параметр orderId • `GET /subscriptions` — параметр subscriptionId

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

boolean

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

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

message

string

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

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

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

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

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

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

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

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

token

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

string

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

user_id

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

object

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

encrypted_sub_id

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

string

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

Параметр	Описание
`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

token

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

string

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

user_id

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

object

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

encrypted_sub_id

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

string

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

Параметр	Описание
`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	Недоступен сетевой шлюз или ошибка на стороне сервиса подписок

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

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

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

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

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

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

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

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

Коды ошибок﻿

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

Авторизация

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

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

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

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

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

Коды ошибок