CLIENTS API
Последнее обновление: 04-03-2021 |
Интерфейс предназначен для создания счета электронных денежных средств из пользовательского интерфейса партнера, а также для получения информации о пользователе: его текущем статусе идентификации, установленных лимитах и т.д.
Здесь и далее по тексту:
- пользовательский интерфейс - web-сайт или мобильное приложение;
- пользователь - клиент (физическое лицо), использующий интерфейс;
- партнер - юридическое лицо, использующее данный API с целью предоставить физическим лицам платежную функциональность в своем интерфейсе.
Взаимодействие между партнёром и сервисом Clients происходит по защищенному протоколу (HTTPS). Данные при запросах передаются в формате JSON в кодировке UTF-8. В ответе данные возвращаются в формате JSON в кодировке UTF-8.
Авторизация
Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.
Схема аутентификации - Bearer.
В заголовках запроса передаётся bearer-токен в поле Authorization
--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"
Bearer-токен выдается партнеру при интеграции.
URL для вызовов API
- https://api-test.qiwi.com - testing окружение;
- https://api.qiwi.com - production окружение.
Взаимодействие через API
Создание пользователя
Для создания пользователя необходимо отправить PUT-запрос.
Запрос → PUT
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
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
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
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
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/accounts/{accountId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
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
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/accounts/{accountId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
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
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/accounts
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
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
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/limits?limitTypes={limitTypes}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
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" \
}'
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/metadata
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8/json
Параметры запроса
| Параметр | Тип | Описание |
|---|---|---|
| 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 | Пользователь находится в тестовом режиме |