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

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

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

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

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

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

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

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

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

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

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

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

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

%%{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. Список таких атрибутов см. в теле запроса на создание правила.

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

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

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

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

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

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

Сущности¶

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

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

erDiagram
    GROUP ||--o{ RULE : bind
    RULE ||--o{ GROUP : bind
    CARD o{--|| GROUP : bind
    GROUP o{--|| CARD : bind

Создание¶

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

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 — в обзоре ответа на запрос создания:

• группы;
• правила;
• связи правила с группой;
• связи карты с группой.

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

Изменение¶

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

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

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

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

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

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

• группы;
• правила;
• связи правила с группой;
• связи карты с группой.

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

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

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

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

• группе;
• правиле;
• связи правила с группой;
• связи карты с группой.

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

HTTP-код ответа¶

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