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

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

Статья описывает общие принципы и правила взаимодействия 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.

X-Digital-Sign является дополнительным фактором безопасности: его использование не отменяет необходимости передавать Bearer Token в заголовке запроса Authorization.

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

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

    • Одна из доступных утилит — OpenSSL.
    • Размер закрытого ключа — 2048 бит, формат — PEM.
  2. Передать QIWI закодированный в Base64 публичный ключ, соответствующий секретному ключу.

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

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

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

Пару RSA-ключей необходимо перевыпускать каждый год.

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

Для создания пары ключей с помощью 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 в ответе на запрос статуса соответствующей операции. Это позволит устранить риски, связанные с получением ложных уведомлений: риски компрометации данных в случае утечки «секрета», который используется при вычислении цифровой подписи уведомления.

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

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

Если уведомление не поступило в течение 10 минут с момента совершения операции, необходимо выполнить запрос статуса.

Последовательность действий для принятия решения об успешности операции на примере оплаты с формы 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 приёма платежей.

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