Перенаправление на страницу оплаты при помощи JS SDK¶
Интеграция через редирект реализована при помощи Merchant JS SDK для платежного сервиса XPAY.
SDK позволяет Мерчантам добавлять на свой сайт онлайн магазина кнопку для оплаты, которая перенаправляет покупателя на страницу оплаты XPAY для завершения транзакции. После завершения оплаты покупатель возвращается в онлайн магазин Мерчанта по указанному URL-адресу возврата для завершения оплаты и получения чека платёжной операции.
Бизнес процесс¶
- Покупатель наполняет корзину покупок в интернет-магазине Мерчанта и нажимает на кнопку Купить.
- Сервер интернет-магазина конфигурирует способ оплаты XPAY.
- Сервер интернет-магазина формирует заказ и отображает страницу выбора способа оплаты.
- Покупатель выбирает способ оплаты XPAY и нажимает кнопку Оплатить.
- Сервер интернет-магазина перенаправляет на платёжную страницу XPAY с параметрами заказа.
- Приложение платёжного метода XPAY проводит оплату.
- Приложение платёжного метода XPAY отображает результат платёжной операции или перенаправляет покупателя назад в интернет магазин Мерчанта с результатом платежной операции.
Состав SDK¶
Конфигуратор платежной сессии¶
SDK предоставляет инициацию сеанса оплаты заказа с API ключом Мерчанта
Пользовательский интерфейс¶
2 варианта реализации:
- SDK предоставляет кнопку по умолчанию, которую Мерчант может для удобства разместить в определенном элементе DOM.
- Также продавец может использовать собственную кнопку/ссылку и вызывать обработчик при нажатии.
Обработчик перенаправления¶
SDK предоставляет обработчик, который продавец вызывает при нажатии кнопки Оплатить. Обработчик отвечает за перенаправление покупателяна страницу оплаты XPay.
Сценарий интеграции¶
1) Скачать SDK¶
2) Подключить SDK¶
<script src="merchant-sdk.min.js"></script>
3) Инициализация¶
Серверная часть продавца создает сеанс оплаты заказа.
При инициализации передается один объект конфигурации.
Он должен быть действительным как для перенаправления, так и для будущих запросов на оплату.
Пример инициализации
XPAY.init(config);
Параметры объекта конфигурации:
| № | Параметр | Тип | Обязательность | Описание | Значение |
|---|---|---|---|---|---|
| 1 | merchantId | строка | Да | Идентификатор продавца, выданный XPAY (используется для перенаправления/API и маршрутизации). | 5813dadb-1f5f-4e9a-85cd-85c5ae1eae4a |
| 2 | environment | ‘sandbox’ , ‘live’ | Да | Среда (определяет базовый URL платежного сервиса). | live |
| 3 | successReturnUrl | строка | - | URL для перенаправления покупателя после успешной оплаты. | https://myshop.com/success |
| 4 | cancelReturnUrl | строка | - | URL для перенаправления покупателя в случае отмены оплаты. | https://myshop.com/cancel |
| 5 | locale | ‘en’ , ‘ru’ | - | Предпочтительный язык () для страницы оплаты. | ru |
| 6 | paymentServiceBaseUrl | строка | - | Переопределение базового URL платежного сервиса. | |
| 7 | createCheckoutSessionUrl | строка | - | Требуется только для Вариант 2 создания кнопки оплаты! URL-адрес серверной конечной точки продавца, которая создает сеанс оплаты заказа и возвращает checkoutUrl (и, при необходимости, sessionId, expiresAt). При вызове обработчика с данными о транзакции (Вариант 2) SDK отправляет на эту конечную точку POST-запрос с указанием суммы, валюты, идентификатора заказа, описания, метаданных и URL-адресов возврата на уровне инициализации. Серверная часть вызывает инициализацию оплаты заказа с ключом API продавца и возвращает URL-адрес оплаты заказа. |
Пример объекта конфигурации:
{
"merchantId": "MERCHANT_ID",
"environment": "sandbox",
"locale": "ru",
"successReturnUrl": "https:/myshop.com/success",
"cancelReturnUrl": "https:/myshop.com/cancel"
}
4) Создать кнопку оплаты¶
Вариант 1:¶
Создайте кнопку
XPAY.renderButton('#payment-button', OrderData);
В данном случае обработчик SDK получает URL-адрес оплаты заказа и перенаправляет на него покупателя.
Вариант 2:¶
Используйте свою кнопку с redirectToCheckout
document.querySelector('#my-pay-btn').addEventListener('click', function () { XPAY.redirectToCheckout(OrderData); });
Дизайн кнопки способа оплаты XPAY в Figma XPAY Buttons
Во данном случае обработчик SDK вызывает запрос createCheckoutSessionUrl с деталями транзакции, а затем перенаправляет покупателя на возвращенный URL-адрес.
Контекст платежа (OrderData)¶
Для каждого действия «Оплатить» продавец должен предоставить данные о транзакции при вызове обработчика, чтобы один экземпляр SDK мог обрабатывать несколько заказов.
Параметры объекта OrderData:
| № | Параметр | Тип | Обязательность | Описание |
|---|---|---|---|---|
| 1 | amount | число | ДА | Сумма платежа. |
| 2 | currency | строка | ДА | ISO 4217 (например, BYN, USD). |
| 3 | orderId | строка | НЕТ | Идентификатор заказа/ссылки на товар. |
| 4 | description | строка | НЕТ | Краткое описание для плательщика. |
| 5 | metadata | объект | НЕТ | Метаданные «ключ-значение» (например, для вебхуков). |
| 6 | idempotencyKey | строка | НЕТ | Ключ идемпотентности (передается на серверную часть; серверная часть отправляет Idempotency-Key в XPay Checkout API). |
| 7 | successReturnUrl | строка | НЕТ | Переопределить начальное значение для этой транзакции (этого требует Checkout API). |
| 8 | cancelReturnUrl | строка | НЕТ | Переопределить начальное значение для этой транзакции (этого требует Checkout API). |
В случае Варианта 2:
Когда SDK вызывает createCheckoutSessionUrl, он отправляет объект OrderData, а также merchantId и URL-адреса возврата (из настроек инициализации или переопределений для каждого вызова). Затем серверная часть вызывает инициализацию сеанса оплаты заказа с теми же параметрами: merchantId, сумма, валюта, URL-адрес успешного возврата, URL-адрес отмены возврата, идентификатор заказа, описание, метаданные, idempotencyKey (заголовок Idempotency-Key). Т.е. параметры объекта конфигурации необходимо указать при инициализации или для каждой транзакции при использовании варианта 2. Ответ серверной части на запрос SDK должен включать checkoutUrl, а также могут быть включены sessionId и expiresAt.
Пример OrderData:
{
"orderId": "ORDER_123",
"amount": "100.25",
"currency": "BYN",
"description": "Order #12345"
}
Параметры безопасности¶
- Ключ доступа Мерчанта к API XPAY хранится только на сервере продавца.
- В рабочей среде обязательно использовать HTTPS
- В конфигурации SDK нет данных о картах или долгоживущих секретных данных, только идентификатор продавца, среда и URL-адреса возврата.
- Перенаправление должно запускаться по действию пользователя, чтобы избежать блокировки всплывающих окон и обеспечить соответствие требованиям безопасности браузера и API запроса платежа.
- CORS: если SDK вызывает API XPAY из браузера, эти конечные точки должны разрешать доступ для источника продавца в рамках CORS.