# Аутентификация 3‑D Secure {#ru_gate_payment_3ds}
статья об основных вариантах аутентификации пользователей с применением протокола 3‑D Secure при проведении через Gate карточных платежей, с использованием платформы Ecommpay
**На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md)
## Общая информация {#ru_gate_payment_3ds_overview}
### Обзор {#section_jg3_pjk_rvb .section}
Аутентификация пользователей с использованием протокола 3‑D Secure \(Three-Domain Secure\) предназначена для защиты от мошенничества при проведении онлайн-платежей с использованием платёжных карт. Она может выполняться с применением различных способов проверки подлинности пользователей: например, через указание пользователем одноразового проверочного кода \(One Time PIN, OTP\), через распознавание лица пользователя, с помощью проверки отпечатка пальца пользователя на его мобильном устройстве или даже без каких-либо действий со стороны пользователя, на основе имеющейся информации о нём, его устройстве и инициированном платеже. При этом в разных случаях со стороны эмитентов могут поддерживаться различные способы проверки.
**Прим.:** В настоящее время как со стороны платёжных систем American Express, Mastercard и Visa, так и со стороны Ecommpay поддерживается вторая версия протокола — 3‑D Secure 2. И представленная в этой статье информация относится к данной версии протокола.
В аутентификации 3‑D Secure задействуются три домена:
- *Домен эквайера*. В рамках работы с платёжной платформой Ecommpay к нему относятся веб-сервисы мерчантов, платёжная платформа и связанный с ней 3DS-сервер.
- *Домен совместимости*. К нему относятся серверы каталогов \(Directory Servers, DS\) международных платёжных систем.
- *Домен эмитента*. К нему относятся серверы управления доступом \(Access Control Servers, ACS\) эмитентов, а также страницы аутентификации \(ACS-страницы\), открываемые при обращениях к этим серверам.
Между этими доменами осуществляется обмен сообщениями, необходимыми для аутентификации пользователей. К таким сообщениям могут относиться запросы на аутентификацию \(Authentication Request Message, AReq\) и ответы на них \(Authentication Response Message, ARes\), а также запросы на подтверждение личности пользователя \(Challenge Request, CReq\) и ответы с информацией о результатах такого подтверждения \(Challenge Response, CRes\).
При работе с аутентификацией 3‑D Secure следует учитывать, что информация о возможности аутентификации держателей карт хранится на серверах управления доступом, и эту информацию в случае с каждой картой можно получить только после отправки запроса на проведение платежа. Также со стороны веб-сервиса и платёжной платформы невозможно отслеживать действия пользователей на страницах аутентификации — доступно лишь получение информации о результатах аутентификации.
### Варианты аутентификации {#section_sb4_qjy_svb .section}
При работе с протоколом 3‑D Secure могут применяться два варианта аутентификации:
- Аутентификация с подтверждением пользователем своей личности \(*challenge flow*\). В этом случае подтверждение личности пользователя выполняется, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом.
- Аутентификация без участия пользователя \(*frictionless flow*\). В этом случае личность пользователя подтверждается исходя из информации, которой располагает эмитент.
Со стороны мерчанта выбирать варианты аутентификации нельзя — можно лишь указывать предпочтения по такому выбору для конкретных платежей, но итоговое решение каждый раз принимается на стороне эмитента.Также, помимо указания предпочтений, в запросах на проведение платежей можно передавать ряд других необязательных параметров, применение которых может повышать вероятность выбора варианта аутентификации frictionless flow и, как следствие, способствовать повышению проходимости и улучшению пользовательского опыта. Информация о таких параметрах представлена [далее](ru_gate_payment_3ds.md#).
### Особенности {#ru_gate_payment_3ds_special_aspects}
#### Область применения {#section_ufm_mps_kdc .section}
Выполнение аутентификации 3‑D Secure, как правило, обязательно для платежей с прямым использованием платёжных карт. Это связано с требованиями второй директивы о платёжных услугах \(Payment Services Directive 2, PSD2\), включающими в себя необходимость выполнения строгой аутентификации пользователя \(Strong Customer Authentication, SCA\) при проведении таких платежей.
К платежам, на которые не распространяются требования PSD2 к строгой аутентификации, относятся:
- Оплаты с использованием платёжных карт, выпущенных за пределами Европейской экономической зоны.
- Оплаты с использованием анонимных предоплаченных платёжных карт, например с использованием подарочной карты или виртуальной карты с предоплаченной стоимостью.
- Оплаты категории Mail Order/Telephone Order \(MO/TO\).
- Оплаты, инициируемые мерчантом \(Merchant-initiated transactions, MIT\), к которым в платёжной платформе Ecommpay относятся регулярные оплаты и автооплаты \(с типом платежа `recurring`\), а также операции по изменению суммы предварительной блокировки \(с типом операции `incremental`\).
- Оплаты с использованием большинства альтернативных платёжных методов.
В платёжной платформе Ecommpay поддерживается определение таких платежей, и аутентификация для них не выполняется.
#### Допустимые исключения {#section_oks_mps_kdc .section}
Среди тех платежей, на которые распространяются базовые требования к строгой аутентификации, директива PSD2 допускает наличие исключений \(SCA Exemptions\), при которых аутентификация может не выполняться по решениям эмитентов. Такими исключениями могут выступать платежи следующих категорий:
- Платежи на незначительные суммы \(Low value\) — оплаты на суммы до 25 фунтов стерлингов \(в пределах Великобритании\) или 30 евро \(в пределах Европейской экономической зоны\), в случаях, когда с момента последней успешной аутентификации было проведено не более пяти платежей и общая сумма этих платежей не превышает 85 фунтов стерлингов или 100 евро соответственно.
- Платежи с низким уровнем риска \(Transaction Risk Analysis\) — оплаты, проводимые эквайером, уровень мошенничества в платёжном трафике которого соответствует порогам PSD2.
- Платежи доверенным мерчантам \(Trusted beneficiaries\) — оплаты в пользу тех мерчантов, которые по инициативе или с согласия держателя карты занесены в список доверенных.
- Безопасные корпоративные платежи \(Corporate payments\) — оплаты, инициируемые юридическими лицами с использованием процессов и протоколов, обеспечивающих высокий уровень защиты от мошенничества \(таких как Electronic Banking Internet Communication Standard, EBICS\).
В платёжной платформе Ecommpay поддерживается работа с исключениями для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa в рамках первых двух категорий \(на незначительные суммы и с низким уровнем риска\).
#### Работа с допустимыми исключениями {#section_tfb_nps_kdc .section}
Применение исключений может уменьшать количество действий со стороны пользователей и положительно влиять на проходимость платежей. При этом ответственность за возможные мошеннические действия для таких платежей возлагается на мерчанта.
Если эта возможность подключена, то применение соответствующих исключений инициируется автоматически, кроме тех случаев, когда со стороны мерчанта указано предпочтительное выполнение аутентификации. При этом следует учитывать, что в случае проведения платежа, который относится к исключениям, итоговое решение о необходимости аутентификации так же остаётся за эмитентом. С его стороны может быть направлен „мягкий отказ“ \(soft decline\), означающий необходимость выполнения аутентификации. В случае получения такого отказа аутентификация для искомого платежа выполняется стандартно, без применения исключений, и, как правило, в варианте *challenge flow*. Кроме того, исключения не могут применяться при регистрации повторяемых оплат — в таких случаях выполнение аутентификации 3‑D Secure обязательно.
Информация о применённых исключениях передаётся в оповещениях о результатах платежей и отображается в карточках платежей в интерфейсе Dashboard. По вопросам, касающимся подключения возможности применения исключений, можно обращаться к курирующему менеджеру Ecommpay.
### Пользовательские сценарии {#ru_gate_payment_3ds_user_scenarios}
С учётом допустимости разных вариантов аутентификации 3‑D Secure, а также с учётом других факторов \(в частности, способов оформления страниц ожидания и используемого платёжного интерфейса\), процесс аутентификации может выглядеть для пользователей по-разному.
В случае с вариантом challenge flow и с перенаправлением пользователя к ACS-странице на стороне эмитента для ввода одноразового кода сценарий может соответствовать следующим иллюстрациям.
В случае с вариантом frictionless flow из такого сценария исключаются шаги с перенаправлением пользователя к ACS-странице и последующим возвращением к веб-сервису.
## Схемы работы {#ru_gate_payment_3ds_workflow}
### Общая информация {#section_fct_smf_tvb .section}
Как и пользовательские сценарии, схемы работы веб-сервиса и других сторон при выполнении аутентификации 3‑D Secure могут различаться. При этом существенными факторами для веб-сервиса выступают внешние решения относительно необходимости сбора дополнительных сведений об устройстве пользователя и относительно варианта аутентификации — каждое из этих решений может вызывать необходимость выполнения соответствующей процедуры дополнительно к базовым действиям по проведению искомого платежа.
|Варианты работы|без сбора сведений|со сбором сведений|
|---------------|------------------|------------------|
|frictionless flow|- базовые действия
|- базовые действия
- сбор сведений
|
|challenge flow|- базовые действия
- перенаправление
|- базовые действия
- сбор сведений
- перенаправление
|
Самостоятельно выбирать какие-либо из этих сценариев со стороны мерчантов нельзя. Но можно влиять на решения других сторон — через передачу рекомендуемых параметров и указание предпочтений по варианту аутентификации \(frictionless flow или challenge flow\) для конкретных платежей.
### Общая схема работы {#section_j4f_3wk_3jc .section}
Общую схему проведения оплаты с аутентификацией 3‑D Secure можно представить следующим образом.
1. В платёжной платформе выполняется обработка исходного запроса на проведение платежа и выявляется необходимость аутентификации 3‑D Secure \(согласно действующим требованиям к проведению платежей\).
2. От платёжной платформы к 3DS‑серверу, связанному с платёжной платформой, передаётся запрос на проверку возможности аутентификации для указанной карты и необходимости сбора сведений об устройстве пользователя.
3. На стороне 3DS‑сервера проверяются возможность аутентификации и необходимость сбора сведений.
4. От 3DS‑сервера к платёжной платформе направляется ответ с информацией о возможности аутентификации и о необходимости сбора дополнительных сведений об устройстве пользователя.
5. В платёжной платформе обрабатывается полученная информация. При этом в случае, если сбор дополнительных сведений не требуется, инициируется выполнение следующего шага \(шага 6\), а в случае необходимости сбора дополнительных сведений выполняются следующие шаги:
1. От платёжной платформы к веб-сервису направляется оповещение с данными для сбора дополнительных сведений об устройстве пользователя.
2. От веб-сервиса к платёжной платформе направляется синхронный ответ о приёме данных.
3. На стороне веб-сервиса выполняется код для сбора дополнительных сведений об устройстве пользователя, с открытием служебного объекта iframe.
4. На устройстве пользователя автоматически выполняются сбор необходимых сведений и их отправка к серверу управления доступом \(Access Control Server\) эмитента.
5. От эмитента к веб-сервису передаётся уведомление о приёме данных.
6. От веб-сервиса на заданный URL Ecommpay передаётся запрос на аутентификацию пользователя.
7. Запрос поступает в платёжную платформу.
8. В платёжной платформе выполняется приём запроса с проверкой его корректности.
9. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
6. От платёжной платформы к 3DS-серверу передаётся запрос на аутентификацию пользователя.
7. Запрос передаётся от 3DS‑сервера к серверу каталогов международной платёжной системы \(Directory Server\).
8. Запрос передаётся от сервера каталогов к серверу управления доступом.
9. На стороне эмитента выполняется аутентификация пользователя. При этом в случае выбора эмитентом варианта аутентификации frictionless flow от сервера управления доступом к платёжной платформе \(через сервер каталогов и 3DS-сервер\) передаётся информация о результате аутентификации, а в случае выбора варианта аутентификации challenge flow выполняются следующие шаги:
1. От сервера управления доступом к серверу каталогов и далее к 3DS-серверу и платёжной платформе передаются данные для перенаправления пользователя на страницу аутентификации \(ACS URL\).
2. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления.
3. Со стороны веб-сервиса выполняется перенаправление пользователя на страницу аутентификации.
4. Пользователю отображается страница аутентификации, после чего он осуществляет требуемые действия.
5. На стороне эмитента выполняется аутентификация пользователя.
6. От сервера управления доступом к серверу каталогов и далее к 3DS-серверу передаётся информация о результате проверки.
7. От 3DS‑сервера к серверу каталогов и далее к серверу управления доступом передаётся ответ о приёме этой информации.
8. Со стороны сервера управления доступом выполняется перенаправление пользователя к веб-сервису с передачей данных о результате аутентификации.
9. Пользователю отображается страница ожидания веб-сервиса.
10. От веб-сервиса на заданный URL Ecommpay передаётся запрос на продолжение проведения платежа с учётом результата аутентификации.
11. Запрос поступает в платёжную платформу.
12. В платёжной платформе выполняется приём запроса с проверкой его корректности.
13. От платёжной платформы к веб-сервису направляется синхронный ответ с информацией о получении запроса и его корректности, после чего обрабатывается информация о результате аутентификации и осуществляется переход к оставшимся действиям для проведения искомого платежа.
Информация о форматах оповещений и запросов, используемых в рамках этой схемы, приведена [далее](ru_gate_payment_3ds.md#) в этой статье; общая информация о работе с Gate API — в статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). Также стоит учитывать, что в различных случаях эта схема может дополняться другими процедурами и действиями, не касающимися непосредственно аутентификации и описанными в соответствующих статьях настоящей документации.
### Сбор сведений об устройстве пользователя {#section_xw2_jwk_3jc .section}
В случаях, когда для эмитента актуален сбор дополнительных сведений об устройстве пользователя, к веб-сервису от платформы отправляется соответствующее [оповещение](ru_gate_payment_3ds.md#section_jnw_q24_cjb). При получении такого оповещения необходимо:
1. Проверить целостность данных путём сличения расчётной подписи с представленной в оповещении.
2. Подтвердить приём оповещения, отправив положительный синхронный ответ \(200 OK\) к платформе.
3. Открыть в клиентской части веб-сервиса элемент iframe для сбора сведений об устройстве пользователя с использованием данных из оповещения \([подробнее](ru_gate_payment_3ds.md#fig_zly_wq2_bjb)\).
4. Принять [уведомление о приёме сведений](ru_gate_payment_3ds.md#section_d4n_vky_svb) от сервера управления доступом \(ACS\) эмитента.
5. Отправить [запрос на аутентификацию](ru_gate_payment_3ds.md#section_o1k_yky_svb) в платёжную платформу.
**Прим.:** Частоту применения этой процедуры по запросам эмитентов можно минимизировать, если обеспечивать со стороны веб-сервиса предварительные сбор и отправку информации об устройствах пользователей \([подробнее](ru_gate_payment_3ds.md#)\).
### Перенаправление пользователя к странице аутентификации {#section_ms4_hcm_3jc .section}
В случаях, когда для эмитента актуален вариант аутентификации challenge flow с перенаправлением пользователя к ACS-странице, к веб-сервису от платформы отправляется соответствующее [оповещение](ru_gate_payment_3ds.md#section_drq_xq1_1jb). При получении такого оповещения необходимо:
1. Проверить целостность данных путём сличения расчётной подписи с представленной в оповещении.
2. Подтвердить приём оповещения, отправив положительный синхронный ответ \(200 OK\) к платформе.
3. Перенаправить пользователя на страницу аутентификации с использованием данных из оповещения \([подробнее](ru_gate_payment_3ds.md#fig_k3g_qr2_bjb)\) и с соблюдением ограничения в 30 секунд с момента приёма оповещения о необходимости перенаправления.
4. Принять [уведомление о результате аутентификации](ru_gate_payment_3ds.md#section_cjg_rss_njb) от эмитента.
5. Отправить [запрос на продолжение проведения платежа](ru_gate_payment_3ds.md#section_gps_1fc_t3b) с учётом результата аутентификации с соблюдением ограничения в 30 минут с момента приёма оповещения о необходимости перенаправления.
6. Если используется возможность каскадного проведения платежей \([подробнее](ru_gate_cascading.md#)\) и повторно получено оповещение о необходимости перенаправления пользователя \(со значением `true` для параметра `cascading_with_redirect`\):
1. Повторить шаги 1–2 этой процедуры, с проверкой и подтверждением приёма оповещения.
2. Отобразить пользователю сообщение об ошибке при предыдущей попытке аутентификации.
3. Получить согласие пользователя на повторную аутентификацию.
4. Повторить шаги 3–5 этой процедуры.
**Прим.:** Частоту применения этой процедуры по запросам эмитентов можно минимизировать, если обеспечивать со стороны веб-сервиса предварительные сбор и отправку рекомендуемых сведений \([подробнее](ru_gate_payment_3ds.md#section_f32_tfl_lxb)\).
## Работа со сведениями об устройстве пользователя {#ru_gate_payment_3ds_collecting_data}
Чтобы улучшать пользовательский опыт и проходимость платежей, уместно минимизировать число действий в рамках аутентификации пользователей. Для этого в запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, полезно передавать ряд таких параметров, которые помогают уменьшать вероятность применения процедур со сбором дополнительных сведений об устройствах пользователей и с перенаправлениями пользователей к страницам аутентификации. В число таких параметров, полный перечень которых представлен [далее](ru_gate_payment_3ds.md#), наряду со сведениями о пользователе и платеже входят следующие сведения об устройстве и браузере пользователя:
- Сведения об устройстве, определяемые на клиентской стороне веб-сервиса:
- `accept_header` — значение HTTP-заголовка Accept;
- `accept_language_header` — значение параметра Accept-Language, которое указывает предпочтения в языке локализации;
- `browser` — значение HTTP-заголовка User-Agent;
- `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа.
- Сведения об устройстве, получаемые из запроса от используемого браузера к веб-сервису:
- `color_depth` — глубина цвета используемого устройства, в битах на пиксель;
- `java_enabled` — индикатор поддержки сценариев Java в используемом браузере;
- `js_enabled` — индикатор поддержки сценариев JavaScript в используемом браузере;
- `language` — код языка, выбранного для работы в используемом браузере;
- `screen_res` — разрешение экрана используемого устройства, в пикселях и с символом `x` в качестве разделителя \(например, `1920x1080`\);
- `timezone_name` — название часового пояса, который актуален для используемого браузера \(например, `Australia/Adelaide`\);
- `timezone_offset` — разница между временем для используемого браузера и UTC, в минутах \(например, `570`\).
``` {#codeblock_ihr_13v_33c .language-json}
"customer": {
"ip_address": "188.113.253.90",
"browser": "Mozilla/5.0 (Linux; Android 14; SM-A155F Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.67 Mobile Safari/537.36",
"screen_res": "1920x1080",
"language": "en_US",
"accept_header": "*/*",
"accept_language_header": "en-GB,en;q=0.8,fr;q=0.3",
"color_depth": 24,
"java_enabled": false,
"js_enabled": true,
"timezone_offset": "570"
}
```
Со стороны веб-сервиса сбор и использование таких сведений об устройстве и браузере пользователя можно организовать следующим образом.
1. Определить сведения об устройстве пользователя в клиентской части веб-сервиса.
``` {#codeblock_cvf_lz5_33c .language-javascript}
function collectClientData() {
return {
// разрешение экрана устройства
screen_res: `${screen.width}x${screen.height}`,
// код языка, выбранного в браузере
language: navigator.language,
// глубина цвета браузера
color_depth: screen.colorDepth,
// индикатор поддержки сценариев Java в браузере
java_enabled: navigator.javaEnabled(),
// индикатор поддержки сценариев JavaScript в браузере
js_enabled: true,
// разница между временем для браузера и UTC
timezone_offset: new Date().getTimezoneOffset().toString(),
};
}
```
2. Отправить собранные сведения из клиентской части веб-сервиса в серверную.
``` {#codeblock_lnp_lz5_33c .language-javascript}
async function sendClientDataToServer(endpoint = '/api/collect-client-data') {
try {
const clientData = collectClientData();
const response = await fetch(endpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': '*/*'
},
body: JSON.stringify(clientData)
});
const result = await response.json();
return result;
} catch (error) {
console.error('Ошибка отправки данных:', error);
throw error;
}
}
```
3. Дополнить эти сведения полученными из запроса от браузера пользователя к веб-сервису и использовать их наряду с другими актуальными параметрами для формирования и отправки запроса на проведение искомого платежа.
``` {#codeblock_n4t_kz5_33c .language-php}
interface CustomerData
{
public function getIpAddress(): ?string;
public function getAcceptHeader(): ?string;
public function getAcceptLanguageHeader(): ?string;
public function getScreenRes(): ?string;
public function getBrowser(): ?string;
public function getLanguage(): ?string;
public function getColorDepth(): ?int;
public function getJavaEnabled(): ?bool;
public function getJsEnabled(): ?bool;
public function getTimezoneOffset(): ?string;
}
interface CardData
{
public function getPan();
public function getYear();
public function getMonth();
public function getCardHolder();
public function getCvv();
}
interface PaymentData
{
public function getPaymentId(): string;
public function getAmount(): int;
public function getCurrency(): string;
public function getCardData(): CardData;
public function getCustomerData(): CustomerData;
}
interface HttpClient
{
public function sendRequest(array $request): bool;
}
interface Signer
{
public function sign(array $params): string;
}
final class PaymentController
{
public function __construct(
private Signer $signer,
private HttpClient $httpClient,
private int $projectId,
) {}
public function processPayment(PaymentData $paymentData): void
{
$paymentRequest = [
'general' => [
'project_id' => $this->projectId,
'payment_id' => $paymentData->getPaymentId(),
],
'customer' => $this->prepareCustomerData($paymentData->getCustomerData()),
'payment' => [
'amount' => $paymentData->getAmount(),
'currency' => $paymentData->getCurrency(),
],
'card' => [
'pan' => $paymentData->getCardData()->getPan(),
'year' => $paymentData->getCardData()->getYear(),
'month' => $paymentData->getCardData()->getMonth(),
'card_holder' => $paymentData->getCardData()->getCardHolder(),
'cvv' => $paymentData->getCardData()->getCvv(),
],
];
$paymentRequest['general']['signature'] = $this->signer->sign($paymentRequest);
$this->httpClient->sendRequest($paymentRequest);
}
private function prepareCustomerData(CustomerData $customerData): array
{
return array_filter([
'ip_address' => $customerData->getIpAddress(),
'browser' => $customerData->getBrowser(),
'screen_res' => $customerData->getScreenRes(),
'language' => $customerData->getLanguage(),
'accept_header' => $customerData->getAcceptHeader(),
'accept_language_header' => $customerData->getAcceptLanguageHeader(),
'color_depth' => $customerData->getColorDepth(),
'java_enabled' => $customerData->getJavaEnabled(),
'js_enabled' => $customerData->getJsEnabled(),
'timezone_offset' => $customerData->getTimezoneOffset(),
]);
}
}
```
``` {#codeblock_lbz_g1v_33c}
package main
import "encoding/json"
// CustomerData interface
type CustomerData interface {
GetIpAddress() *string
GetAcceptHeader() *string
GetAcceptLanguageHeader() *string
GetScreenRes() *string
GetBrowser() *string
GetLanguage() *string
GetColorDepth() *int
GetJavaEnabled() *bool
GetJsEnabled() *bool
GetTimezoneOffset() *string
}
// CardData interface
type CardData interface {
GetPan() interface{}
GetYear() interface{}
GetMonth() interface{}
GetCardHolder() interface{}
GetCvv() interface{}
}
// PaymentData interface
type PaymentData interface {
GetPaymentId() string
GetAmount() int
GetCurrency() string
GetCardData() CardData
GetCustomerData() CustomerData
}
// HttpClient interface
type HttpClient interface {
SendRequest(request map[string]interface{}) bool
}
// Signer interface
type Signer interface {
Sign(params map[string]interface{}) string
}
// PaymentController struct
type PaymentController struct {
signer Signer
httpClient HttpClient
projectId int
}
// NewPaymentController constructor
func NewPaymentController(signer Signer, httpClient HttpClient, projectId int) *PaymentController {
return &PaymentController{
signer: signer,
httpClient: httpClient,
projectId: projectId,
}
}
// ProcessPayment processes the payment
func (pc *PaymentController) ProcessPayment(paymentData PaymentData) {
cardData := paymentData.GetCardData()
paymentRequest := map[string]interface{}{
"general": map[string]interface{}{
"project_id": pc.projectId,
"payment_id": paymentData.GetPaymentId(),
},
"customer": pc.prepareCustomerData(paymentData.GetCustomerData()),
"payment": map[string]interface{}{
"amount": paymentData.GetAmount(),
"currency": paymentData.GetCurrency(),
},
"card": map[string]interface{}{
"pan": cardData.GetPan(),
"year": cardData.GetYear(),
"month": cardData.GetMonth(),
"card_holder": cardData.GetCardHolder(),
"cvv": cardData.GetCvv(),
},
}
// Add signature
general := paymentRequest["general"].(map[string]interface{})
general["signature"] = pc.signer.Sign(paymentRequest)
// Send request
pc.httpClient.SendRequest(paymentRequest)
}
// prepareCustomerData filters and prepares customer data
func (pc *PaymentController) prepareCustomerData(customerData CustomerData) map[string]interface{} {
result := make(map[string]interface{})
if v := customerData.GetIpAddress(); v != nil {
result["ip_address"] = *v
}
if v := customerData.GetBrowser(); v != nil {
result["browser"] = *v
}
if v := customerData.GetScreenRes(); v != nil {
result["screen_res"] = *v
}
if v := customerData.GetLanguage(); v != nil {
result["language"] = *v
}
if v := customerData.GetAcceptHeader(); v != nil {
result["accept_header"] = *v
}
if v := customerData.GetAcceptLanguageHeader(); v != nil {
result["accept_language_header"] = *v
}
if v := customerData.GetColorDepth(); v != nil {
result["color_depth"] = *v
}
if v := customerData.GetJavaEnabled(); v != nil {
result["java_enabled"] = *v
}
if v := customerData.GetJsEnabled(); v != nil {
result["js_enabled"] = *v
}
if v := customerData.GetTimezoneOffset(); v != nil {
result["timezone_offset"] = *v
}
return result
}
```
**Прим.:** Следует учитывать, что представленные здесь примеры кода для работы со сведениями об устройстве пользователя носят информативный характер и не допускают их использования в прямом виде \(«как есть»\) без проверки и доработки на соответствие всем актуальным требованиям на стороне веб-сервиса, включая [требования PCI DSS](ru_faq_integration.md#fig_fgk_rgs_4nb).
## Формат запросов на проведение платежей {#ru_gate_payment_3ds_formats_request}
### Общая информация {#section_pj3_4gr_k3c .section}
Общий формат запросов на проведение платежей с возможностью выполнения аутентификации 3‑D Secure должен соответствовать описанному в статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). При этом для каждого запроса может быть актуальным свой набор параметров:
- в любом случае должны использоваться параметры, обязательные для соответствующего типа платежа \(подробнее — в статьях о типах платежей\), и параметры, перечисленные далее как [обязательные](ru_gate_payment_3ds.md#section_ppq_gfl_lxb) для выполнения аутентификации 3‑D Secure;
- в случаях, когда предпочтительны сценарии без сбора дополнительных сведений об устройстве пользователя и без перенаправления пользователя к странице аутентификации \(с вариантом frictionless flow\), желательно передавать максимальное число параметров, которые перечислены далее как [рекомендуемые](ru_gate_payment_3ds.md#section_f32_tfl_lxb) для выполнения аутентификации 3‑D Secure;
- дополнительно могут использоваться любые другие параметры из числа допустимых для конкретного типа платежа.
### Обязательные параметры {#section_ppq_gfl_lxb .section}
В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, вместе с обязательными для соответствующего типа платежа параметрами необходимо передавать следующие объекты и параметры.
|Параметр|Описание| |
|--------|--------|--|
|`acs_return_url`
object
|Объект с адресами веб-сервиса, используемыми для аутентификации|1|
|`return_url`
string
|Адрес веб-сервиса для перенаправления пользователя после аутентификации|1-11|
|`3ds_notification_url`
string
|Адрес веб-сервиса для получения уведомления о том, что данные приняты сервером управления доступом|1-21|
|`customer`
object
|Объект со сведениями о пользователе|2|
|`ip_address`
string
|IP-адрес пользователя, актуальный для инициируемого платежа|2-12|
|`screen_res`
string
|Разрешение экрана используемого устройства, в пикселях и с символом `x` в качестве разделителя \(например, `1920x1080`\)|2-22|
|`email`
string
|Адрес электронной почты пользователя|2-32|
|`phone`
string
|Номер телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей|2-42|
|`card`
object
|Объект со сведениями о платёжной карте пользователя|3|
|`card_holder`
string
|Имя держателя карты, в соответствии с указанным на карте|3-13|
``` {#codeblock_gmn_gbx_x3c .language-json}
{
"general": {
"project_id": 42,
"payment_id": "456789",
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
},
"customer": { // сведения о пользователе
"ip_address": "248.121.176.220", // IP-адрес пользователя
"id": "customer_12",
"screen_res": "1920x1080", // разрешение экрана используемого устройства
"phone": "44991234567", // номер телефона пользователя
"email": "john_smith@email.com" // адрес электронной почты пользователя
},
"payment": {
"amount": 400000,
"currency": "USD"
},
"return_url": {
"success": "https://example.com/success",
"decline": "https://example.com/decline"
},
"card": {
"pan": "4314220000000056",
"year": 2025,
"month": 8,
"card_holder": "JOHN SMITH", // имя держателя карты
"cvv": "123"
},
"acs_return_url": { // сведения об адресах веб-сервиса
"return_url": "https://3DS_result_url", // адрес для перенаправления пользователя после аутентификации
"3ds_notification_url": "https://3DS_result_url" // адрес для получения уведомления о принятии данных
}
```
### Рекомендуемые параметры {#section_f32_tfl_lxb .section}
В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, рекомендуется передавать ряд необязательных параметров, указание которых может повышать вероятность выбора эмитентами варианта аутентификации frictionless flow, без участия пользователя, а также отказ от сбора дополнительных сведений об устройстве пользователя. Со стороны веб-сервиса можно передавать как полный, так и неполный набор таких параметров, с учётом наличия соответствующей информации. К базовому минимуму параметров, влияющих на решения эмитентов о варианте аутентификации и сборе сведений, при этом можно отнести платёжный адрес пользователя и сведения о его устройстве и браузере.
|Параметр|Описание| |
|--------|--------|--|
|`customer`
object
|Объект со сведениями о пользователе|2|
|`accept_header`
string
|Значение HTTP-заголовка Accept в соответствии с полученным со стороны используемого браузера|2-12|
|`accept_language_header`
string
|Значение параметра Accept-Language в соответствии с полученным со стороны используемого браузера. Представляет собой строку с перечислением кодов и уровней приоритетности \(q-values\) использования языков \(например, `en-GB,en;q=0.8,fr;q=0.3`\)|2-192|
|`browser`
string
|Значение HTTP-заголовка User-Agent в соответствии с полученным со стороны используемого браузера|2-22|
|`color_depth`
integer
|Глубина цвета используемого устройства, в битах на пиксель|2-32|
|`java_enabled`
boolean
|Индикатор поддержки сценариев Java в используемом браузере|2-42|
|`js_enabled`
boolean
|Индикатор поддержки сценариев JavaScript в используемом браузере|2-52|
|`language`
string
|Код языка, выбранного для работы в используемом браузере|2-62|
|`timezone_name`
string
|Название часового пояса, который актуален для используемого браузера \(например, `Australia/Adelaide`\)|2-82|
|`timezone_offset`
string
|Разница между временем для используемого браузера и UTC, в минутах \(например, `570`\)|2-92|
|`address_match`
boolean
|Указатель совпадения расчётного адреса пользователя с адресом доставки, указанным в объекте `shipping`, который может принимать оно из следующих значений:
- `true` — адреса совпадают
- `false` — адреса не совпадают
|2-102|
|`home_phone`
string
|Номер домашнего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44991234567`\)|2-112|
|`work_phone`
string
|Номер рабочего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44997654321`\)|2-122|
|`account`
object
|Объект со сведениями об учётной записи пользователя на стороне веб-сервиса мерчанта|2-132|
|`additional`
string
|Дополнительная информация об учётной записи пользователя, например её идентификатор, в произвольном формате с использованием до 64 символов|2-13-12-13|
|`activity_day`
integer
|Количество попыток проведения оплаты за последние 24 часа, в виде числа от 0 до 999 \(`999`\)|2-13-22-13|
|`activity_year`
integer
|Количество попыток проведения оплаты за последние 365 дней, в виде числа от 0 до 999 \(`999`\)|2-13-32-13|
|`age_indicator`
string
|Индикатор давности учётной записи, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(при инициировании платежа без аутентификации пользователя\)
- `02` — при нулевой давности \(при создании учётной записи для инициирования платежа\)
- `03` — при давности менее 30 дней
- `04` — при давности от 30 до 60 дней
- `05` — при давности более 60 дней
|2-13-42-13|
|`auth_data`
string
|Дополнительная информация об аутентификации на стороне веб-сервиса, в произвольном формате с использованием не более 255 символов|2-13-52-13|
|`auth_method`
string
|Указатель способа последней аутентификации пользователя на стороне веб-сервиса, который может принимать одно из следующих значений:- `01` — отсутствие аутентификации
- `02` — аутентификация с использованием данных, сохранённых на стороне веб-сервиса мерчанта
- `03` — аутентификация с использованием технологии Federated Identity \(например, Google Account или Facebook\)
- `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\)
|2-13-62-13|
|`auth_time`
string
|Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`|2-13-72-13|
|`date`
string
|Дата создания учётной записи в формате `ДД-ММ-ГГГГ`|2-13-82-13|
|`change_date`
string
|Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`|2-13-92-13|
|`change_indicator`
string
|Индикатор давности изменений в учётной записи, за исключением изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при нулевой давности \(при изменениях в день проведения платежа\)
- `02` — при давности менее 30 дней
- `03` — при давности от 30 до 60 дней
- `04` — при давности более 60 дней
|2-13-102-13|
|`pass_change_date`
string
|Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`|2-13-112-13|
|`pass_change_indicator`
string
|Индикатор давности последнего изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(пароль не был изменён или сброшен\)
- `02` — при нулевой давности \(пароль был изменён или сброшен в день проведения платежа\)
- `03` — при давности менее 30 дней
- `04` — при давности от 30 до 60 дней
- `05` — при давности более 60 дней
|2-13-122-13|
|`payment_age`
string
|Дата добавления реквизитов платёжного инструмента в формате `ДД-ММ-ГГГГ`|2-13-132-13|
|`payment_age_indicator`
string
|Индикатор давности сохранения данных платёжного инструмента, используемых для проведения платежа, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(платёж проводится без аутентификации в учётной записи\)
- `02` — при нулевой давности \(данные карты сохранены в день проведения платежа\)
- `03` — при давности менее 30 дней
- `04` — при давности от 30 до 60 дней
- `05` — при давности более 60 дней
|2-13-142-13|
|`provision_attempts`
integer
|Количество попыток сохранения реквизитов для новых платёжных инструментов за последние 24 часа, от 0 до 999 \(`999`\)|2-13-152-13|
|`purchase_number`
integer
|Количество покупок, совершённых через учётную запись за последние 6 месяцев, от 0 до 9999 \(`9999`\)|2-13-162-13|
|`suspicious_activity`
string
|Индикатор подозрительной активности, который может принимать одно из следующих значений:- `01` — без выявления подозрительной активности
- `02` — с выявлением подозрительной активности
|2-13-172-13|
|`billing`
object
|Объект со сведениями о расчётном адресе пользователя|2-162|
|`address`
string
|Название улицы в расчётном адресе пользователя|2-16-12-16|
|`city`
string
|Название города в расчётном адресе пользователя|2-16-22-16|
|`country`
string
|Код страны в расчётном адресе пользователя в формате ISO 3166-1 alpha-2|2-16-32-16|
|`postal`
string
|Почтовый индекс в расчётном адресе пользователя|2-16-42-16|
|`region_code`
string
|Внутренний код региона \(штата, провинции или иной территориальной области\) в расчётном адресе пользователя.
Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. При указании значения этого параметра также необходимо указать значение параметра `country` этого же объекта
|2-16-52-16|
|`shipping`
object
|Объект со сведениями о доставке|2-172|
|`address`
string
|Название улицы и номер дома в адресе доставки \(с обозначением корпуса или строения, где это актуально\), в виде строки длиной не более 150 символов|2-17-12-17|
|`address_usage`
string
|Дата первого использования указанного адреса, в формате `ДД-ММ-ГГГГ`|2-17-22-17|
|`address_usage_indicator`
string
|Индикатор давности первого использования указанного адреса доставки, который может принимать одно из следующих значений:- `01` — при нулевой давности \(указанный адрес используется впервые\)
- `02` — при давности менее 30 дней
- `03` — при давности от 30 до 60 дней
- `04` — при давности более 60 дней
|2-17-32-17|
|`city`
string
|Название города \(или иного населённого пункта\) в адресе доставки, в виде строки длиной не более 50 символов|2-17-42-17|
|`country`
string
|Код страны в адресе доставки в формате ISO 3166-1 alpha-2 \(например, [GB](references/ru/countries/GB.md)\)|2-17-52-17|
|`delivery_email`
string
|Адрес электронной почты в случае доставки на этот адрес, который может содержать не более 255 символов|2-17-62-17|
|`delivery_time`
string
|Индикатор срока доставки, который может принимать одно из следующих значений:- `01` — в день покупки в электронном виде
- `02` — в день покупки в материальном виде
- `03` — на следующий день после покупки
- `04` — позднее чем на следующий день после покупки
|2-17-72-17|
|`name_indicator`
string
|Индикатор совпадения имени пользователя с именем получателя доставки, который может принимать одно из следующих значений:- `01` — имена совпадают
- `02` — имена не совпадают
|2-17-82-17|
|`postal`
string
|Почтовый индекс в адресе доставки, представляет собой строку длиной не более 16 символов|2-17-92-17|
|`region_code`
string
|Внутренний код региона в адресе доставки, представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, например `DOR` для графства Дорсет.
При указании значения этого параметра также необходимо указать значение параметра `country` этого же объекта
|2-17-102-17|
|`type`
string
|Указатель варианта доставки, который может принимать одно из следующих значений:- `01` — доставка на расчётный адрес держателя карты
- `02` — доставка на другой подтверждённый адрес
- `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым
- `04` — доставка в магазин мерчанта
- `05` — доставка в электронном виде
- `06` — отсутствие доставки
- `07` — другой вариант
|2-17-112-17|
|`mpi_result`
object
|Объект со сведениями о предыдущей аутентификации пользователя|2-182|
|`acs_operation_id`
string
|Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре `acs_operation_id` оповещения о результате проведения предыдущего платежа|2-18-12-18|
|`authentication_flow`
string
|Указатель варианта предыдущего прохождения аутентификации пользователем, полученный в параметре `authentication_flow` оповещения о результате проведения предыдущего платежа, который может принимать оно из следующих значений:
- `01` — frictionless flow
- `02` — challenge flow
|2-18-22-18|
|`authentication_timestamp`
string
|Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре `mpi_timestamp` оповещения о результате проведения предыдущего платежа|2-18-32-18|
|`payment`
object
|Объект со сведениями о платеже|3|
|`challenge_indicator`
string
|Индикатор предпочтения по использованию варианта аутентификации challenge flow, который может принимать одно из следующих значений:- `01` — без предпочтений
- `02` — предпочтительно не использовать
- `03` — предпочтительно использовать
- `04` — обязательно использовать
- `05` — не использовать, анализ рисков выполнен на стороне мерчанта
- `06` — не использовать, применить сценарий Data Only
- `07` — не использовать, Strong Customer Authentication уже выполнена иным способом
- `08` — не использовать, мерчант включен в список доверенных для этого пользователя
- `09` — обязательно использовать, предпочтительно предложить пользователю добавить мерчанта в список доверенных
|3-13|
|`challenge_window`
string
|Индикатор размера окна для открытия страницы аутентификации, который может принимать одно из следующих значений:- `01` — 250 x 400 пикселей
- `02` — 390 x 400 пикселей
- `03` — 500 x 600 пикселей
- `04` — 600 x 400 пикселей
- `05` — полноэкранный режим
|3-23|
|`preorder_date`
string
|Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`|3-33|
|`preorder_purchase`
string
|Индикатор предварительного заказа, который может принимать одно из следующих значений:- `01` — не является предварительным заказом
- `02` — является предварительным заказом
|3-43|
|`reorder`
string
|Индикатор первичной или повторной покупки данного товара или услуги пользователем, который может принимать одно из следующих значений:- `01` — первичная покупка
- `02` — повторная покупка
|3-53|
|`gift_card`
object
|Объект со сведениями о покупке предоплаченных или подарочных карт|3-63|
|`amount`
integer
|Сумма покупки, в дробных единицах валюты, указанной в параметре `currency` этого же объекта|3-6-13-6|
|`currency`
string
|Код валюты для суммы покупки в формате ISO 4217 alpha-3 \(например, [GBP](references/ru/currencies/GBP.md)\)|3-6-23-6|
|`count`
integer
|Количество приобретаемых предоплаченных или подарочных карт|3-6-33-6|
## Форматы промежуточных сообщений {#ru_gate_payment_3ds_formats_messages}
### Формат оповещения о необходимости сбора дополнительных сведений {#section_jnw_q24_cjb .section}
Для сбора эмитентом дополнительных сведений об устройстве пользователя при выполнении аутентификации необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `iframe` объекта `threeds2` — чтобы сформировать служебный элемент iframe на странице веб-сервиса. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\), при этом в состав объекта `iframe` включаются сведения, которые необходимо использовать следующим образом: адрес из параметра `url` — в атрибуте `action` используемой формы в клиентской части веб-сервиса, а данные из других параметров — в тегах `input` этой же формы.
``` {#codeblock_on5_hfm_njc .language-json}
{
"threeds2":{
"iframe":{
"url":"https://example.com",
"params":{
"3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
"threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
}
}
}
}
```
``` {#codeblock_pn5_hfm_njc .language-xml}
```
### Формат уведомления о приёме дополнительных сведений {#section_d4n_vky_svb .section}
Для уведомлений о приёме дополнительных сведений об устройствах пользователей используются форматы эмитентов. Такие уведомления передаются от серверов управления доступом \(ACS\) эмитентов на адреса веб-сервисов, указанные в запросах на проведение платежей \(в параметре `3ds_notification_url`\). С вопросами о работе с такими уведомлениями можно обращаться к специалистам технической поддержки Ecommpay.
``` {#codeblock_qn5_hfm_njc .language-xml}
threeDSMethodData:eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImRiNmFjM2UwLWI5ZWQtNWQ3NS04MDAwLTAwMDAwMDAwMTA0MiJ9
threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455
```
### Формат запроса на инициирование аутентификации {#section_o1k_yky_svb .section}
Для инициирования аутентификации, когда это актуально после сбора дополнительных сведений об устройстве пользователя, каждый раз должен использоваться POST-запрос к конечной точке [/v2/payment/card/3ds\_check\_iframe](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-check-iframe). В каждом таком запросе должны использоваться следующие объекты и параметры:
- `general` — объект, содержащий основные идентификационные сведения запроса:
- `project_id` — идентификатор используемого проекта;
- `payment_id` — идентификатор проводимого платежа;
- `signature` — подпись к данным запроса, составленная после указания целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md#)\).
- `threeds_completion_indicator` — индикатор своевременного получения уведомления о приёме сведений — со значением `true`, если такое [уведомление](ru_gate_payment_3ds.md#section_d4n_vky_svb) получено в течение 10 секунд с момента открытия элемента iframe для сбора дополнительных сведений об устройстве пользователя, или `false`, если уведомление получено позже.
Таким образом, корректный запрос на инициирование аутентификации 3‑D Secure после сбора дополнительных сведений об устройстве пользователя должен содержать идентификаторы проекта и платежа, индикатор получения уведомления о сборе сведений в допустимый период и подпись.
``` {#codeblock_kzn_2hx_x3c .language-json}
{
"general":{
"project_id":42,
"payment_id":"456789",
"signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
},
"threeds_completion_indicator":true
}
```
### Формат оповещения о необходимости перенаправления {#section_drq_xq1_1jb .section}
Для перенаправления пользователей от веб-сервиса мерчанта к страницам аутентификации \(ACS URL\) эмитентов необходимо принимать промежуточные оповещения от платёжной платформы и использовать информацию из них, включённую в объект `redirect` объекта `threeds2`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\), при этом в состав объекта `redirect` включаются сведения, которые необходимо использовать следующим образом: адрес из параметра `url` — в атрибуте `action` используемой формы в клиентской части веб-сервиса, а данные из других параметров — в тегах `input` этой же формы.
``` {#codeblock_xvv_cfx_x3c .language-json}
{
"threeds2":{
"redirect":{
"url":"https://example.com/ACS",
"params":{
"creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
"threeDSSessionData":"240000549"
}
}
}
}
```
``` {#codeblock_yvv_cfx_x3c .language-xml}
3D Secure Processing
3D Secure Processing
```
### Формат уведомления о результате аутентификации {#section_cjg_rss_njb .section}
Для уведомлений со сведениями о результатах аутентификации используются форматы эмитентов, при этом в состав таких уведомлений должен включаться параметр `cres`, который должен передаваться далее в платформу со стороны веб-сервиса в запросах на продолжение платежа.
``` {#codeblock_rn5_hfm_njc}
**cres**=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554
```
``` {#codeblock_sn5_hfm_njc}
**cres**=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&threeDSSessionData=240000622
```
### Формат запроса на продолжение платежа {#section_gps_1fc_t3b .section}
Для продолжения проведения платежа, когда это актуально после аутентификации с вариантом challenge flow, каждый раз должен использоваться POST-запрос к конечной точке [/v2/payment/card/3ds\_result](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-result). В каждом таком запросе должны использоваться следующие объекты и параметры:
- `general` — объект, содержащий основные идентификационные сведения запроса:
- `project_id` — идентификатор используемого проекта;
- `payment_id` — идентификатор проводимого платежа;
- `signature` — подпись к данным запроса, составленная после указания целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md#)\).
- `cres` — сведения о результате аутентификации 3‑D Secure, полученные [в соответствующем уведомлении](ru_gate_payment_3ds.md#section_cjg_rss_njb).
Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, сведения о результате аутентификации от эмитента и подпись.
``` {#codeblock_tn5_hfm_njc .language-json}
{
"general": {
"project_id": 42,
"payment_id": "456789",
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
},
"cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
// Сведения о результате аутентификации
}
```
## Формат оповещений о результатах платежей {#ru_gate_payment_3ds_formats_callback}
Информация о результатах платежей, при проведении которых выполнялась аутентификация 3‑D Secure, передаётся от платёжной платформы к веб-сервису в оповещениях типового формата, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md#). При этом в объекте `mpi_result` таких оповещений дополнительно могут передаваться следующие параметры:
- `mpi_operation_id` — идентификатор операции на стороне 3DS‑сервера;
- `ds_operation_id` — идентификатор операции на стороне cервера каталогов международной платёжной системы;
- `acs_operation_id` — идентификатор операции на стороне сервера управления доступом эмитента;
- `mpi_timestamp` — дата и время аутентификации;
- `cardholder_info` — информация об аутентификации, которую рекомендуется отобразить пользователю при уведомлении о результате проведения платежа;
- `authentication_flow` — указатель использованного варианта аутентификации: `01` — frictionless flow, `02` — challenge flow.
В случаях, когда аутентификация не выполнялась в связи с применением одного из допустимых [исключений](ru_gate_payment_3ds.md#section_oks_mps_kdc), в объекте `operation` таких оповещений дополнительно может передаваться параметр `non_3ds_reason` со значением `tra, lve` \(для платежей с низким уровнем риска \(Transaction Risk Analysis\) или на незначительные суммы \(Low value\)\).
По умолчанию такие дополнительные параметры не включаются в состав итоговых оповещений. Однако их можно включить в используемую структуру через обращение к специалистам технической поддержки Ecommpay.
```language-json
{
"account":{
"number":"431422******0056",
"token":"f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
"type":"visa",
"card_holder":"JOHN SMITH",
"id":45678,
"expiry_month":"08",
"expiry_year":"2025"
},
"customer":{
"id":"customer_12",
"phone":"44991234567"
},
"payment":{
"date":"2019-01-11T13:02:42+0000",
"id":"456789",
"method":"card",
"status":"success",
"sum":{
"amount":400000,
"currency":"USD"
},
"type":"purchase",
"description":""
},
"project_id":42,
"operation":{
"id":969000002636,
"type":"sale",
"status":"success",
"date":"2019-01-11T13:02:42+0000",
"created_date":"2019-01-11T13:01:45+0000",
"request_id":"c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c",
"sum_initial":{
"amount":400000,
"currency":"USD"
},
"sum_converted":{
"amount":400000,
"currency":"USD"
},
"provider":{
"id":408,
"payment_id":"330157196",
"date":"2019-01-11T13:02:32+0000",
"auth_code":"",
"endpoint_id":"612266625"
},
"mpi_result":{
"mpi_operation_id":"",
// Идентификатор операции на стороне 3DS‑сервера
"ds_operation_id":"",
// Идентификатор операции на стороне сервера каталогов международной платёжной системы
"acs_operation_id":"",
// Идентификатор операции на стороне сервера управления доступом эмитента
"mpi_timestamp":"YYYYMMDDHHMM",
// Дата и время выполнения аутентификации
"cardholder_info":"Additional authentication is needed for this transaction",
// Информация об аутентификации, которую рекомендуется отобразить пользователю
"authentication_flow":"02"
// Информация о варианте аутентификации
},
"code":"0",
"message":"Success",
"eci":"07"
},
"signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}
```
