Аутентификация по инициативе платежной системы
Общая информация
Аутентификация по инициативе платежной системы применяется для обеспечения безопасности интернет-оплаты с использованием платежных карт некоторых платежных систем и обязательна для проведения такой оплаты.
Эта аутентификация заменяет аутентификацию 3‑D Secure, и в ней также используются одноразовые проверочные коды (One Time PIN, OTP), которые пользователь получает в сообщениях. Однако в отличие от 3‑D Secure такие коды пользователь вводит не на стороне эмитента, а в веб-сервисе мерчанта.
Для поддержки аутентификации пользователя по инициативе платежной системы нужно позаботиться о том, чтобы ваш веб-сервис принимал проверочные коды от пользователя и передавал их в платежную платформу.
Схема работы
С технической точки зрения платеж с аутентификацией по инициативе платежной системы осуществляется через процедуру дополнения информации о платеже. После обработки начального запроса платежная система отправляет в веб-сервис оповещение с информацией о необходимости предоставить проверочный код. При получении такого оповещения ваш веб-сервис должен получить проверочный код от пользователя и отправить его в платформу в составе запроса на продолжение платежа.
Время ожидания запроса на продолжение платежа зависит от используемого платежного метода и измеряется с момента выявления необходимости дополнить данные и до получения запроса от веб-сервиса. Если до истечения времени ожидания запрос в платформу не поступит, платеж будет автоматически отклонен. Как только в платежную платформу поступают все запрашиваемые данные, проведение платежа продолжается.
Таким образом, в процессе взаимодействия с платежной платформой для аутентификации пользователя по инициативе платежной системы ваш веб-сервис должен:
- Принять оповещение о необходимости указать проверочный код.
- Получить проверочный код от пользователя.
- Отправить запрос о продолжении платежа с полученным кодом.
В некоторых регионах платежная платформа предоставляет возможность запросить повторную отправку сообщения с проверочным кодом. Подробнее об этой функциональности см. Повторная отправка проверочного кода далее. Подробнее о доступности этой функциональности уточняйте у своего курирующего менеджера.
Подробнее о процедуре дополнения информации о платеже см. Дополнение информации о платеже. Примеры данных из оповещения и запроса для аутентификации пользователя по инициативе платежной системы представлены далее в этом разделе.
Форматы данных
Форматы оповещения и запроса, используемых при аутентификации по инициативе платежной системы, аналогичны форматам оповещения и запроса при дополнении информации о платеже за исключением некоторых параметров, которые описаны далее.
Тело оповещения о необходимости передать проверочный код содержит следующие дополнительные элементы:
- provider_extra_fields — объект, содержащий сведения об отправке проверочного кода:
- new_attempt_time — момент времени в формате "Unix-время", до которого в платформу должен поступить проверочный код.
Чтобы обеспечить своевременное подтверждение платежа, отправить запрос с кодом подтверждения надо до наступления срока, указанного в параметре new_attempt_time. Запрос с кодом подтверждения отправляется по механизму дополнения информации о платеже. После получения кода проведение платежа продолжится на стороне платежной платформы и сервиса провайдера, а в веб-сервис будет отправлено итоговое оповещение.
{
"provider_extra_fields": {
"new_attempt_time": 1681736775
},
"clarification_fields": [
"confirm_code"
],
"customer": {
"id": "123456"
},
"account": {
"number": "123456******1234",
"type": "uzcard",
"card_holder": "John Dow",
"expiry_month": "05",
"expiry_year": "2025"
},
"project_id": 100992,
"payment": {
"id": "payment_12",
"type": "purchase",
"status": "awaiting clarification",
"date": "2023-04-19T12:12:40+0000",
"method": "card",
"sum": {
"amount": 204000,
"currency": "UZS"
},
"description": ""
},
"operation": {
"sum_initial": {
"amount": 204000,
"currency": "UZS"
},
"sum_converted": {
"amount": 204000,
"currency": "UZS"
},
"code": "19999",
"message": "Awaiting processing",
"provider": {
"id": 11131,
"payment_id": "",
"auth_code": "",
"endpoint_id": 11131
},
"id": 42737010081577,
"type": "sale",
"status": "awaiting clarification",
"date": "2023-04-19T12:12:40+0000",
"created_date": "2023-04-19T12:12:38+0000",
"request_id": "d8ce5b71...0-00042738"
},
"signature": "bBw5bW5hVs...oQUXQfxnuhP5RvN/+YEEZe1t6gS10Uw=="
}
{
"general": {
"project_id": 11,
"payment_id": "pID-14",
"signature": "v7KNMpfog...=="
},
"additional_data": {
"confirm_code":"123456"
}
}
Повторная отправка проверочного кода
Возможны ситуации, когда пользователь не получает сообщение с проверочным кодом, поэтому в некоторых регионах платежная платформа предоставляет возможность запросить повторную отправку сообщения с проверочным кодом. Подробнее о доступности этой функциональности уточняйте у своего курирующего менеджера. Далее в этом разделе описан порядок применения и формат запроса о повторной отправке и приведены примеры оповещения и запроса о повторной отправке проверочного кода.
Если оповещение с информацией о необходимости предоставить проверочный код содержит объект resend, то в текущем платеже возможна повторная отправка проверочного кода. Объект resend содержит следующие параметры:
- new_attempt_time — момент времени в формате "Unix-время", до которого в платформу должен поступить проверочный код. Запросить повторную отправку проверочного кода можно только после истечения срока, указанного в этом параметре.
- available_attempts_number — количество оставшихся попыток повторной отправки проверочного кода. Этот параметр определяет, сколько еще раз можно отправить запрос на повторную отправку проверочного кода.
Вот пример оповещения с объектом resend, информирующем о том, что есть еще одна попытка запроса повторной отправки проверочного кода.
{
"provider_extra_fields": {
"available_customer_actions": {
"resend": {
"new_attempt_time": 1681736775,
"available_attempts_number": 1
}
}
},
"clarification_fields": [
"confirm_code"
],
"customer": {
"id": "1"
},
"account": {
"number": "12345678******1234",
"type": "humo",
"card_holder": "JACK ONEAL",
"expiry_month": "08",
"expiry_year": "2027"
},
"project_id": 29781,
"payment": {
"id": "PAYMENT_123456",
"type": "purchase",
"status": "awaiting clarification",
"date": "2023-04-17T13:05:14+0000",
"method": "card",
"sum": {
"amount": 1000,
"currency": "UZS"
},
"description": "PAYMENT_1234"
},
"operation": {
"sum_initial": {
"amount": 0,
"currency": ""
},
"sum_converted": {
"amount": 0,
"currency": ""
},
"code": "0",
"message": "Success",
"provider": {
"id": 12345,
"payment_id": "",
"auth_code": "",
"endpoint_id": 12345
},
"id": 123456789,
"type": "customer action",
"status": "success",
"date": "2023-04-17T13:05:15+0000",
"created_date": "2023-04-17T13:05:14+0000",
"request_id": "05027333"
},
"signature": "MiMeZogWjdhqoO3rPGFmDxf...w0UHQ=="
}
В обычных условиях веб-сервис получает от пользователя проверочный код и отправляет его в платежную платформу до истечения срока, указанного в параметре new_attempt_time. Но далее мы будем рассматривать только порядок действий в ситуации, когда пользователь не предоставляет проверочный код в отведенный срок и веб-сервис задействует механизм повторной отправки проверочного кода.
В приведенном ниже сценарии получения проверочного кода предполагается, что параметр available_attempts_number в последнем оповещении о передаче проверочного кода больше нуля, иначе говоря платформа предоставляет как минимум одну попытку повторной отправки проверочного кода.
- Веб-сервис ожидает от пользователя предоставления проверочного кода в срок, указанный в параметре new_attempt_time.
На время ожидания ввода проверочного кода настоятельно рекомендуется закрыть пользователю возможность повторной отправки проверочного кода (например, отключить соответствующую кнопку).
- Веб-сервис не получает от пользователя проверочный код в отведенный срок.
По истечении срока ввода проверочного кода рекомендуется закрыть пользователю возможность ввода проверочного кода (например, сделать неактивным соответствующее поле ввода) и открыть возможность запроса нового проверочного кода (например, активировать соответствующую кнопку).
- Если пользователь запрашивает новый проверочный код, веб-сервис отправляет в конечную точку
/v2/customer/action/resendзапрос на повторную отправку проверочного кода.Формат запроса описан далее в этом разделе.
ОСТОРОЖНО: Запрос на повторную отправку проверочного кода следует направлять строго после истечения срока отправки проверочного кода в платежную платформу. - В ответ платформа направляет пользователю новое сообщение с проверочным кодом, а также отправляет в веб-сервис еще одно оповещение о необходимости предоставления проверочного кода.
Объект resend в этом оповещении содержит новый срок предоставления проверочного кода в параметре new_attempt_time, а также число оставшихся попыток повторной отправки проверочного кода в параметре available_attempts_number.
- Далее возможны два варианта:
- Пользователь вводит проверочный код в веб-сервисе и веб-сервис отправляет этот код в конечную точку /v2/payment/clarification в соответствии с процедурой дополнения информации о платеже.
После того, как веб-сервис направит запрос с проверочным кодом в платежную платформу, повторная отправка проверочного кода становится невозможной.
- Пользователь не предоставляет веб-сервису проверочный код в отведенный срок.
В таком случае веб-сервис может повторно запросить проверочный код, выполнив пп. 2–4, но только при условии, что в последнем оповещении о необходимости предоставления проверочного кода значение параметра available_attempts_number больше нуля.
- Пользователь вводит проверочный код в веб-сервисе и веб-сервис отправляет этот код в конечную точку /v2/payment/clarification в соответствии с процедурой дополнения информации о платеже.
Такой порядок повторной отправки проверочного кода применяется только в некоторых регионах. Подробнее о доступности этой функциональности уточняйте у своего курирующего менеджера.
Формат запроса о повторной отправке проверочного кода
Запрос о повторной отправке кода подтверждения пользователю отправляется методом POST в конечную точку /v2/customer/action/resend, относящейся к группе /v2/customer/action/{action_name}, и должен содержать следующие объекты и параметры:
- general — объект, содержащий основные сведения о запросе:
- project_id — идентификатор проекта, полученный от PSPHost при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- signature — подпись, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи);
- customer — объект, содержащий сведения о пользователе:
- ip_address — IP-адрес устройства пользователя.
Вот пример данных из запроса на повторную отправку кода подтверждения.
{
"general": {
"project_id": 1234,
"payment_id": "payment_47",
"signature": "PJkV8ej...9MTO8yJA=="
},
"customer": {
"ip_address": "198.51.100.47"
}
}