Вопросы
baas_support@qiwi.com
NAV Navbar
shell

CLIENTS API

Последнее обновление: 04-03-2021 |

Интерфейс предназначен для создания счета электронных денежных средств из пользовательского интерфейса партнера, а также для получения информации о пользователе: его текущем статусе идентификации, установленных лимитах и т.д.

Здесь и далее по тексту:

Взаимодействие между партнёром и сервисом Clients происходит по защищенному протоколу (HTTPS). Данные при запросах передаются в формате JSON в кодировке UTF-8. В ответе данные возвращаются в формате JSON в кодировке UTF-8.

Авторизация

Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются. Схема аутентификации - Bearer. В заголовках запроса передаётся bearer-токен в поле Authorization

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

Bearer-токен выдается партнеру при интеграции.

URL для вызовов API

Взаимодействие через API

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

Для создания пользователя необходимо отправить PUT-запрос.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d '{
  "clientIpAddress": "255.255.255.255"
}'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого происходит создание пользователя: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +
clientIpAddress IP-адрес пользователя, для которого партнер отправляет запрос String валидный IPv4/IPv6 255.255.255.255, 2001:0db8:85a3:0000:0000:8a2e:0370:7334 +

Ответ ←

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

{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "identificationLevel": "NOT_VERIFIED"
}
Параметр Тип Описание
productId String Идентификатор продукта, в рамках которого создан пользователь
clientId String Уникальный идентификатор пользователя в системе партнера
identificationLevel String Текущий уровень идентификации пользователя: см. значения в данном разделе

Получение информации по пользователю

Для получения информации по пользователю необходимо отправить GET-запрос.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +

Ответ ←

См. ответ на данный запрос.

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

Для создания счета необходимо отправить PUT-запрос.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/accounts/account1
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d '{
  "accountCurrency": "RUB"
}'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +
accountId Уникальный идентификатор счета в системе партнера String ^[A-Za-z0-9-]{1,100}$ Acc-123-DEF-456 +
accountCurrency Буквенный код валюты создаваемого счета String   Пример +

Коды валют

На текущий момент поддерживаются следующие валюты:

Код Описание
RUB Рубли

Ответ ←

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


{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "accountId": "account1",
    "currency": "RUB",
    "ownFunds": {
        "currency": "RUB",
        "value": "10.12",
    }
}
Параметр Тип Описание
productId String Идентификатор продукта, в рамках которого создан пользователь
clientId String Уникальный идентификатор пользователя в системе партнера
accountId String Уникальный идентификатор счета в системе партнера
currency String Валюта счета
ownFunds String Информация о доступных средствах на счете пользователя, параметр опционален в ответе: приходит в тех случаях, когда баланс ведется в QIWI.

Запрос информации по счету пользователя

Для получения информации по счету необходимо отправить GET-запрос.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/accounts/account1
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +
accountId Уникальный идентификатор счета в системе партнера String ^[A-Za-z0-9-]{1,100}$ Acc-123-DEF-456 +

Ответ ←

См. ответ на данный запрос.

Запрос информации по всем счетам пользователя

Для получения информации по всем счетам пользователя необходимо отправить GET-запрос.

Запрос → GET

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

curl https://api.qiwi.com/partner/openapi-clients/v1/products/best-partner/client/clientUID123/accounts
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +

Ответ ←

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

{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "accounts": {
        "account1":{
            "currency": "RUB",
            "ownFunds":{
                "value": "10.12",
                "currency":"RUB"
            }
        },
        "account2":{
            "currency": "EUR",
            "ownFunds":{
                "value": "10.12",
                "currency":"EUR"
            }
        }
    }
}

См. ответ на данный запрос.

Запрос информации по установленным для пользователя ограничениям

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

Данный метод возвращает информацию по установленным для пользователя ограничениям: лимитам, которые соответствуют его текущему статусу. Для получения информации необходимо отправить GET-запрос.

Запрос → GET

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

curl https://api.qiwi.com/partner/openapi-clients/v1/products/best-partner/client/clientUID123/limits?limitTypes=EXPENSE_OPERATIONS
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание Тип REGEX Пример Обяз.
productId Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции String ^[A-Za-z0-9-]{1,100}$ Prd-123-DEF-456 +
clientId Уникальный идентификатор пользователя в системе партнера String ^[A-Za-z0-9-]{1,100}$ Cnt-123-DEF-456 +
limitTypes Тип ограничения. Указывается при необходимости сузить выборку конкретными типами. При желании ограничить выборку сразу несколькими типами - данный параметр в запросе необходимо передать нужное количество раз. String   EXPENSE_OPERATIONS -

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

{
  "productId" : "best-partner",
  "clientId" : "tqrxbwhnso6563448632",
  "limits" : [ {
    "maxAmount" : {
      "currency" : "RUB",
      "value" : "15000.00"
    },
    "currentAmount" : {
      "currency" : "RUB",
      "value" : "14993.66"
    },
    "limitPeriod" : {
      "periodType" : "LIFETIME"
    },
    "limitType" : "BALANCE"
  }, {
    "maxAmount" : {
      "currency" : "RUB",
      "value" : "40000.00"
    },
    "currentAmount" : {
      "currency" : "RUB",
      "value" : "39993.33"
    },
    "limitPeriod" : {
      "periodFrom" : "2021-08-01T00:00:00+03:00",
      "periodTill" : "2021-08-31T23:59:59+03:00",
      "periodType" : "ON_MONTH"
    },
    "limitType" : "EXPENSE_OPERATIONS"
  }, {
    "maxAmount" : {
      "currency" : "RUB",
      "value" : "0.00"
    },
    "currentAmount" : {
      "currency" : "RUB",
      "value" : "0.00"
    },
    "limitPeriod" : {
      "periodFrom" : "2021-08-01T00:00:00+03:00",
      "periodTill" : "2021-08-31T23:59:59+03:00",
      "periodType" : "ON_MONTH"
    },
    "limitType" : "WITHDRAWAL_OPERATIONS_CASH_ONLY"
  } ]
}
Параметр Тип Описание
productId String Идентификатор продукта, в рамках которого создан пользователь
clientId String Уникальный идентификатор пользователя в системе партнера
limits   Блок со списком ограничений
limitType String Тип ограничения
limitPeriod   Блок с информацией по временному периоду действия ограничения
periodFrom DateTime в формате ISO 8601 ±hh:mm с московской Time Zone Дата начала периода
periodTill DateTime в формате ISO 8601 ±hh:mm с московской Time Zone Дата окончания периода
periodType String Тип периода
maxAmount   Блок с информацией о максимально допустимой сумме операций по определенному типу лимита. Для типа BALANCE — максимально допустимая сумма остатка на счете пользователя.
currency String Валюта, ISO 4217
value String Значение с двумя десятичными разрядами
currentAmount   Блок с информацией об оставшейся (неизрасходованной) сумме операций за указанный период по определенному типу лимита. Для типа BALANCE — максимально допустимая сумма, на которую пользователь может пополнить счет в настоящий момент времени.
currency String Валюта, ISO 4217
value String Значение с двумя десятичными разрядами

Типы ограничений

Тип Описание
BALANCE Допустимый остаток на счете пользователя
EXPENSE_OPERATIONS Допустимая сумма платежей и переводов
WITHDRAWAL_OPERATIONS_CASH_ONLY Допустимая сумма на снятие наличных с карт

Типы периодов действия ограничений

Тип Описание
LIFETIME Все время жизни продукта: для этого типа периода не будут заполнены periodFrom и periodTill
ON_HOUR Час
ON_DAY День
ON_WEEK Неделя
ON_MONTH Месяц
ON_YEAR Год

Отправка метаданных по пользователю

Для предотвращения мошеннических действий в системе, партнер должен отправлять метаданные при определенных действиях клиента в приложении партнера.

Для отправки метаданных о действиях клиента необходимо отправить PATCH-запрос:

Запрос → PATCH

Пример запроса для события установки номер телефона для входа в приложение (SIGN_IN_PHONE_NUMBER_SET)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PHONE_NUMBER_SET", \
	"phoneNumber" : "79786543210" \
	}'

Пример запроса для события успешного входа в приложение (SUCCESSFUL_SIGN_IN)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SUCCESSFUL_SIGN_IN", \
	"signInIp" : "49.76.45.39", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события успешной смена пароля для входа в приложение (SIGN_IN_PASSWORD_CHANGED)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PASSWORD_CHANGED", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события отправки смс-подтверждения при попытке смены пароля для входа в приложение (SIGN_IN_PASSWORD_CONFIRMATION_SENT)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PASSWORD_CONFIRMATION_SENT", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события успешной смены пин-кода для доступа в приложение (SIGN_IN_PIN_CHANGED)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PIN_CHANGED", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события отправки смс-подтверждения при попытке смены пин-кода для входа в приложение (SIGN_IN_PIN_CONFIRMATION_SENT)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PIN_CONFIRMATION_SENT", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'
Параметр Тип Описание
productId String Идентификатор продукта, в рамках которого создан клиент
clientId String Уникальный идентификатор клиента в системе партнера
clientUseCase String Вариант события взаимодействия с клиентом на стороне партнера. Возможные значения:
SIGN_IN_PHONE_NUMBER_SET — клиент установил номер телефона для входа в приложение
SUCCESSFUL_SIGN_IN — успешный вход в приложение
SIGN_IN_PASSWORD_CHANGED — успешная смена пароля для входа в приложение
SIGN_IN_PASSWORD_CONFIRMATION_SENT — отправка смс-подтверждения при попытке смены пароля для входа в приложение
SIGN_IN_PIN_CHANGED — успешная смена пин-кода для доступа в приложение
SIGN_IN_PIN_CONFIRMATION_SENT — отправка смс-подтверждения при попытке смены пин-кода для входа в приложение

В зависимости от типа события, указанного в clientUseCase, в запросе передаются дополнительные поля:

Событие SIGN_IN_PHONE_NUMBER_SET

		{
		"clientUseCase": "SIGN_IN_PHONE_NUMBER_SET",
		"phoneNumber" : "79786543210"
		}

Событие SUCCESSFUL_SIGN_IN

		{
		"clientUseCase": "SUCCESSFUL_SIGN_IN",
		"signInIp" : "49.76.45.39",
		"dateTime": "2021-01-20T14:30:00+03:00"
		}

Прочие события

		{
		"clientUseCase": "SIGN_IN_PASSWORD_CHANGED",
		"dateTime": "2021-01-20T14:30:00+03:00"
		}
Параметр Тип Описание
phoneNumber String номер телефона клиента (без знака "+", только числовое значение). Передается только для варианта события SIGN_IN_PHONE_NUMBER_SET.
signInIp String IP-адрес клиента. Передается только для варианта события SUCCESSFUL_SIGN_IN.
dateTime String дата наступления события в формате "2021-01-20T14:30:00+03:00". Передается для всех вариантов событий, кроме SIGN_IN_PHONE_NUMBER_SET.

Ответ

Тело ответо пустое.

Статусы идентификации

Статус Описание
NOT_VERIFIED Не верифицированный: аноним
SIMPLIFIED Упрощенно-идентифицированный
SIMPLIFIED_RESTRICTED Упрощенно-идентифицированный с ограниченными возможностями: меньшими, чем у SIMPLIFIED
FULL Полностью идентифицированный
FULL_RESTRICTED Полностью идентифицированный с ограниченными возможностями: меньшими, чем у FULL

Статус «Аноним» присваивается пользователю автоматически при его создании в сервисе Clients. Получение статусов «Упрощенно-идентифицированный» и «Полностью идентифицированный» осуществляется путем прохождения пользователем определенной процедуры: используется API идентификации. Это позволяет убрать ограничения (пользователь сможет пополнять счет наличными, совершать переводы другому пользователю) или изменить их (увеличить допустимую сумму платежей и т.д.).

Ошибки

Ниже — описание ответа на неуспешный запрос.

Ответ ←

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

{
    "serviceName": "openapi-clients",
    "errorCode": "openapi.clients.client.not.found",
    "dateTime": "2020-07-23T20:13:22.290416+03:00",
    "traceId": "67477569e8bc6838"
} 
Название Описание
serviceName Имя сервиса, который вернул ошибку
errorCode Код ошибки. См. справочник кодов ошибок
dateTime Дата и время формирование ответа
traceId Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовках ответа (response headers) в параметре X-B3-TraceId

Справочник кодов ошибок

Код Описание
openapi.clients.product.not.found Продукт не найден
openapi.clients.client.not.found Пользователь не найден
openapi.clients.client.blocked Пользователь заблокирован
openapi.clients.internal.error В сервисе Clients произошла внутренняя ошибка
openapi.clients.client.already.exists Пользователь уже существует
openapi.clients.account.already.exists Счет уже существует
openapi.clients.account.not.found Счет пользователя не найден
openapi.clients.unsupported.currency Валюта не поддерживается
openapi.clients.unsupported.multiple.accounts.per.currency Возвращается при попытке создания более одного счета в одной и той же валюте. Для партнера отдельно настраивается возможность создавать несколько счетов в одной и той же валюте.
openapi.clients.client.must.be.in.test.mode Пользователь находится в тестовом режиме