3D-Secure¶

3D-Secure (Three-Domain Secure) — протокол аутентификации покупателей, обеспечивающий безопасную оплату товаров и услуг в интернете. Технология 3D-Secure (далее по тексту — 3DS) подразумевает дополнительный шаг аутентификации при совершении покупки в интернет-магазине:

на первом шаге на странице оплаты используются реквизиты банковской карты: номер, срок действия, имя держателя, код проверки подлинности (например, CVC2);
на втором — дополнительный защитный код, который вводится на веб-форме банка-эмитента.

Данная статья предназначена для компаний, осуществляющих приём платежей с помощью собственной платёжной формы и взаимодействия с платформой XPAY по API.

Обязательность 3DS-аутентификации

Согласно правилам международных платёжных систем (далее — МПС) по умолчанию все платежи, проводимые XPAY, требуют использования 3DS. Для уточнения возможности отключения 3DS (использования не-3DS терминала) обратитесь в службу поддержки XPAY или банка-эквайера. Однако в некоторых случаях при проведении платежей через не-3DS терминал банк-эмитент всё же может потребовать аутентификацию: ваше приложение должно поддерживать использование данной технологии.

Сценарий¶

Этап проведения платежа, на котором используется 3DS, отражён в данном сценарии.

Ниже представлена схема, описывающая детали прохождения покупателем 3DS.

Информация

В случае использования одной из тестовых карт платформа эмулирует процесс прохождения 3DS-аутентификации.

Описание

После выполнения запроса на оплату выставленного счета необходимо запустить таймер и начать опрашивать XPAY на предмет появления новых событий.

Интервал и время опроса

Рекомендуется установить интервал опроса в 1 секунду и ограничение на время опроса в 60-120 секунд, либо 60-120 запросов.
Платформа проверит необходимость использования 3DS и вернёт нужные для этого данные в случае положительного результата: в ответе на запрос событий по инвойсу появится изменение с changeType = PaymentInteractionRequested и userInteraction.interactionType = Redirect.

Пример ответа платформы:

   {
        "createdAt": "2018-03-20T10:15:26.905268Z",
        "id": 3,
        "changes": [
            {
                "changeType": "PaymentInteractionRequested",
                "paymentID": "1",
                "userInteraction": {
                    "interactionType": "Redirect",
                    "request": {
                        "requestType": "BrowserPostRequest",
                        "uriTemplate": "https://3ds-mock.xpay.by/mpi/acs",
                        "form": [
                            {
                                "key": "TermUrl",
                                "template": "https://wrapper.xpay.by"
                            },
                            {
                                "key": "PaReq",
                                "template": "paReq"
                            },
                            {
                                "key": "MD",
                                "template": "COM_MPI-ymJorPXs5A1"
                            }
                        ],
                    }
                }
            }
        ],
    }

Полученную в request структуру следует использовать для переадресации браузера покупателя на страницу банка-эмитента по указанному в ответе uriTemplate.
Переадресация на страницу 3DS-аутентификации
- Тип переадресации request.requestType (GET или POST) зависит от решения банка-эквайера. Следует поддерживать оба варианта.
- Значение параметра uriTemplate не подлежит изменению.
- Набор параметров в form для requestType = BrowserPostRequest может меняться: его возвращает соответствующая МПС. Не следует базировать на нём логику работы приложения: например, проверять наличие определённого параметра или присутствие его значения. Количество параметров и их значения при выполнении переадресации должны оставаться неизменны.
Пример запроса средствами cURL на основании ответа платформы, представленного выше:

    curl "https://3ds-mock.xpay.by/mpi/acs" --data "TermUrl=https://wrapper.xpay.by?PaReq=paReq&MD=COM_MPICOM_MPI-ymJorPXs5A1"

Покупатель введёт второй фактор аутентификации на странице банка-эмитента.
Банк-эмитент сформирует ответ об успешности прохождения аутентификации и оповестит об этом платформу.

Завершение 3DS-аутентификации

Для того чтобы узнать о завершении 3DS-аутентификации покупателя, при выполнении запроса на оплату выставленного счета необходимо передать redirectUrl: см. payer → sessionInfo. Браузер покупателя будет перенаправлен на указанный URL в случае как успешного, так и неуспешного завершения аутентификации.

Событие PaymentStatusChanged говорит об изменении состояния оплаты и, соответственно, о статусе прохождения 3DS (см. параметр status):

processed — оплату заказа можно считать успешно выполненной: денежные средства в размере суммы выставленного счета уже как минимум заблокированы на источнике денежных средств плательщика;
failed — оплата неуспешна.