Получение платежей с использованием 3D Secure
Оплаты с использованием 3D Secure реализуются в три этапа: инициация, проверка и завершение. В запросе на инициацию Odero API предоставляется URL обратного вызова, по которому может быть передан статус 3D Secure; с использованием этого URL участник бизнеса в своих рабочих процессах указывает ID оплаты и отправляет запрос на завершение оплаты, обеспечивая завершение процесса от начала до конца.
Начало 3D Secure платежа
URL
Информация о конечной точке и методе HTTP, используемых для запуска 3D Secure платежа, предоставлена ниже:
| HTTP Method | URL |
|---|---|
POST |
/payment/v1/card-payments/3ds-init |
Параметры запроса на начало оплаты
В отличие от других платежей, при реализации оплат с использованием 3D Secure обязательно отправление параметра callbackUrl. В этом контексте обязательными параметрами для начала 3D Secure оплаты являются следующие:
| Название параметра | Тип | Обязательный | Описание |
|---|---|---|---|
conversationId |
string |
Нет | Значение "boomerang", которое можно отправить в запросе и принять в ответе. Используется для связывания различных запросов между собой. Обычно используется номер заказа, связанный с платежами бизнес-участника. |
price |
decimal |
Да | Общая сумма платежа. Должна быть равна сумме продуктов/услуг в корзине. |
paidPrice |
decimal |
Да | Общая сумма, которую клиент должен заплатить, рассчитывается с учетом комиссий и скидок. В случае частичного или полного платежа из кошелька, сумма, взимаемая с кошелька, также включена в эту сумму. |
walletPrice |
decimal |
Нет | Сумма, удерживаемая из кошелька покупателя, указанная в параметре buyerId. Обязательно при частичном или полном удержании средств из кошелька. В случае полного удержания средств с карты или отсутствия buyerId может быть отправлена как 0. (По умолчанию: 0) |
installment |
integer |
Да | Количество месячных выплат по платежу. Может быть отправлено как 1 для единовременного платежа. Возможные значения: 1, 2, 3, 6, 9 и 12. |
buyerId |
long |
Нет | ID покупателя, связанный с платежом. Этот идентификатор принадлежит системам Odero, а не ID значению в системах участника бизнеса. |
currency |
Currency |
Да | см.: Валюты Валюта, в которой принимается платеж |
paymentGroup |
PaymentGroup |
Да | см.: Группы Платежей |
callbackUrl |
string |
Да* | Адрес, который будет использован для доставки результата от банка в систему торговца при проведении платежа с использованием 3D Secure (см. 3D Secure Получение Платежа) |
card |
Card |
Нет | (см. Информация о Карте) Информация о карте, для которой будет проведено удержание. Не обязательно для полного удержания из кошелька (т.е. когда paidPrice равен walletPrice) |
posAlias |
string |
Нет | Используется для операций TOKENGATE. Если заполнено, платеж будет проведен через этот POS. см.: Операции Шлюза |
items |
PaymentItem[] |
Да | (см.: Информация о Платеже) Информация о разделении платежа. Должно быть отправлено как минимум одно разделение, и сумма всех отправленных разделений должна быть равна значению price. |
*: В обычных условиях это поле необязательное, но оно выделено как обязательное для платежей, совершаемых через страницу Общего платежа
Параметры ответа
Параметры, возвращаемые в результате процесса оплаты с использованием 3D Secure, подчиняются правилам, указанным в разделе Форматы Возврата на основной странице документации API. При отсутствии систематической или структурной ошибки параметры возвращаемые в data, следующие:
| Название параметра | Тип | Обязательный | Описание |
|---|---|---|---|
htmlContent |
string |
Да | Структура HTML-кода формы 3D Secure, которая будет представлена пользователю. Это значение отправляется в кодировке Base64 и должно быть декодировано системой торговца перед отображением |
Проверка 3D Secure
Процесс 3D Secure-оплаты, начинающийся с запроса на инициирование платежа, отправленного торговцем, продолжается с проверки пользователя. Для этого HTML-структура, содержащаяся в ответе на запрос на инициирование, должна быть декодирована и показана пользователю.
После того как пользователь вводит полученный им код подтверждения, результат проверки передается в API Odero соответствующим банком. API Odero отправляет запрос на обратный адрес callbackUrl, предоставленный торговцем при запросе на проведение оплаты, сохраняя при этом полученный результат вместе с некоторой информацией о платеже.
Передаваемые параметры в Callback URL
Следующие параметры передаются в виде переменных формы с использованием HTTP POST метода. Параметры, содержащиеся в запросе, который будет отправлен Odero на callbackUrl после подтверждения, будут следующими:
| Название параметра | Тип | Обязательный | Описание |
|---|---|---|---|
status |
string |
Да | Значение, выражающее статус проверки 3D Secure. Если проверка прошла успешно, будет получено значение SUCCESS, в противном случае — FAILURE |
conversationId |
string |
Нет | Значение параметра conversationId, отправленного в запросе на запуск оплаты |
paymentId |
long |
Нет | Отправляется в случае успешной проверки. Это идентификатор, созданный API Odero, связанный с платежом |
Завершение 3D Secure Платежа
После отправки торговцу результата Odero через запрос на callbackUrl для успешных платежей, бизнес-партнер должен завершить процесс, отправив запрос на завершение к API Odero. Этот запрос должен быть отправлен в течение времени ожидания (В зависимости от банка издателя карты). Если запрос на завершение не отправлен или не будет подтвержден после успешного вызова callbackUrl, транзакция не будет завершена. Если это не произойдет или если невозможно перейти на callbackUrl после подтверждения, транзакция останется в ожидании и будет отображаться желтым цветом на панели торговца.
URL
Информация о конечной точке и методе HTTP, используемых для завершения 3D Secure платежа, предоставлена ниже:
| HTTP Metod | URL |
|---|---|
POST |
/payment/v1/card-payments/3ds-complete |
Параметры ответа на завершение платежа:
Параметры запроса на завершение для платежей, прошедших этап проверки, следующие:
| Название параметра | Тип | Обязательный | Описание |
|---|---|---|---|
paymentId |
long |
Да | ID платежа, созданного API Odero и переданного в callbackUrl в связи с платежом. |
partnerId | long | Нет | Интеграционное поле partnerId. |
walletId | long | Нет | Интеграционное поле walletId. |
checkoutToken | string | Нет | Интеграционное поле checkoutToken. |
conversationData | string | Нет | Интеграционное поле conversationData. |
walletAccessToken | string | Нет | Интеграционное поле walletAccessToken. |
softOtp | string | Нет | Интеграционное поле softOtp. |
groupMemberApiKey | string | Нет | Интеграционное поле groupMemberApiKey. |
Параметры Возврата Завершения Платежа
Ответ на запрос о завершении платежей, совершенных с использованием 3D Secure, аналогичен стандартному платежу и содержит детали, связанные с платежом. Для формата ответа и параметров, которые он содержит, обратитесь к: Параметры Приема Платежа - Ответ
Серверный API проверки 3D Secure
Интеграции, выполняющие проверку через API, используют следующий endpoint.
URL
| HTTP Method | URL |
|---|---|
POST | /payment/v1/card-payments/3ds-verify |
Параметры запроса
| Parameter | Type | Required / Available | Description |
|---|---|---|---|
pfCallbackToken | string | Да | Callback-токен длиной 36 символов. |
status | ThreeDSVerifyStatus | Да | Статус проверки 3D Secure. |
callbackParams | Map | Да | Карта ключ/значение callback банка. |
Параметры ответа
| Parameter | Type | Required / Available | Description |
|---|---|---|---|
callbackUrl | string | Нет | Интеграционное поле callbackUrl. |
status | ThreeDSVerifyStatus | Нет | Интеграционное поле status. |
conversationData | string | Нет | Интеграционное поле conversationData. |
paymentId | long | Нет | Интеграционное поле paymentId. |
conversationId | string | Нет | Интеграционное поле conversationId. |
mdStatus | integer | Нет | Интеграционное поле mdStatus. |