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

Статья описывает общие принципы и правила взаимодействия c сервисами продукта Интернет-эквайринг.

Проведение платежа и взаиморасчёты¶

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

Проведение платежа

1. Клиент выбирает товар или услугу на торговой площадке партнёра, попадает на платёжную форму, заполняет необходимые поля и нажимает «Оплатить».
2. QIWI получает запрос на совершение операции.
3. QIWI отправляет запрос на совершение операции в платёжную систему, которая обслуживает карту.
4. Платёжная система отправляет запрос на совершение операции банку-эмитенту, который выпустил карту клиента.
5. Банк-эмитент изменяет состояние счёта клиента и отправляет ответ об успешном совершении операции платёжной системе.
6. Платёжная система отправляет ответ об успешном совершении операции QIWI.
7. QIWI информирует об успешном совершении операции партнёра.

Взаиморасчёты

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

%%{init: {
    "sequence" : {
        "wrap":true,
        "diagramMarginY": 0,
        "mirrorActors":true,
        "width":120,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorFontSize":14,
        "actorMargin":
        15 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P1 as Торговая площадка партнёра
    participant P2 as Кредитная организация партнёра
    participant Q as QIWI
    participant PS as Платежная система
    participant B as Банк-эмитент
    rect rgb(230, 230, 230)
    Note over С, B: Проведение платежа
    loop Повторяется с определённой периодичностью
    С->>P1: Оплата товара или услуги
    Note over P1: Платёжная форма
    P1->>+Q: Запрос на совершение операции
    Q->>+PS: Запрос на совершение операции
    PS->>+B: Запрос на совершение операции
    B->>-PS: ОК
    PS->>-Q: ОК
    Q->>-P1: ОК
    P1->>С: Коммуникация с клиентом
    end
    end
    rect rgb(255, 238, 223)
    Note over P2, B: Взаиморасчеты
    B->>PS: ₽₽₽
    PS->>Q: ₽₽₽
    Q->>P2: ₽₽₽
    end

Электронная подпись платежей¶

Для совершения платежей партнёру может потребоваться подписать запрос и передать значение подписи в заголовке X-Digital-Sign.

Чтобы понять, в каких запросах следует передавать X-Digital-Sign: <значение подписи>, см. описание HTTP Headers в документации Payments API.

Для подписи запроса партнёр должен:

1. Создать пару ключей с помощью алгоритма RSA-2048.

   • Одна из доступных утилит — OpenSSL.
   • Размер закрытого ключа — 2048 бит, формат — PEM.

2. Передать QIWI закодированный в Base64 публичный ключ, соответствующий секретному ключу.

3. Подписывать каждый запрос к Payments API, требующий передачи заголовка X-Digital-Sign.

Шаги 1 и 2 выполняются разово, шаг 3 — каждый раз при создании запроса.

Создание пары ключей¶

Для создания пары ключей с помощью OpenSSL, партнёру необходимо:

1. Сгенерировать закрытый ключ.

   Команда

   openssl genrsa -out private-key.pem 2048
   

   В папке выполнения команды будет создан файл с секретным ключом: private-key.pem.

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

   Секретный ключ недопустимо передавать третьим лицам, сохраняйте его конфиденциальность.

2. Получить открытый ключ, соответствующий закрытому.

   Команда

   openssl rsa -in private-key.pem -pubout -out public-key.pem
   

3. Закодировать полученный ключ public-key.pem в Base64.

   Команда

   base64 -i public-key.pem
   

Передача публичного ключа QIWI¶

Партнёр должен передать QIWI результат, полученный на шаге 3 этапа «Создание пары ключей». Способ передачи public-key.pem необходимо уточнить у курирующего менеджера.

Подпись платёжного запроса¶

Для подписи платёжных запросов партнёру следует выполнить нижеописанные действия. Примеры в описании приведены на языке Bash.

1. Сформировать тело запроса в виде строки с параметрами запроса.

   Шаблон строки

   REQUEST_BODY='{"amount":{"value":100, "currency":"RUB"},...'
   

2. Сформировать цифровую подпись с помощью алгоритма SHA256withRSA и секретного ключа private-key.pem, полученного на этапе «Создание пары ключей».

   SIGNATURE_RAW=$(echo -n $REQUEST_BODY | openssl dgst -sha256 -sign private-key.pem)
   

3. Закодировать полученную цифровую подпись при помощи Base64 в строку.

   SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)
   

4. Передать закодированную цифровую подпись в заголовке X-Digital-Sign при отправке запроса к Payments API.

Решение об успешности операции¶

Для принятия решения об успешности операции (например, авторизации или подтверждения платежа) партнёру нужно:

• дождаться уведомления от QIWI;
• выполнить запрос статуса операции к QIWI.

Для понимания статуса операции рекомендуется основываться на значении поля status в ответе на запрос статуса соответствующей операции. Это позволит устранить риски, связанные с получением ложных уведомлений: риски компрометации данных в случае утечки «секрета», который используется при вычислении цифровой подписи уведомления.

Запрос статуса операции рекомендуется выполнять после получения уведомления.

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

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":14,
        "actorMargin":
        110 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
    С->>P: Оплата с формы QIWI
    Note right of С: «Оплатить»
    P->>+B: Сценарий «Оплата с формы QIWI с помощью API»
    Note right of P: billId, flags:[SALE]
    B->>-P: 
    Note left of B: Направление на `successUrl`
    rect rgb(255, 238, 223)
    B->>+P: Сценарий «Получение уведомления»
    P-->>-B: 
    Note left of B: billId, paymentId, status:SUCCESS
    end
    rect rgb(230, 230, 230)
    P->>+B: Запрос статуса счёта (Payments API)
    Note right of P: billId
    B-->>-P: Ответ на запрос статуса
    Note left of B: billId, status:PAID, paymentsData
    end
    P->>С: Коммуникация с клиентом

Запросы описаны в документации API приёма платежей.

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

• «Оплата с формы QIWI с помощью API»;
• «Уведомления».