Checkout¶

Checkout — решение, которое позволяет встроить готовую платёжную форму на ваш веб-сайт.

Варианты реализации¶

Использование инвойса¶

Сценарий описан в данной статье (см. случай, когда оплата производится с платёжной формы XPAY).

Ниже приведены:

список возможных атрибутов для управления внешним видом и поведением платёжной формы;
пример встраивания Checkout для HTML/JS;

HTML и JS¶

В данной таблице содержится список атрибутов, которые можно использовать как для HTML, так и для JS.

data-* атрибут HTML	Свойство конфигурации JS	Описание	Обязательность	Возможные значения
data-invoice-id	invoiceID	Идентификатор инвойса	+	oVU2LzUCbQ
data-invoice-access-token	invoiceAccessToken	Ключ доступа к инвойсу	+	eyJhbGciOiJSUzI1N…
data-name	name	Наименование компании или сайта	-	Company name
data-description	description	Описание продукта или сервиса
data-email	email	email покупателя, будет предзаполнен на форме	-	example@mail.com
data-obscure-card-cvv	obscureCardCvv	Затенять карточный CVV-код	-	true/false
data-require-card-holder	requireCardHolder	Требовать от покупателя заполнять поле «card holder»	-	true/false
data-locale	locale	Настройка локализации платёжной формы	-	auto/ru/en
data-popup-mode	popupMode	Открывать Checkout в новой вкладке браузера	-	true/false
data-recurring	recurring	Признак рекуррентного платежа	-	true/false

HTML¶

В данной таблице содержится список атрибутов, которые можно использовать только для HTML.

data-* атрибут	Описание	Обязательность	Возможные значения
data-label	Текст кнопки открытия формы	-	Pay with XPAY

<form action="https://<your-server-side>" method="GET">
    <script src="https://checkout.xpay.by/checkout.js" class="xPay-checkout"
            data-invoice-id="string"
            data-invoice-access-token="string"
            data-name="Company name"
            data-description="Some product"
            data-label="Pay with XPAY">
    </script>
</form>

С помощью form можно задать url для callback’a об успешном проведении платежа.

JS¶

В данной таблице содержится список атрибутов, которые можно использовать только для JS.

Свойство конфигурации	Описание	Обязательность	Возможные значения
opened	callback’a об открытии окна Checkout	-	function
closed	callback о закрытии окна Checkout	-	function
finished	callback об успешном проведении платежа	-	function

const checkout = xPayCheckout.configure({
    invoiceID: 'string',
    invoiceAccessToken: 'string',
    name: 'Company name',
    description: 'Some product',
    opened: function () {
        console.log('Checkout opened');
    },
    closed: function () {
        console.log('Checkout closed');
    },
    finished: function () {
        console.log('Payment successful finished');
    }
});

document.getElementById('customButton').addEventListener('click', function () {
    checkout.open();
});

window.addEventListener('popstate', function () {
    checkout.close();
});

Использование шаблона инвойса¶

Шаблон инвойса позволяет совершать произвольное количество платежей с идентичными параметрами без необходимости создавать счёт для каждого из них.

Сценарий использования Checkout в данном случае аналогичен тому, что описан для создания инвойса. Однако, вместо метода createInvoice используется createInvoiceTemplate.

Список возможных атрибутов немного отличается от приведённого в данном разделе. Различия описаны таблицами ниже. В остальном наборы атрибутов идентичны.

При оплате шаблона инвойса покупатель может самостоятельно указать сумму. Возможность указания произвольной суммы задается при вызове createInvoiceTemplate: см. price → costType для templateType:InvoiceTemplateSingleLine. Сумму также допускается предзаполнить (без возможности ее редактирования на форме оплаты).

HTML¶

Данная таблица отражает различия в использовании атрибутов для HTML.

data-* атрибут (инвойс)	data-* атрибут (шаблон инвойса)
data-invoice-id	data-invoice-template-id
data-invoice-access-token	data-invoice-template-access-token

JS¶

Данная таблица отражает различия в использовании атрибутов для JS.

data-* атрибут (инвойс)	data-* атрибут (шаблон инвойса)
invoiceID	invoiceTemplateID
invoiceAccessToken	invoiceTemplateAccessToken

HTML и JS¶

Для того чтобы предзаполнить сумму оплаты для покупателя, необходимо передать нижеописанный параметр.

data-* атрибут HTML	Свойство конфигурации JS	Описание	Тип
data-amount	amount	Сумма к оплате в минорных денежных единицах, например в копейках (в случае указания белорусских рублей в качестве валюты)	integer

Рекуррентный платеж¶

Описание рекуррентных платежей и сценарии их использования отражены в данной статье.

Список возможных атрибутов при создании подобного платежа немного отличается от приведённого в данном разделе: требуется передать идентификатор плательщика и ключ доступа к операциям с использованием принадлежащего ему источника денежных средств. Различия описаны таблицами ниже. В остальном наборы атрибутов идентичны.

HTML¶

Данная таблица отражает различия в использовании атрибутов для HTML.

data-* атрибут (инвойс)	data-* атрибут (шаблон инвойса)
data-invoice-id	data-customer-id
data-invoice-access-token	data-customer-access-token

JS¶

Данная таблица отражает различия в использовании атрибутов для JS.

data-* атрибут (инвойс)	data-* атрибут (шаблон инвойса)
invoiceID	customerID
invoiceAccessToken	customerAccessToken

HTML и JS¶

Для того чтобы обозначить платеж в качестве родительского, необходимо передать нижеописанный параметр.

data-* атрибут HTML	Свойство конфигурации JS	Описание	Возможные значения	Значение по умолчанию
recurring	data-recurring	Признак выполнения рекуррентного платежа	true/false	false

Платеж с удержанием (холдированием) денежных средств¶

Вышеописанные варианты реализации подразумевают одноэтапный или двухэтапный процесс проведения платежа при оплате инвойса/шаблона инвойса.

Одноэтапное проведение говорит о немедленном списании денежных средств с покупателя. Двухэтапное — об их временном удержании (холдировании) до момента подтверждения покупки мерчантом: подробности см. в описании раздела «Подтвердить или отменить оплату заказа» данного руководства пользователя.

Для проведения платежа с удержанием средств необходимо:

передать соответствующий атрибут со значением true;
выбрать политику, которая будет применена по истечении срока удержания денежных средств:
- cancel - удержанные денежные средства вновь станут доступны покупателю: не поступят в пользу мерчанта.
- capture - денежные средства поступят в пользу мерчанта.

В остальном список возможных атрибутов не отличается от приведённых в разделе «Использование инвойса»/«Использование шаблона инвойса»/«Рекуррентный платеж» (в зависимости от выбранного вида оплаты).

HTML и JS¶

Для того чтобы захолдировать денежные средства покупателя, необходимо передать нижеописанные атрибуты.

data-* атрибут HTML	Свойство конфигурации JS	Описание	Возможные значения
data-payment-flow-hold	paymentFlowHold	Признак холдирования средств	true/false
data-hold-expiration	holdExpiration	Политика управления захолдированными средствами	cancel/capture

Ограничения¶

Checkout позволяет получить callback только об успешном завершении платежа: callback о других состояниях платежа не поддерживается.
В случае неуспешной попытки проведения платежа покупателю будет предложено вновь совершить оплату. Количество попыток не ограничено в рамках действия времени жизни инвойса/шаблона инвойса.

Частые ошибки¶

Блокировка функции открытия Сheckout¶

Не вызывайте функцию открытия Сheckout в callback. Большинство мобильных браузеров блокируют подобное поведение. Открытие нового окна должно происходить в результате действия пользователя.

// Будет работать:
document.getElementById("button").addEventListener("click", function() {
    checkout.open();
});

// Не будет работать:
document.getElementById("button").addEventListener("click", function() {
    someFunction().then(function() {
        checkout.open();
    });
});

«xPayCheckout is not defined»¶

При некорректном встраивании Checkout в код страницы оплаты может возникать ошибка «xPayCheckout is not defined». Она связана с тем, что вы вызываете функцию xPayCheckout.configure() до полной инициализации DOM. Используйте подходящие вам практики, для того чтобы обеспечить вызов платежной формы после полной инициализации модели документа.

Частный случай решения этой задачи с использованием jquery, указывающий направление ее решения, может выглядеть так:

<!DOCTYPE html>
<html>
<head>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"   integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="   crossorigin="anonymous"></script>
    <script type="text/javascript" src="https://checkout.xpay.by/checkout.js"></script>
</head>
<body>
    <script>
    $(function() {
        $('#xPay-checkout').on('click', function(e) {
            e.preventDefault();
            const checkout = initCheckout('{INVOICE_ID}', '{INVOICE_ACCESS_TOKEN}');
            checkout.open();
        });

        function initCheckout(invoiceID, invoiceAccessToken) {
            return xPayCheckout.configure({
                invoiceID: invoiceID,
                invoiceAccessToken: invoiceAccessToken,
                name: 'Product name',
                description: 'Product description',
                email: 'example@example.com',
                finished: function() {
                    console.log('Payment successful finished');
                },
                opened: function() {
                    console.log('Checkout opened');
                },
                closed: function() {
                    console.log('Checkout closed');
                }
            });
        }
    });
    </script>
    <button id="xPay-checkout">Pay with xPay</button>
</body>
</html>