Перенаправление на страницу оплаты через прямой вызов API¶

Способ интеграции, при котором бэкенд магазина самостоятельно напрямую вызывает методы API платежного сервиса XPAY.

Размещение API платежного сервиса XPAY: https://pay-service.xpay.by/api/v1/

Бизнес процесс¶

При использовании данного способа интеграции процесс оплаты выглядит следующим образом:

Покупатель наполняет корзину покупок в онлайн магазине Мерчанта и нажимает на кнопку “Купить”.
Бэкенд или сервер интернет-магазина Мерчанта формирует заказ и отображает страницу выбора способа оплаты.
Покупатель выбирает способ оплаты XPAY и нажимает кнопку “Оплатить”.
Бэкенд или сервер интернет-магазина Мерчанта создаёт сессию оформления заказа через вызов API и получает URL-адрес перенаправления. URL-адрес перенаправления содержит подписанный токен.
Веб интерфейс интернет-магазина Мерчанта перенаправляет Покупателя на страницу оплаты XPAY по полученному URL-адресу перенаправления.
Платежный сервис XPAY преобразует токен, полученный из URL-адреса, чтобы получить данные сессии
Платежный сервис XPAY отображает платежную формы Покупателю и проводит оплату.
После завершение оплаты платежный сервис XPAY отображает результат платёжной транзакции и возвращает Покупателя на страницу интернет-магазина Мерчанта, полученную из данных сессии.

Сценарий интеграции¶

1) Создать сеанс оформления заказа¶

Для создания сессии из бэкенда или с сервера Мерчанта отправляется запрос POST /v1/checkout/sessions с указанием суммы, валюты, URL возврата, X-API-Key и деталями корзины заказа.

Запрос

Заголовок запроса:

Параметр	Обязательный	Описание	Заполнение
Content-Type	ДА	Тип содержимого	application/json
X-API-Key	ДА	Аутентификация. Ключ API Мерчанта. Выдан XPAY при регистрации Мерчанта, хранится в конфигурации Мерчанта. Мерчант никогда не отправляет его из браузера, только между серверами.	Взять из конфигурации Мерчанта. “sdrtywe54tgfe3gw4543f”
Idempotency-Key	НЕТ	Дополнительный ключ для обеспечения идемпотентности. Чтобы избежать повторной оплаты заказа	Заполнить уникальным идентификатором заказа

Тело запроса:

json атрибут	Обязательный	Описание	Заполнение
merchantId	ДА	Ваш идентификатор Мерчанта, выданный XPAY при регистрации Мерчанта	Взять из конфигурации Мерчанта. “f436c940-e86d-4ea7-89c0-e72552419220”
amount	ДА	Сумма (минимум 0,01)	99.99
currency	ДА	ISO 4217 (например, BYN, USD, EUR)	“BYN”
successReturnUrl	ДА	Куда отправить клиента после оплаты	“https://golden-shop.by/checkout/order-received/206/?key=wc_order_Kzo6qw9G1qdlw“
cancelReturnUrl	ДА	Куда отправить клиента после отмены бронирования	“https://golden-shop.by/checkout/“
orderId	НЕТ	Дополнительная ссылка на заказ (максимум 255 символов)	206
merchantName	НЕТ	Наименование магазина Мерчанта (максимум 200 символов)	“Золотая груша”
description	НЕТ	Дополнительное описание (максимум 500 символов)	“Заказ физлица (3 товарных позиции, 12 единиц товара)”
metadata	НЕТ	Не обязательный дополнительный блок данных. Может передавать детали о корзине заказа.	см. пример заполнения ниже

Пример заполнения атрибута metadata:

    {
            "cartItems": [
                {
                    "quantity": 4,
                    "price": 15.96,
                    "name": "Sticker"
                },
                {
                    "quantity": 1,
                    "price": 5.6,
                    "name": "Pencil"
                }
            ]
        }

Пример заполнения тела запроса:

{ 
    "merchantId": "f436c940-e86d-4ea7-89c0-e72552419220",
    "amount": 15.96,
    "currency": "BYN",
    "successReturnUrl": "https://golden-shop.by/checkout/order-received/206/?key=wc_order_Kzo6qw9G1qdlw",
    "cancelReturnUrl": "https://golden-shop.by/checkout/",
    "orderId": "206",
    "merchantName": "Золотая груша",
    "metadata": { 
    "cartItems": [ 
        { 
            "quantity": 4,
            "price": 15.96,
            "name": "Sticker" 
        } 
                 ] 
                }
}

Ответ

Ответ 201 содержит:

checkoutUrl (с подписанным токеном), чтобы перенаправить Покупателя на платёжную страницу XPAY.
sessionId - Идентификатор сессия оформления заказа.
expiresAt - Таймаут сессия оформление заказа.

Пример ответа 201:

{ 
    "checkoutUrl": "http://web-ui.pay.local/checkout?token=Y3Nf...",
    "sessionId": "cs_f58119275369",
    "expiresAt": "2026-02-18T21:03:00Z"
}

Сессия оформления заказа в платёжном сервисе XPAY создана.

2) Перенаправить Покупателя на платежный сервис для оплаты¶

Перенаправьте Покупателя на страницу оформления заказа по checkoutUrl (например, с помощью HTTP 302 или ссылки/кнопки).

Токен в checkoutUrl подписан, не изменяйте его.

3) Подготовить страницы возврата Покупателя в магазин после оплаты¶

Подготовьте страницы магазина, куда Покупатель вернётся после оплаты.

После оплаты Покупатель перенаправляется на successReturnUrl или cancelReturnUrl , которые были указаны Мерчантом при создании сессии оформления заказа.