Перенаправление на страницу оплаты при помощи JS SDK¶
Способ интеграции при помощи библиотеки Merchant JS SDK платежного сервиса XPAY.
JS SDK позволяет Мерчантам добавлять на свой сайт интернет-магазина кнопку для оплаты, которая перенаправляет покупателя на страницу оплаты XPAY.
Бизнес процесс¶
- Покупатель наполняет корзину покупок в интернет-магазине Мерчанта и нажимает на кнопку “Купить”.
- Бэкенд или сервер интернет-магазина Мерчанта конфигурирует способ оплаты XPAY.
- Бэкенд или сервер интернет-магазина Мерчанта формирует заказ и отображает страницу выбора способа оплаты.
- Покупатель выбирает способ оплаты XPAY и нажимает кнопку “Оплатить”.
- Веб интерфейс интернет-магазина Мерчанта перенаправляет Покупателя на страницу оплаты XPAY с параметрами заказа.
- Платежный сервис XPAY отображает платежную формы Покупателю и проводит оплату.
- После завершение оплаты платежный сервис XPAY отображает результат платёжной транзакции и перенаправляет Покупателя на страницу интернет-магазина Мерчанта, полученную из данных сессии.
Состав SDK¶
- Конфигуратор платежной сессии
- Пользовательский интерфейс
- Обработчик перенаправления
Конфигуратор платежной сессии инициализирует сеанс оплаты заказа с API ключом Мерчанта
Пользовательский интерфейс имеет 2 варианта реализации:
- SDK предоставляет кнопку по умолчанию, которую Мерчант может для удобства разместить в определенном элементе DOM.
- Также Мерчант может использовать собственную кнопку/ссылку и вызывать обработчик при нажатии.
Обработчик перенаправления вызывается при нажатии на кнопку “Оплатить”. Обработчик отвечает за перенаправление покупателя на страницу оплаты XPAY.
Сценарий интеграции¶
1) Скачать SDK¶
2) Подключить SDK¶
<script src="merchant-sdk.min.js"></script>
3) Инициализация¶
Бэкенд или сервер Мерчанта создает сессию оформления заказа.
При инициализации передается объект конфигурации config.
Пример инициализации:
XPAY.init(config);
Параметры объекта конфигурации 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 | строка | НЕТ | URL-адрес метода создания сессии оформления заказа (см. Замечание ниже). |
Замечание:
- createCheckoutSessionUrl требуется только для Вариант 2 пользовательского интерфейса!\ SDK отправляет на этот endpoint POST-запрос с деталями транзауции и URL-адресов возврата. В ответ получает URL-адрес оплаты заказа checkoutUrl, а также sessionId, expiresAt.
Пример объекта конфигурации для Варианта 1 пользовательского интерфейса:
{
"merchantId": "MERCHANT_ID",
"environment": "sandbox",
"locale": "ru",
"successReturnUrl": "https:/myshop.com/success",
"cancelReturnUrl": "https:/myshop.com/cancel"
}
4) Создать кнопку оплаты¶
Вариант 1 пользовательского интерфейса¶
Создайте брендированную кнопку XPAY
XPAY.renderButton('#payment-button', OrderData, ButtonOptions);
, где:
- OrderData - Контекст платежа или данные о транзакции
- ButtonOption - Опции брендирования кнопки
При нажатии на кнопку обработчик перенаправления получает URL-адрес страницы оплаты XPAY и перенаправляет на него покупателя.
Параметры контекста платежа OrderData:
| № | Параметр | Тип | Обязательность | Описание |
|---|---|---|---|---|
| 1 | amount | число | ДА | Сумма платежа. |
| 2 | currency | строка | ДА | ISO 4217 (например, BYN, USD). |
| 3 | orderId | строка | НЕТ | Идентификатор заказа/ссылки на товар. |
| 4 | description | строка | НЕТ | Краткое описание для Покупателя. |
| 5 | metadata | объект | НЕТ | Метаданные «ключ-значение» (например, для вебхуков). |
| 6 | idempotencyKey | строка | НЕТ | Ключ идемпотентности (передается на серверную часть; серверная часть отправляет Idempotency-Key в XPay Checkout API). |
| 7 | successReturnUrl | строка | НЕТ | Переопределить начальное значение для этой транзакции. |
| 8 | cancelReturnUrl | строка | НЕТ | Переопределить начальное значение для этой транзакции. |
Пример OrderData:
{
"orderId": "ORDER_123",
"amount": 100.25,
"currency": "BYN",
"description": "Order #12345"
}
```
Параметры брендирования кнопки **ButtonOptions**:
|№| Параметр| Тип| Обязательность | По умолчанию | Описание|
|-|---------|--------|--------|-----------|-----------------------------------------------|
|1| buttonText| строка| НЕТ| "Оплатить" | Текст кнопки.|
|2| theme| 'white', 'black'| НЕТ| "black" | Цветовая тема кнопки.|
|3| displayLogo| true, false| НЕТ| true | Отображать логотип в кнопке.|
|4| borderRadius| число| НЕТ| 12 | Закругление кнопки.|
|5| height| число| НЕТ| auto | Высота кнопки в px.|
|6| width| число/строка| НЕТ| auto | Ширина кнопки в px или %.|
Пример ButtonOptions:
```json
{
"theme": "white",
"displayLogo": true,
"buttonText": "100.25 BYN",
"borderRadius": 0
}
```
#### Вариант 2 пользовательского интерфейса
Используйте свою кнопку с redirectToCheckout
```js
document.querySelector('#my-pay-btn').addEventListener('click', function () { XPAY.redirectToCheckout(OrderData); });
При нажатии на кнопку обработчик перенаправления вызывает POST запрос, указанный в параметре createCheckoutSessionUrl объекта инициализации с деталями транзакции и адресами возврата в интернет-магазин, а затем перенаправляет покупателя на возвращенный URL-адрес checkoutUrl.
На своей кнопке вы можете использовать наш фирменный логотип XPAY в форматах PNG и SVG.
Возможный дизайн кнопки способа оплаты XPAY можно посмотреть в Figma XPAY Buttons
5) Подготовить страницы возврата Покупателя в магазин после оплаты¶
Подготовьте страницы магазина, куда Покупатель вернётся после оплаты.
После оплаты Покупатель перенаправляется на successReturnUrl или cancelReturnUrl , которые были указаны Мерчантом при создании сессии оформления заказа.
Параметры безопасности¶
- Ключ доступа Мерчанта к API XPAY хранится только на сервере Мерчанта.
- В рабочей среде обязательно использовать HTTPS
- В конфигурации SDK нет данных о картах или долгоживущих секретных данных, только идентификатор Мерчанта, среда и URL-адреса возврата.
- Перенаправление должно запускаться по действию пользователя, чтобы избежать блокировки всплывающих окон и обеспечить соответствие требованиям безопасности браузера и API запроса платежа.
- CORS: если SDK вызывает API XPAY из браузера, эти конечные точки должны разрешать доступ для источника Мерчанта в рамках CORS.