CLIENTS API
Последнее обновление: 07-02-2022
Сервис Clients предназначен для создания счета электронных денежных средств из пользовательского интерфейса партнера, а также для получения информации о пользователе: его текущем уровне идентификации, установленных лимитах и т.д.
Термины, используемые в тексте:
- пользовательский интерфейс — web-сайт или мобильное приложение;
- пользователь — клиент (физическое лицо), использующий интерфейс;
- партнер — юридическое лицо, использующее API с целью предоставить физическим лицам платежную функциональность в своем интерфейсе.
Авторизация
Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.
Схема аутентификации - Bearer.
В заголовках запроса передаётся bearer-токен в поле Authorization
--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"
Bearer-токен выдается партнеру при интеграции.
URL для вызовов API
- https://api-test.qiwi.com - testing окружение;
- https://api.qiwi.com - production окружение.
Взаимодействие через API
Взаимодействие между партнёром и сервисом Clients происходит по защищенному протоколу (HTTPS). Данные при запросах передаются в формате JSON в кодировке UTF-8. В ответе данные возвращаются в формате JSON в кодировке UTF-8.
С помощью API вы можете:
- Создать пользователя.
- Создать счет электронных денежных средств для пользователя.
- Запросить информацию о пользователе, всех его счетах или отдельном счете.
- Запросить информацию об установленных для пользователя ограничениях (лимитах).
Вы должны отправлять метаданные пользователя при определенных его действиях в приложении партнера.
Создание пользователя
Метод создает пользователя с указанным идентификатором для партнера.
Запрос → 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 | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого происходит создание пользователя: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
| clientIpAddress | string Обязательный параметр тела запроса. IP-адрес пользователя, для которого партнер отправляет запрос |
валидный IPv4/IPv6 | 255.255.255.255, 2001:0db8:85a3:0000:0000:8a2e:0370:7334 |
| createInactive | boolean Если true, то после создания пользователь не сможет совершать платежи, пока не будет активирован. По умолчанию false, т. е. пользователь сможет платить сразу после создания. |
^true|false$ | true |
Ответ ←
Пример ответа
{
"clientId": "clientUID123",
"productId": "best-partner",
"identificationLevel": "NOT_VERIFIED",
"active": true
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | string | Идентификатор продукта, в рамках которого создан пользователь |
| clientId | string | Уникальный идентификатор пользователя в системе партнера |
| identificationLevel | string | Текущий уровень идентификации пользователя. При создании пользователю присваивается уровень NOT_VERIFIED, т. е. "Не верифицированный (аноним)". |
| active | boolean | Показывает, активирован ли пользователь. Неактивированный пользователь не может совершать платежи. |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Активация пользователя
Метод активирует пользователя с указанным идентификатором для партнера. Запрос выполняется в случае, когда при создании пользователь был неактивированным. После активации такой пользователь сможет совершать платежи.
Запрос → POST
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/activate
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
| Параметр | Описание | 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 |
Ответ ←
См. ответ на запрос создания пользователя.
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение информации по пользователю
Метод возвращает информацию о пользователе с указанным идентификатором.
Запрос → 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 | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
Ответ ←
См. ответ на запрос создания пользователя.
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Создание счета для пользователя
Метод создает счет электронных денежных средств для пользователя с указанным идентификатором.
Запрос → 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 | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
| accountId | Обязательный параметр URL запроса. Уникальный идентификатор счета в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Acc-123-DEF-456 |
| accountCurrency | string Обязательный параметр тела запроса. Буквенный код валюты создаваемого счета |
RUB |
Коды валют
На текущий момент поддерживаются следующие валюты:
| Код | Описание |
|---|---|
| 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 | object Money | Информация о доступных средствах на счете пользователя. Возвращается в тех случаях, когда баланс ведется в QIWI. |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение информации по счету пользователя
Метод возвращает информацию о счете пользователя с указанным идентификатором.
Запрос → 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 | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого создан пользователь: выдается партнеру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| clientId | Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
| accountId | Обязательный параметр URL запроса. Уникальный идентификатор счета в системе партнера | ^[A-Za-z0-9-]{1,100}$ | Acc-123-DEF-456 |
Ответ ←
См. ответ на запрос создания счета для пользователя.
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение информации по всем счетам пользователя
Метод возвращает информацию о всех счетах пользователя с указанным идентификатором.
Запрос → 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/clients/clientUID123/accounts
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
| Параметр | Описание | 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 |
Ответ ←
Пример ответа
{
"clientId": "clientUID123",
"productId": "best-partner",
"accounts": {
"account1":{
"currency": "RUB",
"ownFunds":{
"value": 10.12,
"currency":"RUB"
}
},
"account2":{
"currency": "EUR",
"ownFunds":{
"value": 10.12,
"currency":"EUR"
}
}
}
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | string | Идентификатор продукта, в рамках которого создан пользователь |
| clientId | string | Уникальный идентификатор пользователя в системе партнера |
| accounts | object | Блок сведений о счетах пользователя. Сведения о каждом счете возвращаются во вложенном блоке с именем, равным уникальному идентификатору этого счета в системе партнера |
| currency | string | Валюта счета |
| ownFunds | object Money | Информация о доступных средствах на счете пользователя. Возвращается в тех случаях, когда баланс ведется в QIWI. |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение информации по установленным для пользователя ограничениям
В рамках банковской платформы для пользователя установлены законодательные ограничения (лимиты) на пополнение наличными, платежи, переводы и на остаток на балансе. Размер ограничений зависит от присвоенного пользователю уровня идентификации.
Запрос → 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/clients/clientUID123/limits?limitTypes=EXPENSE_OPERATIONS
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
| Параметр | Описание | 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 запроса. Тип ограничения. Указывается для фильтрации выборки. Чтобы ограничить выборку сразу несколькими типами, укажите параметр нужное количество раз. | 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" : "CASH_WITHDRAWAL_OPERATIONS"
} ]
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | string | Идентификатор продукта, в рамках которого создан пользователь |
| clientId | string | Уникальный идентификатор пользователя в системе партнера |
| limits | array of objects | Блок со списком ограничений |
| limitType | string | Тип ограничения |
| limitPeriod | object | Блок с информацией по временному периоду действия ограничения |
| periodType | string | Тип периода |
| periodFrom | string | Дата начала периода, в формате ISO 8601 ±hh:mm с московской Time Zone |
| periodTill | string | Дата окончания периода, в формате ISO 8601 ±hh:mm с московской Time Zone |
| maxAmount | object Money | Блок с информацией о максимально допустимой сумме операций по определенному типу лимита. Для типа BALANCE — информация о максимально допустимой сумме остатка на счете пользователя. |
| currentAmount | object Money | Блок с информацией об оставшейся (неизрасходованной) сумме операций за указанный период по определенному типу лимита. Для типа ограничения BALANCE — информация о максимально допустимой сумме, на которую пользователь может пополнить счет в настоящий момент времени. |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Типы ограничений
| Тип | Описание |
|---|---|
| BALANCE | Допустимый остаток на счете пользователя |
| EXPENSE_OPERATIONS | Допустимая сумма платежей и переводов |
| CASH_WITHDRAWAL_OPERATIONS | Допустимая сумма на снятие наличных с карт |
Типы периодов действия ограничений
| Тип | Описание |
|---|---|
| LIFETIME | Все время жизни продукта: для этого типа периода не заполняются periodFrom и periodTill |
| ON_HOUR | Час |
| ON_DAY | Календарный день |
| ON_WEEK | Календарная неделя |
| ON_MONTH | Календарный месяц |
| ON_YEAR | Календарный год |
Отправка метаданных пользователя
Для предотвращения мошеннических действий в системе, партнер должен отправлять метаданные при определенных действиях клиента в приложении партнера:
- Если клиент установил номер телефона для входа в приложение.
- Если клиент выполнил успешный вход в приложение.
- Если клиент успешно сменил пароль для входа в приложение.
- Выполнена отправка SMS-подтверждения при попытке смены пароля для входа в приложение.
- Успешно изменен PIN-код для доступа в приложение.
- Выполнена отправка SMS-подтверждения при попытке смены PIN-кода для входа в приложение.
Запрос → 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
Параметры запроса
| Параметр | Описание |
|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого создан клиент |
| clientId | Обязательный параметр URL запроса. Уникальный идентификатор клиента в системе партнера |
| 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 Параметр тела запроса. Дата наступления события в формате ГГГГ-ММ-ДДTЧЧ:ММ:СС+TMZ. Передается для всех вариантов событий, кроме SIGN_IN_PHONE_NUMBER_SET |
Ответ ←
В успешном ответе возвращается HTTP-статус 200 OK. Тело успешного ответа не содержит данных.
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Добавление контактных данных пользователя
Метод добавляет контактные данные для пользователя с указанным идентификатором.
Запрос → PUT
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact
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/contact
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
"phoneNumber": "79786543210",
"email": "mary@example.com"
}
'
| Параметр | Описание | 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 |
| phoneNumber | string Номер телефона клиента (без знака +, только цифры). |
\^\d{11,16}$ | 79786543210 |
| string Электронная почта клиента | mary@example.com |
Ответ ←
Пример ответа
{
"phoneNumber": "79786543210",
"email": "mary@example.com"
}
| Параметр | Тип | Описание |
|---|---|---|
| phoneNumber | string | Номер телефона клиента |
| string | Электронная почта клиента |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение контактных данных пользователя
Метод возвращает контактные данные для пользователя с указанным идентификатором.
Запрос → GET
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
| Параметр | Описание | 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 |
Ответ ←
Пример ответа
{
"phoneNumber": "79786543210",
"email": "mary@example.com"
}
| Параметр | Тип | Описание |
|---|---|---|
| phoneNumber | string | Номер телефона клиента |
| string | Электронная почта клиента |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Установка значения телефонного номера пользователя
Метод устанавливает телефонный номер пользователя с указанным идентификатором для партнера.
Запрос → PUT
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact/phone
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/contact/phone
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
"value": "79786543210",
}
'
| Параметр | Описание | 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 |
| value | string Номер телефона клиента (без знака +, только цифры). |
\^\d{11,16}$ | 79786543210 |
Ответ ←
Пример ответа
{
"value": "79786543210"
}
| Параметр | Тип | Описание |
|---|---|---|
| value | string | Установленный контактный номер телефона |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение телефонного номера пользователя
Метод возвращает телефонный номер пользователя с указанным идентификатором.
Запрос → GET
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact/phone
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/phone
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
| Параметр | Описание | 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 |
Ответ ←
Пример ответа
{
"value": "79786543210"
}
| Параметр | Тип | Описание |
|---|---|---|
| value | string | Телефонный номер пользователя |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Установка значения e-mail пользователя
Метод добавляет или меняет существующий e-mail для пользователя с указанным идентификатором.
Запрос → PUT
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact/email
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/contact/email
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
"value": "mary@example.com"
}'
| Параметр | Описание | 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 |
| value | string Адрес электронной почты клиента | mary@example.com |
Ответ ←
Пример ответа
{
"value": "test@example.com"
}
| Параметр | Тип | Описание |
|---|---|---|
| value | string | Адрес электронной почты пользователя |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Получение e-mail пользователя
Метод возвращает e-mail пользователя с указанным идентификатором.
Запрос → GET
URL /partner/openapi-clients/v1/products/{productId}/clients/{clientId}/contact/email
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/email
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
| Параметр | Описание | 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 |
Ответ ←
Пример ответа
{
"value": "test@example.com"
}
| Параметр | Тип | Описание |
|---|---|---|
| value | string | Электронная почта пользователя |
Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.
Уровни идентификации
| Уровень | Описание |
|---|---|
| NOT_VERIFIED | Не верифицированный: аноним. Присваивается пользователю автоматически при его создании в сервисе Clients. |
| SIMPLIFIED | Упрощенно-идентифицированный |
| SIMPLIFIED_RESTRICTED | Упрощенно-идентифицированный с ограниченными возможностями: меньшими, чем у SIMPLIFIED |
| FULL | Полностью идентифицированный |
| FULL_RESTRICTED | Полностью идентифицированный с ограниченными возможностями: меньшими, чем у FULL |
Уровни Упрощенно-идентифицированный и Полностью идентифицированный присваиваются пользователю после прохождения процедуры с помощью API идентификации. Это позволяет убрать ограничения (пользователь сможет пополнять счет наличными, совершать переводы другому пользователю) или изменить их (увеличить допустимую сумму платежей и т.д.).
Модели данных API
Класс Money
Объект с информацией о сумме денежных средств.
| Параметр | Обязательность | Тип | Описание |
|---|---|---|---|
| value | ✓ | number | Значение с двумя десятичными разрядами |
| currency | ✓ | string | Валюта, ISO 4217 |
Формат ошибок 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 | Пользователь находится в тестовом режиме |