Управление лимитами пользователя
Последнее обновление: 15-08-2022
В рамках банковской платформы для пользователя установлены законодательные ограничения (лимиты) на пополнение наличными, платежи, переводы и на остаток на балансе. Лимиты зависят от присвоенного пользователю уровня идентификации.
Вы можете:
- Установить собственные лимиты на финансовые операции пользователя.
- Получить информацию по указанным лимитам пользователя — установленным как партнером, так и банковской платформой.
Установка лимита на расходные операции пользователя
Запрос → PUT
URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/rule
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api.qiwi.com/partner/openapi-limits/v1/products/best-partner/clients/clientUID123/rule \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJDM5OE***********************' \
-d '{
"limitValue" : {
"type" : "MONEY",
"value" : "300.00",
"currency" : "RUB"
},
"limitType" : "CUSTOMIZABLE_EXPENSE_OPERATIONS",
"periodType" : "ON_DAY"
}'
Параметр | Описание | REGEX | Пример |
---|---|---|---|
productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
limitType | string Обязательный параметр тела запроса. Тип лимита. Поддерживается только CUSTOMIZABLE_EXPENSE_OPERATIONS |
CUSTOMIZABLE_EXPENSE_OPERATIONS |
|
limitValue | object Обязательный параметр тела запроса. Блок с информацией о значении устанавливаемого лимита, в формате LimitData |
||
periodType | string Обязательный параметр тела запроса. Тип периода действия лимитов. Поддерживаются только ON_DAY и ON_MONTH . |
ON_MONTH |
|
dateFrom | string Параметр тела запроса. Дата начала периода в формате ISO 8601 ±hh:mm с московской Time Zone. Для установки лимита с текущего момента параметр передавать не нужно. |
2023-08-01T00:00:00+03:00 |
|
dateTill | string Параметр тела запроса. Дата окончания периода в формате ISO 8601 ±hh:mm с московской Time Zone. Для установки лимита на неопределенный срок параметр передавать не нужно. |
2027-08-01T00:00:00+03:00 |
Ответ ←
В успешном ответе возвращается HTTP-статус 200 OK
. Тело успешного ответа не содержит данных.
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение информации по установленным для пользователя лимитам
Метод возвращает список сведений о лимитах, как сервисных, так и установленных партнером для пользователя. Если не указывать явно тип лимита в запросе, возвращаются все действующие лимиты для пользователя.
Запрос → GET
URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/limits?limitTypes={limitTypes}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
curl --location \
--request GET \
'https://api.qiwi.com/partner/openapi-limits/v1/products/best-partner/clients/clientUID123/limits' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIRDM5OE***********************'
Параметр | Описание | REGEX | Пример |
---|---|---|---|
productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
limitTypes | Параметр URL запроса. Тип лимита. Указывается для фильтрации выборки. Чтобы ограничить выборку сразу несколькими типами, укажите параметр нужное количество раз. | CUSTOMIZABLE_EXPENSE_OPERATIONS |
Ответ ←
Пример ответа
[
{
"maxValue": {
"type": "MONEY",
"value": 3000.00,
"currency": "RUB"
},
"accumulatedValue": {
"type": "MONEY",
"value": 9.76,
"currency": "RUB"
},
"remainingValue": {
"type": "MONEY",
"value": 2990.24,
"currency": "RUB"
},
"limitPeriod": {
"periodFrom": "2022-02-03T00:00:00+03:00",
"periodTill": "2022-02-03T23:59:59+03:00",
"periodType": "ON_DAY"
},
"limitType": "CUSTOMIZABLE_EXPENSE_OPERATIONS"
},
{
"maxValue": {
"type": "MONEY",
"value": 200000.00,
"currency": "RUB"
},
"accumulatedValue": {
"type": "MONEY",
"value": 9.76,
"currency": "RUB"
},
"remainingValue": {
"type": "MONEY",
"value": 199990.24,
"currency": "RUB"
},
"limitPeriod": {
"periodFrom": "2022-02-01T00:00:00+03:00",
"periodTill": "2022-02-28T23:59:59+03:00",
"periodType": "ON_MONTH"
},
"limitType": "EXPENSE_OPERATIONS"
},
{
"maxValue": {
"type": "MONEY",
"value": 40000.00,
"currency": "RUB"
},
"accumulatedValue": {
"type": "MONEY",
"value": 1.57,
"currency": "RUB"
},
"remainingValue": {
"type": "MONEY",
"value": 39998.43,
"currency": "RUB"
},
"limitPeriod": {
"periodFrom": "2022-02-01T00:00:00+03:00",
"periodTill": "2022-02-28T23:59:59+03:00",
"periodType": "ON_MONTH"
},
"limitType": "CASH_WITHDRAWAL_OPERATIONS"
},
{
"maxValue": {
"type": "MONEY",
"value": 5000.00,
"currency": "RUB"
},
"accumulatedValue": {
"type": "MONEY",
"value": 1.57,
"currency": "RUB"
},
"remainingValue": {
"type": "MONEY",
"value": 4998.43,
"currency": "RUB"
},
"limitPeriod": {
"periodFrom": "2022-02-03T00:00:00+03:00",
"periodTill": "2022-02-03T23:59:59+03:00",
"periodType": "ON_DAY"
},
"limitType": "CASH_WITHDRAWAL_OPERATIONS"
},
{
"maxValue": {
"type": "MONEY",
"value": 60000.00,
"currency": "RUB"
},
"accumulatedValue": {
"type": "MONEY",
"value": 8.22,
"currency": "RUB"
},
"remainingValue": {
"type": "MONEY",
"value": 59991.78,
"currency": "RUB"
},
"limitPeriod": {
"periodType": "LIFETIME"
},
"limitType": "BALANCE"
}
]
В теле успешного ответа возвращается список лимитов, как сервисных, так и установленных партнером для пользователя. Если у пользователя нет счетов, то лимит на допустимый остаток (тип лимита BALANCE
) не возвращается. Каждый элемент списка содержит следующие параметры:
Параметр | Тип | Описание |
---|---|---|
limitType | string | Тип лимита |
limitPeriod | object | Блок с информацией о периоде действия лимита |
periodType | string | Тип периода действия лимитов |
periodFrom | string | Дата начала периода, в формате ISO 8601 ±hh:mm с московской Time Zone |
periodTill | string | Дата окончания периода, в формате ISO 8601 ±hh:mm с московской Time Zone |
maxValue | object LimitData | Блок с информацией о максимально допустимой сумме операций в рублях за указанный период для этого лимита. Для типа BALANCE — информация о максимально допустимой сумме остатка на счете пользователя. |
accumulatedValue | object LimitData | Блок с информацией о сумме операций (израсходованная часть) в рублях за указанный период для этого лимита. Для типа лимита BALANCE — информация о текущем значении остатка на счете пользователя. |
remainingValue | object LimitData | Блок с информацией об оставшейся (неизрасходованной) сумме в рублях за указанный период для этого лимита. Для типа лимита BALANCE — информация о максимально допустимой сумме, на которую пользователь может пополнить счет в настоящий момент времени. |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Модели данных API
Класс LimitData
Объект с информацией о значении лимита.
Параметр | Тип | Описание |
---|---|---|
type | string | Обязательный параметр. Тип данных. Принимает значение MONEY (для лимитов, значения которых задаются в денежном выражении, в частности CUSTOMIZABLE_EXPENSE_OPERATIONS ) или INT (для лимитов, значения которых задаются целым числом) |
value | number | Обязательный параметр. Для "type":"MONEY" : значение с двумя десятичными разрядами.Для "type":"INT" : целое число. |
currency | string | Валюта, ISO 4217. Только для "type":"MONEY" . |
Справочники
Типы лимитов
Тип | Описание |
---|---|
BALANCE | Допустимый остаток на счете пользователя |
EXPENSE_OPERATIONS | Допустимая сумма платежей и переводов |
CASH_WITHDRAWAL_OPERATIONS | Допустимая сумма на снятие наличных с карт |
CUSTOMIZABLE_EXPENSE_OPERATIONS | Допустимая сумма на другую операцию |
Типы периодов действия лимитов
Тип | Описание |
---|---|
LIFETIME | Все время жизни продукта: для этого типа периода даты начала и окончания периода указывать не нужно. |
ON_HOUR | Час |
ON_DAY | Календарный день |
ON_WEEK | Календарная неделя |
ON_MONTH | Календарный месяц |
ON_YEAR | Календарный год |
Формат ошибок API
В разделе описывается структура ответа на неуспешный запрос.
{
"serviceName" : "openapi-limits",
"errorCode" : "openapi.limits.unsupported.limit.type",
"description" : "Undefined error. Please try to make operation later.",
"userMessage" : "Undefined error. Please try to make operation later.",
"dateTime" : "2022-08-10T13:42:33.843663+03:00",
"traceId" : "b213b51102380a77"
}
Параметр | Описание |
---|---|
serviceName | Имя сервиса, который вернул ошибку |
errorCode | Код ошибки. См. справочник кодов ошибок |
dateTime | Дата и время формирования ответа |
traceId | Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовке ответа X-B3-TraceId |
cause | Причина ошибки, опциональный параметр |
Справочник кодов ошибок
Код | Описание |
---|---|
openapi.limits.client.not.found | Пользователь не найден |
openapi.limits.client.blocked | Пользователь заблокирован |
openapi.limits.wrong.date.interval | Пользователь не найден |
openapi.limits.wrong.date.interval | Неправильный интервал дат (например, dateFrom позднее dateTill) |
openapi.limits.unsupported.limit.type | Неподдерживаемый для установки тип лимита |
openapi.limits.unsupported.limit.period | Неподдерживаемый для установки период лимита |
openapi.limits.unsupported.limit.value.type | Несоответствие типа значения лимита (limitValue.type) его значению (limitValue.value) |
openapi.limits.limit.value.type.mismatch | Несоответствие значения лимита его типу (например, для денежного лимита передано значение с type = INT) |
openapi.limits.invalid.limit.value | Некорректное значение лимита (например, отрицательное) |