Аутентификация по инициативе мерчанта

Общая информация

Аутентификация пользователя со стороны провайдера по инициативе мерчанта предназначена для обеспечения дополнительной безопасности проведения интернет-оплат с использованием платёжных карт. Такая аутентификация используется, как правило, в качестве замены аутентификации 3‑D Secure или для её дополнения. Это может быть уместно в тех случаях, когда аутентификация 3‑D Secure недостаточно надёжна, например из-за поддержки эмитентами устаревших методов подтверждения пользователем своей личности. При аутентификации по инициативе мерчанта подтверждение личности пользователя осуществляется путём ввода пользователем проверочного кода, полученного в информации о списании. Информацию о списании пользователь получает в SMS-сообщении или банковской выписке.

В платёжной платформе аутентификация по инициативе мерчанта поддерживается только для некоторых провайдеров, а для её подключения необходимо настроить проект мерчанта. Для этого следует обратиться в службу технической поддержки support@ecommpay.com.

Со стороны веб-сервиса для аутентификации по инициативе мерчанта необходимо:

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

Более подробные сведения о работе с аутентификацией по инициативе мерчанта представлены далее.

Схема работы

Аутентификация по инициативе мерчанта может выполняться при проведении одностадийных и двухстадийных оплат с применением платёжных карт. Информирование о необходимости такой аутентификации осуществляется через оповещения, на которые, как и обычно, необходимо направлять ответы об их приёме. Эти оповещения содержат информацию об изменении статуса платежа на awaiting merchant auth.

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

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

После того как в платёжную платформу поступает запрос с проверочным кодом, проведение платежа продолжается дальше.

Рис. 1. Выполнение аутентификации по инициативе мерчанта

В платёжной платформе выполняется обработка платежа.
От платёжной платформы к веб-сервису направляется оповещение о необходимости аутентификации.
Выполняется перенаправление пользователя на страницу с информацией об аутентификации.
Пользователь соглашается с выполнением аутентификации.
От веб-сервиса на заданный URL ecommpay передаётся запрос на инициирование аутентификации.
Запрос поступает в платёжную платформу.
В платёжной платформе выполняется обработка запроса.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
От платёжной платформы к сервису провайдера направляется запрос на инициирование аутентификации.
На стороне провайдера выполняется обработка запроса и отправка проверочного кода пользователю.
Пользователь вводит проверочный код.
От веб-сервиса на заданный URL ecommpay передаётся запрос на завершение аутентификации и продолжение проведения платежа.
Запрос поступает в платёжную платформу.
В платёжной платформе выполняется обработка запроса.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
От платёжной платформы к сервису провайдера направляется запрос на завершение аутентификации и продолжение проведения платежа.

Информация о формате запросов и оповещений приведена далее; общая информация о работе с API — в разделе Организация взаимодействия.

Формат оповещения о необходимости аутентификации

Информация о необходимости аутентификации передаётся в оповещении стандартного формата, описание которого представлено в разделе Оповещения.

В данном случае оповещение свидетельствует о том, что платёж и операция переведены в статус awaiting merchant auth до получения запроса на продолжение платежа.

Рис. 2. Пример данных из оповещения о необходимости аутентификации

{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"purchase",
    "status":"awaiting merchant auth", // Статус платежа
    "date":"2019-02-20T15:33:11+0000",
    "method":"card",
    "sum":{  
      "amount":400000,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "customer":{  
    "id":"customer_12"
  },
  "operation":{  
    "id":171200003265,
    "type":"sale",
    "status":"awaiting merchant auth", // Статус операции
    "date":"2019-02-20T15:33:11+0000",
    "created_date":"2019-02-20T15:33:02+0000",
    "request_id":"617c2626f873151a1cf5873ceb7cca0ade292ee-646d...ec",
    "sum_initial":{  
      "amount":400000,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400000,
      "currency":"USD"
    },
    "provider":{  
      "id":4,
      "payment_id":"3301571985",
      "auth_code":"",
      "endpoint_id":4
    },
    "code":"9999",
    "message":"Awaiting processing",
    "eci":"06"
  },
  "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Формат запроса на инициирование аутентификации

Для инициирования аутентификации по инициативе мерчанта необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/merchant_auth. В этом запросе должен использоваться объект general, содержащий основные идентификационные сведения и указатель типа запроса:

project_id — идентификатор проекта, полученный от ecommpay при интеграции;
payment_id — идентификатор платежа, уникальный в рамках проекта;
type — указатель типа запроса, необходимо передать значение start;
signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, указатель типа запроса (start) и подпись.

Рис. 3. Пример набора данных в запросе на инициирование аутентификации

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}

Формат запроса на продолжение проведения платежа

Для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/merchant_auth. В этом запросе должны использоваться следующие объекты и параметры:

general — объект, содержащий основные идентификационные сведения и указатель типа запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- type — указатель типа запроса, необходимо передать значение finish;
- signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью);
confirmation_code — проверочный код, полученный от пользователя.

Таким образом, корректный вопрос должен содержать идентификаторы проекта и платежа, указатель типа запроса (finish), подпись и проверочный код.

Рис. 4. Пример набора данных в запросе на продолжение проведение платежа

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "type": "start",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "confirmation_code": "835"
}