Перейти к содержанию

Управление клиентом и его счётом

В этой статье описаны основные сценарии управления клиентом и его счётом, а также технические ограничения, которые необходимо учитывать при их выполнении.

Создание клиента и счёта

Создание клиента и счёта являются обязательными этапами информационного взаимодействия с платформой и выполняются последовательно — партнёр:

В результате появляется электронный кошелёк.

Обратите внимание

Клиент:

не может совершать платежи, а также ряд иных (нефинансовых) операций.

Сценарий «Создание клиента и счёта» может быть привязан к какому-либо событию в системе партнёра или выполняться независимо.

Примеры событий

Клиент партнёра (физическое лицо):

  • зарегистрировался в интерфейсе;
  • авторизовался в интерфейсе;
  • захотел открыть электронный кошелёк или выпустить карту — нажал на кнопку в интерфейсе, сформировал устный или письменный запрос и т.д.

Успешный сценарий «Создание клиента и счёта» изображён на диаграмме ниже.

Обратите внимание

При необходимости для одного физического лица может быть создано несколько clientId в платформе.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "actorMargin":
        155 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
      С->>P: Событие/действие
      P->>+B: Запрос на создание клиента
      Note right of P: productId, clientId, clientIpAddress
      B-->>-P: Ответ на запрос создания клиента
      Note left of B: productId, clientId, identificationLevel, active, creationStatus: PENDING_CLIENT_TOKEN
      rect rgb(230, 230, 230)
      P->>+B: Сценарий «Аутентификация с помощью OTP»
      Note right of P: OTP для confirmationOperationType:CREATE_TOKEN
      B-->>-P: 
      Note left of B: confirmationId, confirmationStatus:CONFIRMED
      end
      rect rgb(255, 238, 223)
      P->>+B: Сценарий «Выпуск токена»
      Note right of P: confirmationId
      B->>B: Изменение статуса создания клиента
      Note over B: creationStatus: CREATED
      B-->>-P: 
      Note left of B: tokenValue
      end
      P->>+B: Запрос на создание счёта
      Note right of P: productId, clientId, accountId, accountCurrency
      B-->>-P: Ответ на запрос создания счёта
      Note left of B: productId, clientId, accountId, currency, ownFunds
      P->>P: Связь accountId и clientId
      P->>С: Коммуникация с клиентом

Запросы описаны в документации Clients API. Упомянутые на диаграмме сценарии см. в статье «Общие принципы и правила» → «Подтверждение операций».

Важная информация

При реализации данного сценария необходимо учитывать существующие в платформе ограничения.

Жизненный цикл операции создания клиента

flowchart TD
    Start --> PENDING_CLIENT_TOKEN
    Start --> errorCode
    PENDING_CLIENT_TOKEN --> CREATED

Партнёр отправляет запрос на создание клиента. BaaS возвращает партнёру один из ответов:

  • HTTP 200 OK и confirmationStatus:PENDING_CLIENT_TOKEN — операция создана, ожидается выпуск клиентского токена;
  • HTTP 4xx/5xx и errorCode — данные не прошли валидацию или другие внутренние проверки ⇒ операция подтверждения не создана по причине, указанной в errorCode.

Ошибку (errorCode) необходимо интерпретировать согласно справочнику кодов ошибок, обработать и затем возобновить работу с операцией, если ошибка не является фатальной и её можно устранить.

Партнёр выполняет сценарии «Аутентификация с помощью OTP» и «Выпуск токена» ⇒ операция переходит в статус CREATED — клиент успешно создан.

Если клиентский токен не был выпущен, операция остаётся в статусе CREATED.

Ограничения

  • Финансовые операции может выполнять только активный клиент, для которого выпущен токен.
  • Счёт создаётся для конкретного клиента: без предварительного заведения clientId создать счёт не удастся.
  • Счёт создаётся в валюте RUB, другие валюты недоступны.

  • Для клиента может быть создан лишь один счёт.

    Пример

    • Для клиента с идентификатором client1 создан счёт с идентификатором account1.
    • Попытка создать для client1 счёт с идентификатором account2 будет неуспешной.

Активность клиента

Клиент может быть создан активным или неактивным.

Активный клиент может совершить любые действия, в том числе:

Неактивному клиенту доступны лишь некоторые из них, такие как просмотр баланса и лимитов. Подробнее см. в разделе «Список разрешённых действий».

По умолчанию клиент создаётся активным. Создание неактивного клиента описано в одноимённом разделе.

Создание неактивного клиента

При выполнении запроса на создание клиента может быть задан признак его активности (createInactive). Значение true говорит о создании неактивного клиента.

Если партнёр создаст активного клиента — тот сможет сразу совершать платежи в рамках законодательных лимитов. Иногда партнёру требуется выполнить ряд подготовительных действий до того, как клиент совершит платёж. Например установить собственные лимиты и запретить проведение определённых операций. В этом случае мы рекомендуем создавать клиента с признаком createInactive:true и активировать его лишь после завершения необходимых действий.

Список разрешённых действий

Список запросов, которые разрешено выполнять для неактивного client_id:

Запросы описаны в документации Clients API, Limits API и Cards-lifecycle API.

Активация клиента

Активация клиента предполагает последовательное выполнение следующих шагов:

  • создать неактивного клиента и счёт;
  • осуществить необходимые действия (например установить собственные лимиты и запретить проведение определённых операций);
  • активировать клиента.

Пример использования сценария «Активация клиента» изображён на диаграмме ниже. Сценарий «Создание клиента и счёта» см. в данном разделе. Остальные упомянутые на диаграмме сценарии см. в статьях:

sequenceDiagram
    participant P as Партнёр
    participant B as BaaS
    rect rgb(230, 230, 230)
    P->>+B: Сценарий «Создание клиента и счёта» (Clients API)
    Note right of P: В запросе на создание клиента следует передать createInactive:true
    B-->>-P: 
    end
    rect rgb(255, 238, 223)
    P->>+B: Сценарий «Установка лимита» (Limits API)
    B-->>-P: 
    end
    rect rgb(230, 230, 230)
    P->>+B: Сценарий «Выпуск банковской карты» (Cards-lifecycle API)
    B-->>-P: 
    end
    rect rgb(255, 238, 223)
    P->>+B: Сценарий «Создание правил проведения авторизаций» (Cards-lifecycle API)
    B-->>-P: 
    end
    P->>+B: Запрос на активацию клиента (Clients API)
    Note right of P: productId, clientId
    B-->>-P: Ответ на запрос активации клиента
    Note left of B: productId, clientId, identificationLevel, active: true

Запросы описаны в документации Clients API, Limits API и Cards-lifecycle API.

Установка и изменение номера телефона

При создании учётной записи клиента партнёр аутентифицирует клиента с помощью OTP от QIWI. Сценарий аутентификации предполагает передачу номера телефона клиента QIWI (BaaS). Этот номер устанавливается в качестве контактного и используется в дальнейшем в других бизнес-сценариях, таких как аутентификация при покупке с помощью 3D-Secure.

Если номер клиента изменился, партнёру необходимо сообщить об этом BaaS — последовательно выполнить следующие действия:

  • аутентифицировать клиента с помощью OTP от QIWI;

    Необходимо отправить два запроса на отправку OTP: клиент должен подтвердить и текущий, и новый номер телефона.

  • отправить запрос на установку или изменение номера телефона к Clients API.

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

Чтобы своевременно узнавать об изменении номера телефона, партнёр может:

  • периодически запрашивать у клиента подтверждение его личных данных;
  • самостоятельно отслеживать факт изменения номера — если это допустимо с точки зрения действующего законодательства.

Пример успешного сценария изменения номера телефона изображён на диаграмме ниже.

sequenceDiagram
%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":150}}}%%
    participant P as Партнёр
    participant B as BaaS
      Note left of P: Номер телефона клиента изменился
      rect rgb(230, 230, 230)
      P->>+B: Сценарий «Аутентификация с помощью OTP»
      Note over P,B: OTP для confirmationOperationType:CHANGE_PHONE_CONFIRM_OLD и для confirmationOperationType:CHANGE_PHONE_CONFIRM_NEW
      B-->>-P: 
      Note over P,B: oldPhoneConfirmationId, newPhoneConfirmationId, confirmationStatus:CONFIRMED
      end
      P->>+B: Запрос на установку или изменение номера телефона
      Note over P,B: productId, clientId, oldPhoneConfirmationId, newPhoneConfirmationId
      B-->>-P: Ответ на запрос
      Note left of B: personPhone

Запрос описан в документации Clients API. Сценарий «Аутентификация с помощью OTP» см. в статье «Общие принципы и правила» → «Подтверждение операций».

Блокировка клиента

Клиент может быть заблокирован QIWI в случае обнаружения компанией мошеннической активности. Блокировка означает, что совершение клиентом любых операций становится невозможным.

Партнёр узнаёт о блокировке, получив уведомление об изменении статуса блокировки от платформы (clientBlocked:true), подробнее см. в статье «Уведомления». Сообщение о блокировке партнёр самостоятельно отправляет клиенту в push-уведомлении или любым другим доступным способом.

Блокировка является обратимым действием — клиенту необходимо обратиться в QIWI и оставить запрос на разблокировку. В случае разблокировки партнёр снова получит уведомление об изменении статуса (clientBlocked:false).

Обратите внимание

Признак активности клиента не эквивалентен признаку блокировки. Активация клиента партнёром не влияет на значение clientBlocked — только QIWI может разблокировать clientId.

Просмотр баланса

Для того чтобы узнать баланс клиента, необходимо выполнить запрос на получение информации о счёте. Значение параметра ownFunds в ответе отражает сумму доступных средств.

Пример использования запроса изображён на диаграмме ниже.

sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
      С->>P: Переход на страницу интерфейса
      P->>+B: Запрос на получение информации о счёте
      Note right of P: productId, clientId, accountId
      B-->>-P: Ответ на запрос получения информации о счёте
      Note left of B: productId, clientId, accountId, currency, ownFunds
      P->>С: Отображение баланса
      Note left of P: ownFunds

Запрос описан в документации Clients API.

Документация
Разработчикам
Обратная связь
  • © 2023, КИВИ Банк (АО), лицензия ЦБ РФ № 2241
  • Россия, 117648, г. Москва, мкр. Чертаново Северное, д.1А, корп.1