Общие принципы и правила¶

Статья описывает общие принципы и правила взаимодействия c платформой.

Вычисление цифровой подписи¶

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

Для вычисления подписи необходимы строковые представления “секрета” (secret) и подписываемых данных, т.е. тела запроса (data). Значение secret предоставляется партнёру по запросу и не зависит от сценария взаимодействия с платформой — оно всегда одинаковое.

Выполните следующие действия:

• преобразуйте строки secret и data в байты UTF-8 secret_bytes и data_bytes, соответственно;

• вызовите библиотечную реализацию алгоритма HmacSHA256 для вычисления байтового представления подписи;

  signature_bytes = HmacSHA256(secret_bytes, data_bytes)

• закодируйте байты подписи в hex-представление и получите строку подписи.

  signature = hex(signature_bytes)

    import hashlib
    import hmac

    data = '{"type":"CLEARING","eventDateTime":"2021-09-20T11:32:35.926795+03:00","txnId":"77fc0beb-1f42-4c46-b4d0-407e3caa13a4","txnType":"FAST_FUNDS","actionId":"ec6861e2-fe67-4d46-a13d-210f5e643e86","actionType":"CAPTURE_FAST_FUNDS","actionStatus":"SUCCESS","actionStatusDetails":{},"actionData":{"cardTokenId":"100080516478","clientId":"547606fd-d5f7-4a60-a004-92fabe246210","clearingDate":"2021-09-20","transactionAmount":{"currency":"RUB","value":"7.89"},"originTransactionAmount":{"currency":"RUB","value":"7.89"},"merchantId":"977492982538","merchantName":"TEST_MERCHANT_NAME","merchantType":"5331","terminalId":"35124585","acquirerId":"357754","wasNotAuthorizedBefore":true}}'
    key = 'cee66da5b04cb4f2026b5c8872dbcf8a'

    key_bytes = bytes(key, 'UTF-8')
    data_bytes = bytes(data, 'UTF-8')
    h = hmac.new(key_bytes, data_bytes, hashlib.sha256 )
    print( h.hexdigest() )

603ab1c988d87c342d7a2cb2b961cb2fd275a3bd2b97f38c0c36864f29a856fb

Решение об успешности платежа¶

BaaS поддерживает несколько вариантов проведения платежа:

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

Синхронный вариант проведения платежа¶

Пример — выплата на кошелёк, перевод между кошельками и др.

Для принятия решения об успешности платежа партнёр может основываться на значении поля status, полученном в ответе на соответствующий платёжный запрос. Запросы и ответы описаны в документации Payments API.

Последовательность действий для принятия решения об успешности платежа на примере совершения перевода между кошельками приведена ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "actorMargin":
        85 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
    С->>P: Перевод на кошелёк в интерфейсе
    Note right of С: «Перевести»
    P->>+B: Сценарий «Перевод между кошельками» (Payments API)
    Note right of P: transactionId
    B->>-P: 
    Note left of B: status:SUCCESS
    P->>С: Коммуникация с клиентом

Сценарий «Перевод между кошельками» см. здесь.

Асинхронный вариант проведения платежа¶

Пример — пополнение с банковской карты (см. пример запроса), перевод на банковскую карту (см. пример запроса) и др.

Для принятия решения об успешности платежа партнёру нужно дождаться уведомления от BaaS и следовать описанной ниже логике.

Если статус в уведомлении имеет финальное успешное значение status:SUCCESS, партнёру необходимо однократно выполнить запрос статуса к платформе самостоятельно. Это позволит избежать ложных уведомлений, т.е. устранить риски компрометации данных в случае утечки “секрета”, который используется при вычислении цифровой подписи уведомления. В конечном итоге партнёру следует основываться на значении поля status в ответе на запрос статуса соответствующего платежа. Запросы и ответы описаны в документации Payments API.

Последовательность действий для принятия решения об успешности платежа на примере совершения перевода на банковскую карту приведена ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":14,
        "actorMargin":
        85 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
    С->>P: Перевод на карту в интерфейсе
    Note right of С: «Перевести»
    P->>+B: Сценарий «Перевод на банковскую карту» (Payments API)
    Note right of P: transactionId
    B->>-P: 
    Note left of B: status:PROCESSING
    rect rgb(255, 238, 223)
    B->>+P: Сценарий «Уведомление об операциях домена PAYMENTS» (History&Notifications API)
    P-->>-B: 
    Note left of B: transactionId, status:SUCCESS
    end
    rect rgb(230, 230, 230)
    P->>+B: Запрос на получение статуса перевода (Payments API)
    Note right of P: transactionId
    B-->>-P: Ответ на запрос получения статуса
    Note left of B: transactionId, status:SUCCESS
    end
    P->>С: Коммуникация с клиентом

Упомянутые на диаграмме сценарии см. в статьях:

• «Перевод на банковскую карту»;
• «Уведомления».

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

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

Обработка таких операций условно делится на 2 этапа:

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

Процесс успешной обработки финансовой операции домена CARDS в упрощённом виде описан ниже.

Онлайн-операция¶

Здесь описан успешный сценарий обработки финансовой операции домена CARDS.

1. Клиент совершает операцию — пополняет карту QIWI с карты другого банка, покупает товар или услугу в интернете, снимает наличные в банкомате и др.
2. Платёжная система, которая обслуживает карту, отправляет QIWI (BaaS) запрос на авторизацию операции.
3. BaaS совершает действие, которое приводит к движению денежных средств, в рамках запроса на авторизацию — зачисляет средства на баланс клиента, резервирует средства на балансе клиента, списывает их и др.
4. BaaS создаёт запись об успешном совершении действия в рамках онлайн-операции определённого типа.
5. BaaS отправляет платёжной системе ответ об успешной авторизации операции.
6. BaaS отправляет партнёру уведомление об успешном совершении действия в рамках онлайн-операции определённого типа, если такая возможность настроена.

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

Пример записи в BaaS о получении запроса на отмену покупки в интернете приведён ниже. В примере запрос получен по операции покупки c идентификатором txn1, в рамках которой BaaS ранее зарезервировал денежные средства на карте клиента.

Пример успешной покупки и отмены покупки в интернет-магазине с помощью карты QIWI изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":13,
        "actorMargin":
        75 }}}%%
sequenceDiagram
    participant С as Клиент
    participant I as Интернет-магазин
    participant PS as Платёжная система
    participant B as BaaS
    С->>I: Покупка товара
    Note right of С: «Оплатить»
    I->>PS: Запрос на авторизацию покупки txn1
    Note right of I: Через систему банка-эквайера
    PS->>B: Запрос на авторизацию покупки txn1
    B->>B: HOLD
    B->>PS: 200 OK
    PS->>I: 200 OK
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Заказ подтверждён, средства зарезервированы на карте
    С->>I: Отмена заказа
    Note right of С: «Отменить»
    I->>PS: Запрос на авторизацию отмены покупки txn1
    Note right of I: Через систему банка-эквайера
    PS->>B: Запрос на авторизацию отмены покупки txn1
    B->>B: REVERSAL
    B->>PS: 200 OK
    PS->>I: 200 OK
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Заказ отменён, средства доступны для использования

Список возможных действий и их описание см. в документации History&Notifications API.

Офлайн-операция¶

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

Для каждой записи из клирингового файла BaaS выполняет определённое действие (например, списывает денежные средства с карты клиента) и уведомляет об этом партнёра, если такая возможность настроена.

Пример записи в BaaS о получении авторизационного клиринга приведён ниже. В примере клиринг получен по операции совершения покупки в интернете c идентификатором txn1, а BaaS ранее зарезервировал средства для этой покупки в рамках получения запроса на авторизацию.

Пример записи в BaaS о получении безавторизационного клиринга по операции совершения покупки в интернете будет содержать лишь одну строку с actionType:CAPTURE_HOLD.

Пример успешной покупки в интернет-магазине с помощью карты QIWI изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":13,
        "actorMargin":
        75 }}}%%
sequenceDiagram
    participant С as Клиент
    participant I as Интернет-магазин
    participant PS as Платёжная система
    participant B as BaaS
    С->>I: Покупка товара
    Note right of С: «Оплатить»
    I->>PS: Запрос на авторизацию покупки txn1
    Note right of I: Через систему банка-эквайера
    PS->>B: Запрос на авторизацию покупки txn1
    B->>B: HOLD
    B->>PS: 200 OK
    PS->>I: 200 OK
    Note left of PS: Через систему банка-эквайера
    I->>С: Коммуникация с клиентом
    Note right of С: Заказ подтверждён
    PS->>B: Клиринговый файл с записью о покупке txn1
    B->>B: CAPTURE_HOLD

Список возможных действий и их описание см. в документации History&Notifications API.

В рамках одной покупки может поступить несколько отдельных записей в одном или разных файлах клиринга. Записи могут содержать разные суммы. Такой случай в терминологии BaaS называется мультиклирингом.

Статусная модель¶

Жизненный цикл действия, которое приводит к движению средств, изображён на диаграмме ниже.

flowchart TD
    Start --> SUCCESS
    Start --> FAILED

• SUCCESS — когда действие выполнено успешно;
• FAILED — когда действие не выполнено (в этом случае BaaS зафиксирует одну из перечисленных в документации History&Notifications API ошибок авторизации).