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

Правила проведения операций домена CARDS

Общие сведения

Понятие операции домена CARDS см. в статье «Термины и бизнес-сущности». В этой статье описан механизм управления проведением таких операций.

Партнёр может запретить или разрешить проведение операций, попадающих под определённые условия.

Пример

Партнёр — компания, возмещающая своим сотрудникам расходы на обед. Партнёр выпускает для сотрудников карты, пополняет их один раз в день на определённую сумму и разрешает тратить эти средства только в тех конкретных точках питания, с которыми у него есть договорные отношения.

Набор условий, по которым определяется возможность проведения операции домена CARDS, называется правилом. Правила, которые запрещают проведение операции, называются DENY-правила. Правила, которые разрешают — ALLOW-правила.

Сценарий применения правил

Успешное применение правил

Сценарий успешного применения правил для операций домена CARDS в упрощённом виде описан и изображён ниже.

Во время проведения онлайн-операции после шага 2 (запрос на авторизацию операции) и перед выполнением шага 3 (движение денежных средств в рамках запроса на авторизацию) BaaS выполняет ряд внутренних проверок.

Проверка Результат проверки
1 Проверка карты Карта выпущена в рамках сотрудничества с партнёром BaaS
2 Достаточность средств на счёте клиента Средств для совершения операции достаточно
3 Активность режима проверки прав доступа Режим проверки прав доступа активен

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

Проверка Результат проверки
4 Проверка правил, созданных QIWI Операция соответствует внутренней политике QIWI
5 Проверка правил, созданных партнёром См. описание ниже

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

Сначала BaaS проверяет DENY-правила.

Проверка Результат проверки Поведение BaaS
5.1 Соответствие DENY-правилу DENY-правило найдено и данные операции удовлетворяют условиям правила Операция отклоняется с кодом ошибки DENIED_BY_PARTNER_ACL. Партнёру отправляется уведомление. Дальнейшие проверки не выполняются
Проверка Результат проверки Поведение BaaS
5.1 Соответствие DENY-правилу DENY-правило не найдено или данные операции не удовлетворяют условиям ни одного DENY-правила Проверка на соответствие ALLOW-правилу

Затем BaaS проверяет ALLOW-правила.

Проверка Результат проверки Поведение BaaS
5.2 Соответствие ALLOW-правилу ALLOW-правило найдено и данные операции удовлетворяют условиям правила Операция проводится — совершается движение денежных средств в рамках запроса на авторизацию. Партнёру отправляется уведомление. Дальнейшие проверки не выполняются
Проверка Результат проверки Поведение BaaS
5.2 Соответствие ALLOW-правилу ALLOW-правило не найдено или данные операции не удовлетворяют условиям ни одного ALLOW-правила Операция отклоняется с кодом ошибки DENIED_BY_PARTNER_ACL. Партнёру отправляется уведомление. Дальнейшие проверки не выполняются

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

  • Если не найдено ни одного правила (DENY или ALLOW) или правила найдены, но операция не удовлетворяет заданным в них условиям, операция отклоняется с кодом ошибки DENIED_BY_PARTNER_ACL.
  • Для применения правила операция должна удовлетворять всем его условиям.
%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        30 }}}%%
sequenceDiagram
    participant С as Клиент
    participant I as Интернет-магазин
    participant PS as Платёжная система
    participant B as BaaS
    participant P as Партнёр
    С->>I: Покупка товара
    Note right of С: «Оплатить»
    I->>PS: Запрос на авторизацию покупки
    Note right of I: Через систему банка-эквайера
    PS->>+B: Запрос на авторизацию покупки
    B->>B: Проверка карты, достаточности средств, режима проверки прав доступа
    Note over B: Карта ОК, средств достаточно, режим включен
    B->>B: Проверка правил, созданных QIWI
    Note over B: Операция соответствует внутренней политике QIWI
    rect rgb(245, 245, 245)
    Note over С, P: Проверка правил, созданных партнёром
    B->>B: Поиск DENY-правила
    alt Для операции найдено подходящее DENY-правило
    B->>PS: Запрос отклонён
    PS->>I: Запрос отклонён
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Операция отклонена, средства остались на карте
    rect rgb(255, 238, 223)
    B->>P: Сценарий «Получение уведомления»
    Note over B, P: txnType:PURCHASE_POS, actionType:HOLD, actionStatus:FAILED, actionStatusDetails.failureCode:DENIED_BY_PARTNER_ACL
    end
    else Для операции не найдено подходящее DENY-правило
    B->>B: Поиск ALLOW-правила
    rect rgb(230, 230, 230)
    alt Для операции найдено подходящее ALLOW-правило
    B->>B: HOLD
    B->>PS: HTTP 200 OK
    PS->>I: HTTP 200 OK
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Операция успешна, средства зарезервированы на карте
    else Для операции не найдено подходящее ALLOW-правило
    B->>-PS: Запрос отклонён
    PS->>I: Запрос отклонён
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Операция отклонена, средства остались на карте
    rect rgb(255, 238, 223)
    B->>P: Сценарий «Получение уведомления»
    Note over B, P: txnType:PURCHASE_POS, actionType:HOLD, actionStatus:FAILED, actionStatusDetails.failureCode:DENIED_BY_PARTNER_ACL
    end
    end
    end
    end
    end

Сценарий «Получение уведомления» см. в статье «Уведомления».

Правила не удалось применить

Если результат проверки №1, №2 или №4 отличается от указанного (см. сценарий успешного применения правил), операция отклоняется с соответствующим кодом ошибки. Для проверки №4 это DENIED_BY_BANK_ACL.

Если результат проверки №3 отличается от указанного (режим проверки прав доступа неактивен), правила не будут применены, но обработка операции продолжится.

Структура правила

Структура правила описана в документации Cards-lifecycle API в запросе на создание правила. В этом разделе указаны ключевые особенности.

Запрет или разрешение на проведение операции определяются значением атрибута ruleEffect, который отвечает за эффект применения правила:

  • ALLOW — разрешить проведение операции;
  • DENY — запретить проведение операции.

Условия, по которым определяется возможность проведения операции, задаются атрибутами с префиксом filter. Список таких атрибутов см. в теле запроса на создание правила.

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

  • Незаполненное условие не проверяется. Например, для разрешения всех карточных авторизаций можно создать правило с незаполненными фильтрами и эффектом ALLOW.
  • При проверке операции на соответствие условиям сравнение строк производится без учета регистра.

Правило может иметь срок действия.

Срок действия

У сущностей, перечисленных в разделе «Управление проведением операций» есть два атрибута — actualFrom и actualTill. Исключение — карта: у данной сущности нет этих атрибутов.

При создании у сущности появляется actualFrom (начало срока её действия), при отключении или удаленииactualTill (окончание срока её действия). Партнёр видит значения этих атрибутов в ответе на соответствующий запрос к Cards-lifecycle API: на создание или отключение/удаление сущности.

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

Время в actualFrom и actualTill не совпадает со временем отправки запроса на создание или отключение/удаление сущности. Для понимания, когда правило начнёт и закончит действовать, проверяйте значения этих атрибутов.

Значения actualFrom и actualTill партнёр также может увидеть в ответе на запрос получения информации о сущности: см. описание в разделе «Получение информации».

Сущность Атрибут Описание
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
actualFrom Присваивается при успешном выполнении запроса на создание сущности
• Группа
• Правило
actualTill Присваивается при успешном выполнении запроса на отключение сущности
Связь правила с группой actualTill Присваивается при успешном выполнении запроса на удаление сущности
Связь карты с группой actualTill Не присваивается связи карты с группой, так связь удаляется без отсроченного эффекта — мгновенно

Управление проведением операций

Сущности

В рамках управления проведением операций домена CARDS BaaS оперирует следующими типами сущностей:

Сущность Описание
Группа Сущность, объединяющая правила и карты с целью нормализации данных
Правило Набор условий, по которым определяется возможность проведения операции
Карта Описание см. в статье «Термины и бизнес-сущности»
Связь правила с группой Принцип объединения правил в группы существует с целью нормализации данных
Связь карты с группой Такая связь позволяет BaaS понять, какие правила и к какой карте будут применяться

Модель данных

erDiagram
    GROUP ||--o{ RULE : bind
    RULE ||--o{ GROUP : bind
    CARD o{--|| GROUP : bind
    GROUP o{--|| CARD : bind
Связь Значение
|| Один
o{ Ноль или более (нет верхнего лимита)

Создание

Чтобы управлять проведением операций, партнёру необходимо:

  1. Создать одну или несколько групп правил.
  2. Создать одно или несколько правил.

  3. Добавить каждое правило в нужную группу — создать связь.

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

    • Если правило не добавлено в группу, оно игнорируется при принятии решения о проведении операции.
    • Принцип объединения правил в группы выбирается партнёром, но сама концепция такого объединения существует с целью нормализации данных: убедитесь, что отношение группа:правило не один к одному, а один ко многим.
    • Один запрос позволяет добавить одно правило в одну группу: чтобы добавить в группу нужное количество правил, сформируйте несколько запросов.
  4. Связать карту каждого клиента с нужной группой.

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

    • Карты должны быть предварительно выпущены.
    • Один запрос позволяет связать одну карту с одной группой: чтобы связать с группой нужное количество карт, сформируйте несколько запросов.
%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":14,
        "actorMargin":
        305 }}}%%
sequenceDiagram
    participant P as Партнёр
    participant B as BaaS
    rect rgb(230, 230, 230)
    P->>+B: Сценарий выпуска банковской карты
    B-->>-P: 
    Note left of B: cardTokenId
    end
    P->>+B: Запрос на создание группы правил
    Note right of P: productId, groupId
    B-->>-P: Ответ на запрос создания группы правил
    Note left of B: groupId, actualFrom
    P->>+B: Запрос на создание правила
    Note right of P: productId, ruleId, filters
    B-->>-P: Ответ на запрос создания правила
    Note left of B: ruleId, filters, actualFrom
    P-->>+B: Запрос на создание связи правила с группой
    Note right of P: productId, ruleId, groupId
    B-->>-P: Ответ на запрос создания связи правила с группой
    Note left of B: ruleId, groupId, actualFrom
    P->>+B: Запрос на создание связи карты с группой
    Note right of P: productId, cardTokenId, groupId
    B-->>-P: Ответ на запрос создания связи карты с группой
    Note left of B: cardTokenId, groupId, actualFrom

Запросы описаны в документации Cards-lifecycle API. Сценарий выпуска банковской карты см. в разделе «Управление банковской картой» → «Сценарии».

В ответе об успешном выполнении запроса на создание сущности содержится поле, отвечающее за начало срока её действия. Остальные поля такого ответа условно назовём основными. Перечень и описание полей см. в документации Cards-lifecycle API — в обзоре ответа на запрос создания:

Ответ на запрос создания зависит от состояния сущности. Различия описаны в таблице ниже.

Сущность Условие Ответ за запрос создания сущности
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
Сущность с указанным идентификатором уже создана, нет успешно выполненного запроса на её отключение или удаление HTTP 200

Основные поля и actualFrom ранее созданной сущности
• Группа
• Правило
Сущность с указанным идентификатором уже создана, есть успешно выполненный запрос на её отключение Ошибка card.auth.acl.***.disabled, где ***group, rule соответственно
Связь правила с группой Сущность с указанным идентификатором уже создана, есть успешно выполненный запрос на её удаление, actualTill ещё не наступил Ошибка card.auth.acl.rule.group.binding.is.being.deleted
Связь правила с группой Сущность с указанным идентификатором создана ранее, есть успешно выполненный запрос на её удаление, actualTill уже наступил HTTP 200

Основные поля и actualFrom новой сущности — не ранее созданной
Связь карты с группой Сущность с указанным идентификатором создана ранее, есть успешно выполненный запрос на её удаление HTTP 200

Основные поля и actualFrom новой сущности — не ранее созданной

Изменение

Внести изменения можно только путём создания новой сущности (группы, правила, связи) и отключения или удаления старой, если её больше не планируется использовать.

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

Новая группа или правило должны быть созданы с другим идентификатором (ruleId/groupId).

Отключение или удаление

Отключение сущности означает, что сущность становится неактивной, а не удаляется навсегда — её идентификатор нельзя переиспользовать при создании новой сущности того же типа. Идентификатор удалённой сущности переиспользовать можно.

Отключить можно группу и правило. Удалить можно связь правила или карты с группой.

Сущность Причина Способ Важно знать
Группа Группа создана по ошибке или больше не используется Отключение Отключенную группу нельзя включить. Правила из отключенной группы остаются активными, но игнорируются при принятии решения о проведении операции, если не связаны с другой (включенной) группой
Правило Правило создано по ошибке или больше не используется Отключение Отключенное правило нельзя включить
Связь правила с группой Связь правила с группой создана по ошибке или правило больше не относится к связанной с ним группе Удаление с отсроченным эффектом Связь правила с группой — сущность, удаляемая с отсроченным эффектом: после успешной обработки запроса на удаление, у неё появляется actualTill c определённым временем в будущем
Связь карты с группой Связь карты с группой создана по ошибке или к карте больше не должны применяться правила связанной с ней группы Удаление Связь карты с группой — сущность, удаляемая мгновенно: actualTill ей не присваивается

Запрос на отключение или удаление в разрезе каждой отдельной сущности описан в документации Cards-lifecycle API. Один запрос позволяет отключить или удалить только одну сущность: чтобы отключить или удалить нужное количество сущностей, сформируйте несколько запросов.

В ответе об успешном выполнении запроса содержится поле, отвечающее за окончание срока действия сущности. Остальные поля такого ответа условно назовём основными. Перечень и описание полей см. в документации Cards-lifecycle API — в обзоре ответа на запрос на отключение или удаление:

Ответ на запрос зависит от состояния сущности. Различия описаны в таблице ниже.

Сущность Условие Ответ за запрос отключения или удаления сущности
• Группа
• Правило
• Связь правила с группой
Сущность с указанным идентификатором существует и для неё нет ни одного успешно выполненного запроса на отключение или удаление HTTP 202

Основные поля и:
actualFrom;
actualTill
Связь карты с группой Сущность с указанным идентификатором существует и для неё нет ни одного успешно выполненного запроса на отключение или удаление HTTP 204

Тело ответа отсутствует
• Группа
• Правило
• Связь правила с группой
Сущность с указанным идентификатором существует и для неё ранее выполнен запрос на отключение или удаление, но actualTill ещё не наступил HTTP 202

Основные поля и:
actualFrom;
actualTill
ранее отключенной/удалённой сущности
• Группа
• Правило
Сущность с указанным идентификатором существует, для неё ранее выполнен запрос на отключение и actualTill уже наступил HTTP 200

Основные поля и:
actualFrom;
actualTill
ранее отключенной сущности
Связь правила с группой Сущность с указанным идентификатором существует, для неё ранее выполнен запрос на удаление и actualTill уже наступил HTTP 404

Ошибка card.auth.acl.rule.group.binding.not.found
Связь карты с группой Сущность с указанным идентификатором существует и для неё ранее выполнен запрос на удаление HTTP 404

Ошибка card.auth.acl.card.group.binding.not.found
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
Сущности не существует HTTP 404

Ошибка card.auth.acl.***.not.found, где ***group, rule, rule.group.binding, card.group.binding соответственно

Получение информации

Запрос на получение информации в разрезе каждой отдельной сущности описан в документации Cards-lifecycle API.

В ответе об успешном выполнении запроса на получение информации о сущности содержатся поля, отвечающие за срок действия сущности: actualFrom и actualTill. Остальные поля такого ответа условно назовём основными. Перечень и описание полей см. в документации Cards-lifecycle API — в обзоре ответа на запрос получения информации о:

Ответ на запрос информации зависит от состояния сущности. Различия описаны в таблице ниже.

Сущность Условие Ответ за запрос информации о сущности
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
Сущность активна: её не отключали/удаляли HTTP 200

Основные поля и actualFrom
• Группа
• Правило
Сущность отключена HTTP 200

Основные поля и:
actualFrom;
actualTill
Связь правила с группой BaaS получил запрос на удаление сущности и время в actualTill ещё не наступило — сущность не удалена HTTP 200

Основные поля и:
actualFrom;
actualTill
Связь правила с группой BaaS получил запрос на удаление сущности и время в actualTill уже наступило — сущность удалена HTTP 404

Ошибка card.auth.acl.rule.group.not.found
Связь карты с группой Сущность удалена HTTP 404

Ошибка card.auth.acl.card.group.not.found
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
Сущности не существует HTTP 404

Ошибка card.auth.acl.***.not.found, где ***group, rule, rule.group.binding, card.group.binding соответственно

HTTP-код ответа

HTTP-код ответа на запросы в рамках управления проведением операций зависит от вида запроса и результата его обработки.

Сущность Вид запроса Условие HTTP-код ответа
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
• Запрос на создание
• Запрос на получение информации
Запрос выполнен успешно 200
• Группа
• Правило
• Связь правила с группой
• Запрос на отключение
• Запрос на удаление
Запрос выполнен успешно 202
Связь карты с группой Запрос на удаление Запрос выполнен успешно 204
• Группа
• Правило
• Связь правила с группой
• Связь карты с группой
Любой запрос в рамках управления проведением операций Запрос не удалось выполнить 4xx/5xx