Checkout: Довідник¶

Перенаправлення клієнтів до Checkout¶

Ви можете використовувати як посилання на оплату (як стандартну HTML-форму), так і платіжний віджет (JS) для того, щоб зібрати та передати деталі платежу та дані клієнта у Checkout. Докладніше про методи інтеграції читайте тут.

Коли клієнт вибирає оплату онлайн, ваш сайт повинен надіслати дані HTML-форми на https://gate.cascad.com/hpp/.

HTML-форма повинна містити обов'язкові приховані поля, перелічені в опціях налаштування.

Ви також можете використовувати безпечніший спосіб перенаправлення користувача — з попередньо створеним Payment Invoice ID (ID інвойсу платежу). Детальний опис у розділі Безпечне перенаправлення.

Безпечне перенаправлення¶

Використовуйте цей спосіб, щоб бути впевненими, що деталі платежу безпечно передаються між вашим сервером та CASCAD.

Процес перенаправлення наступний:

1. Ваш веб-сервер надсилає стандартний POST запит із параметрами платежу, використовуючи приватний API.
2. Сервер CASCAD створює інвойс (Payment Invoice) і повертає стандартну HTTP(S) відповідь.
3. Ваш веб-сервер отримує з відповіді значення ID інвойсу.
4. Формується посилання для перенаправлення виду:

https://gate.cascad.com/hpp/?cpi=<PAYMENT_INVOICE_ID>

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    cpi: "<PAYMENT_INVOICE_ID>",
});
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

Можливі налаштування¶

Те, який обраний метод інтеграції, визначає, які ви задаєте параметри Checkout.

Основні параметри¶

Усі нижченаведені параметри обов'язкові*:

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>

Додаткові параметри¶

Додаткові значення потрібні для більш гнучкого налаштування Checkout і додають більше інформації в інвойс.

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    reference_id: "<your_unique_reference_id>",
    description: "Some goods",
    expires: 1602414000
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="expires" value="1602414000" />
    <input type="submit" value="Pay" />
</form>

Дані клієнта¶

Об'єкт customer містить додаткову інформацію про клієнта, який здійснює платіж. Зокрема email — e-mail, який можна використовувати для надсилання повідомлень про успішний або відхилений платіж (якщо ви використовуєте цей канал для комунікації з користувачами).

Налаштуйте прийом даних за допомогою таких додаткових параметрів:

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    customer: {
        reference_id: "cus_1234567",
        email: "somename@domain.com",
        name: "John Wick",
        metadata: {
            key1: "value1",
            key2: "value2"
        }
    }
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="customer[reference_id]" value="cus_1234567" />
    <input type="hidden" name="customer[email]" value="somename@domain.com" />
    <input type="hidden" name="customer[name]" value="John Wick" />
    <input type="hidden" name="customer[metadata][key1]" value="value1" />
    <input type="hidden" name="customer[metadata][key1]" value="value2" />
    <input type="submit" value="Pay" />
</form>

Автопроцесинг¶

Поля service і service_fields використовуються, щоб відправити клієнта відразу на заздалегідь визначений порт платіжного сервісу. Наприклад: service: paypal_UAH_hpp.

Якщо у сервісу (service) є обов'язкові поля, ви їх вказуєте у service_fields.

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    service: "paypal_UAH_hpp"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="service" value="paypal_UAH_hpp" />
    <input type="submit" value="Pay" />
</form>

URL для повернення¶

Введіть URL для повернення (return_url), щоб ваші клієнти поверталися на ваш сайт після завершення процесу оплати.

Якщо return_url не задано, користувачі будуть перенаправлені за замовчуванням на одну зі стандартних сторінок CASCAD.

Ви можете перезаписати URL для повернення після здійснення індивідуальної транзакції в об'єкті options з наступним необов'язковим полем:

CASCAD налаштовує для вас посилання для автоповернення у вашому обліковому записі, але ви також можете передавати значення return_url, перезадаючи цей параметр.

Наприклад, ви можете налаштувати перенаправлення платника в індивідуальному порядку, залежно від ID сесії або інших налаштувань транзакції, які можна вказати в URL. У такому разі, щоб задати URL для повернення, увімкніть return_url в налаштуваннях інвойсу.

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    return_url: "https://somedomain.com/",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="return_url" value="https://somedomain.com/" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Локалізація¶

Наразі Checkout підтримує три основні мови: англійську, українську, російську. За замовчуванням використовується мова браузера клієнта, але ви можете встановити відображення сторінки певною мовою:

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    locale: "uk",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="locale" value="uk" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Кастомізація¶

Одна з наших улюблених налаштувань Checkout – налаштування його зовнішнього вигляду.

Відображення¶

Задається в об'єкті display з наступними ключами:

Фільтрація платіжних методів¶

Для деяких платежів ви можете дозволити фільтрацію методів оплати або обійти перший крок із вибором методу на Checkout.

Задається в об'єкті display з наступними ключами:

Стиль¶

Ви можете налаштувати зовнішній вигляд Checkout, щоб сторінка відповідала стилістиці вашого бренду. Перевизначити стиль можна задавши ключі властивостей всередині об'єкта style.

payment_widget.init ({
    public_key: "YOUR_COMMERCE_ACCOUNT_PUBLIC_KEY",
    amount: "100.00",
    currency: "UAH",
    style: {
        pay_button_label: "pay"
    },
});

Метадані¶

Налаштування:

У прикладі вище ми пропонували вам передавати унікальний reference_id разом з рештою даних про платеж. Так зв'язується платіж і Callbacks по ньому, що передаються CASCAD, і можна відслідковувати зміни статусу платежу та співвідносити із замовленням у внутрішній системі продавця (ми використовували цей підхід у прикладі як оптимальний).

Однак, як альтернативу, ви можете задати унікальний ідентифікатор для замовлення у вигляді order_id і передавати CASCAD API всередині metadata. Ті ж метадані будуть повернуті до metadata Callbacks, та система співвіднесе платіж та замовлення.

Так, якщо ви хочете зберігати та обробляти додаткові дані про платіж, використовуйте metadata. Наприклад, якщо постачальнику послуг передачі даних потрібно вказувати додаткові опції до конкретних тарифних планів, наприклад, "Обмеження використання", "Швидкість у заданих межах", їх можна надсилати до метаданих.

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    metadata: {
        "usage-limit": "5GB",
        "speed-within-quota": "2MBbps",
        "post-usage-quota": "512kbps"
    }
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="metadata[usage-limit]" value="5GB" />
    <input type="hidden" name="metadata[speed-within-quota]" value="2MBbps" />
    <input type="hidden" name="metadata[post-usage-quota]" value="512kbps" />
    <input type="submit" value="Pay" />
</form>

Відображення на сторінці¶

Ми пропонуємо два варіанти інтеграції:

• Перенаправлення на окрему сторінку: Перенаправлення на кастомізовану сторінку оплати.
• Вбудований елемент (iFrame или lightbox): Відображається всередині сторінки оплати на вашому сайті.

Перенаправлення на окрему сторінку¶

Коли ваш клієнт перенаправляється до Checkout, Checkout відкривається як окрема сторінка у браузері та у рядку браузера відображається її адреса.

Задається значенням ключа target — redirect для платіжного віджету (для платіжного посилання - задається прямим посиланням).

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    target: "redirect"
};
</script>

<form action="https://gate.cascad.com/hpp/" method="get" target="_self">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>

Вбудований елемент (iFrame или lightbox)¶

У цьому варіанті Checkout вбудовується на сторінці як елемент iFrame або lightbox (модальне вікно). Коли клієнт переходить до Checkout, адреса сторінки не змінюється.

Базовий варіант для відображення в iFrame або lightbox Checkout використовує адаптивний веб-дизайн, тому розміри та вміст блоку підлаштовуються під розміри вікна (залежно від кількості елементів усередині змінюється висота iFrame або lightbox, а контент, розташований нижче блоку iFrame, додатково зміщується вниз).

Задайте значення iframe для ключа target, щоб додати елемент із Checkout на сторінку. Визначте selector_id в налаштуваннях віджета (за замовчуванням payment_widget).

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    target: "iframe"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://gate.cascad.com/hpp/" method="get" target="payment_frame">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="UAH" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>
<iframe name="payment_frame" src="" id="payment_frame" width="100%" height="600"></iframe>

Платіжний віджет¶

Бібліотека¶

Найбільш легкий та швидкий шлях інтегрувати та почати використання Checkout — paymentWidget.js.

Щоб вбудувати віджет на ваш сайт, скачайте його з CDN або додайте бібліотеку всередину вашої javascript-збірки.

Репозиторій: unpkg.com/@paycore/payment-widget-js

CDN:

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.js"></script>

Ініціалізація¶

Ми пропонуємо два шляхи інтеграції payment_widget.js на сайт:

1. window.payment_widget.init()

   З цим методом payment_widget.js запускається лише синхронно.

2. window.HPPConfig

   Рекомендований метод, з яким payment_widget.js може запускатися синхронно або асинхронно.

Після того, як будуть визначені та заповнені всі поля, на сторінці з'явиться список доступних методів.

<script src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    target: "redirect"
});
</script>

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
    target: "redirect"
};
</script>

Конфігурація¶

<script src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    base_url: "https://pay.yourdomain.сom/hpp/",
    selector_id: "payWidget",
    frame_id: "payFrame",
    target: "redirect",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods"
});
</script>

<script async src="https://unpkg.com/@paycore/payment-widget-js@0.1.93/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    base_url: "https://pay.yourdomain.сom/hpp/",
    selector_id: "payWidget",
    frame_id: "payFrame",
    target: "redirect",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "UAH",
    description: "Some goods",
};
</script>

Дії з віджетом¶

window.payment_widget.init({
    public_key: "<your_public_key>",
    amount: "100.00",
    currency: "UAH",
});

window.payment_widget.reinit({
    public_key: "<your_public_key>",
    amount: "100.00",
    currency: "UAH",
});

window.payment_widget.close({
    frame_id: "<id_of_frame>", // By default: `payment_widget`
});

Події¶

Віджет обробляє події, які генерує Checkout та які ви також можете використовувати для обробників.

Додавання обробників подій¶

Три можливі методи для додавання обробників подій:

1. Стандартний підхід

   Прив’язка до константи

   window.payment_widget.bindEventListener(payment_widget.events.<EVENT_CONSTANT>, handler)
   

   Прив’язка до ім'я

   window.payment_widget.bindEventListener(<event_name>, handler)
   

   Приклад ведення журналу консолі

   window.payment_widget.bindEventListener('delete', () => {console.log("Iframe closing handle")})
   

2. Додаткова конфігурація

   init()

   window.payment_widget.init({
       public_key: 'pk_test_<your_key>',
       handlers: {
           <event_name>: handler
       }
   });
   

   HPPConfig

   window.HPPConfig = {
       public_key: 'pk_test_<your_key>',
       handlers: {
           <event_name>: handler
       }
   };
   

3. За подією в iFrame

   Можна обробляти події в iFrame безпосередньо, якщо платіжний віджет (JS) не використовується.

   window.addEventListener(<event_name>, callback, false);
   

   Документація MDN: Window.postMessage() .

Чим ми можемо допомогти?¶

Дякую, що використовуєте продукти CASCAD! Якщо вам потрібна додаткова порада або допомога, щоб розібратися в налаштуваннях Checkout, зв'яжіться, будь ласка, із нашою службою підтримки .