Перейти к содержанию

Checkout: Справочник

Перенаправление клиентов к Checkout

Вы можете использовать как ссылку на оплату (в виде стандартной HTML-формы), так и платежный виджет (JS) для того, чтобы собрать и передать детали платежа и данные клиента в Checkout. Подробнее о методах интеграции читайте здесь.

Когда клиент выбирает оплату онлайн, ваш сайт должен отправить данные HTML-формы на https://pay.paymentstrust.com/hpp/.

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

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

Как улучшить пользовательский опыт на вашем сайте

  • Любые параметры, которые вы передаете через HTML-форму, такие как данные клиента (ФИО, email), должны иметь возможность для автозаполнения (или автозаполнения и скрытия), чтобы пользователю было легче заполнять форму.
  • Воспользуйтесь возможностью кастомизировать вашу Checkout.
  • Чтобы улучшить конверсию, PaymentsTrust рекомендует перенаправлять клиента к Checkout в том же окне браузера или встроить Checkout на страницу в iFrame.

Безопасное перенаправление

Используйте этот способ, чтобы быть уверенными, что детали платежа безопасно передаются между вашим сервером и PaymentsTrust.

Важно!

Мы рекомендуем использовать этот метод перенаправления клиентов к PaymentsTrust, потому что он не требует передачи параметров платежа в браузер пользователя. Это предотвращает возможность просмотреть или изменить какой-либо из параметров платежа.

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

  1. Ваш веб-сервер отправляет стандартный POST запрос с параметрами платежа, используя приватный API.
  2. Сервер PaymentsTrust создает инвойс (Payment Invoice) и возвращает стандартный HTTP(S) ответ.
  3. Ваш веб-сервер извлекает из ответа значение ID инвойса.
  4. Формируется ссылка для перенаправления вида:
https://pay.paymentstrust.com/hpp/?cpi=<PAYMENT_INVOICE_ID>
<script src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<script>
window.widget.init({
    cpi: "<PAYMENT_INVOICE_ID>",
});
</script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>

Возможности настройки

То, какой выбран метод интеграции, определяет, какие вы задаете параметры Checkout.

Напомним общие требования

Интеграция Checkout будет успешна, если выдержаны следующие требования:

  • Аккаунт активирован.
  • На нём разрешено создание инвойсов платежа (payment invoices) через публичный API.
  • В настройках задан и активирован хотя бы один тип валют.

Пожалуйста, свяжитесь с вашим аккаунт-менеджером, если не уверены, что все эти требования выполнены.

Стандарт кодирования текстовых полей запросов-ответов

Все текстовые поля используют стандарт UTF-8.

Параметры URL

Все параметры URL должны передаваться в полном виде, так например вместо www.google.co.uk следует использовать https://www.google.co.uk.

Основные параметры

Все нижеследующие параметры обязательные*:

Ключ Тип Описание
public_key* string Ключ доступа к открытому API, находится в Панели управления в разделе «Настройки» → «Интеграция»
amount* float Сумма платежа
currency* (string) CurrencyCode Код валюты платежа (трёхбуквенный ISO 4217 код)
Пример: Платеж с минимальным набором параметров
<script src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    public_key: "your_public_key",
    baseUrl: "https://pay.paymentstrust.com/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    amount: 100.00,
    currency: "USD"
});
</script>
<form action="https://pay.paymentstrust.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>

Доступные валюты

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

Тестовый режим

Если вы хотите протестировать обработку платежа, замените «боевой» (Public Live Key) тестовым ключом доступа (Public Test Key).

Дополнительные параметры

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

Ключ Тип Описание
reference_id string Уникальный ID инвойса платежа в системе учёта продавца
description string Описание платежа
expires int Дата, до которой действителен инвойс, в формате UNIX таймстамп, UTC+0
Пример: Платеж с дополнительными параметрами
<script async src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<script>
window.widget.init({
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    reference_id: "<your_unique_reference_id>",
    description: "Some goods",
    expires: 1602414000
});
</script>
<form action="https://pay.paymentstrust.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <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>

Идемпотентность

Идемпотентность методов обработки предотвращает обработку дублирующихся запросов, благодаря использованию уникального значения для ключа reference_id.

Каждый reference_id должен быть уникальным идентификатором (уникальным — в рамках конкретного коммерческого аккаунта), и вы можете настроить генерацию собственных ключей, чтобы быть уверенными, что они не повторяются, но и не генерируются в хаотичном порядке.

UUID — это большие (128-битные) числа. Чтобы избежать "случайного" создания одинаковых ключей, мы рекомендуем использовать генератор UUID для ваших reference_id. Это особенно важно, когда reference_id генерируются для разных инвойсов платежей одновременно.

Данные клиента

Объект customer содержит дополнительную информацию о клиенте, который совершает платеж. В том числе: email — e-mail, который можно использовать для отправки уведомлений об успешном или отклоненном платеже (если вы используете этот канал для коммуникации с пользователями).

Настройте прием данных с помощью следующих дополнительных параметров:

Ключ Тип Описание
reference_id* string Уникальный ID клиента в системе учета продавца
email string E-mail клиента
phone string Номер телефона клиента
name string Имя клиента
metadata array[key:value] Метадата (любые дополнительные данные, которые вам необходимо передавать)
Пример: Платеж с данными о клиенте
<script async src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    baseUrl: "https://pay.paymentstrust.com/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    public_key: "<your_public_key>",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    customer: {
        reference_id: "cus_1234567",
        email: "somename@domain.com",
        name: "John Wick",
        metadata: {
            key1: "value1",
            key2: "value2"
        }
    }
});
</script>
<form action="https://pay.paymentstrust.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="USD" />
    <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_usd_hpp.

Если у сервиса (service) есть обязательные поля, вы их указываете в service_fields.

Ключ Type Description
service (string) ServiceCode Код сервиса. Например: bitcoin_btc_hpp
service_fields (object) string[key:value] Обязательные поля для выбранного сервиса. Например: [{'name': 'John Doe'}]
Пример: Платеж с автопроцессингом
<script async src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    baseUrl: "https://pay.paymentstrust.com/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    service: "paypal_usd_hpp"
});
</script>
<form action="https://pay.paymentstrust.com/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="service" value="paypal_usd_hpp" />
    <input type="submit" value="Pay" />
</form>
Попробуйте настроить Checkout в "песочнице"

Вы можете предварительно настроить все эти параметры Checkout и проверить отображение в песочнице .

Аналогично вы сможете настроить платежную ссылку или сниппет кода для выполнения на странице сайта.

Демо

URL для возвращения

Задайте URL для возвращения (return_url), чтобы ваши клиенты возвращались на ваш сайт после завершения процесса оплаты.

Если return_url не задан, пользователи будут по умолчанию перенаправлены на одну из стандартных страниц PaymentsTrust.

Вы можете перезаписать URL для возвращения после совершения индивидуальной транзакции в объекте options со следующим необязательным полем:

Ключ Тип Описание
return_url string URL, на который перенаправляется клиент после завершения процесса оплаты

PaymentsTrust настраивает для вас ссылку для автовозвращения в вашем аккаунте, но вы также можете передавать значения return_url, перезадавая этот параметр.

Например, вы можете настроить перенаправления плательщика в индивидуальном порядке, в зависимости от ID сессии или других настроек транзакции, которые можно указать в URL. Чтобы задать URL для возвращения в таком случае, включите return_url в настройки инвойса.

Пример: Платеж с индивидуальным URL для возвращения пользователя
<script src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
    window.widget.init({
        public_key: "your_public_key", // replace the value with YOUR commerce public key
        baseUrl: "https://pay.paymentstrust.com/hpp/",
        flow: "iframe",
        selector: "merchant-widget-mount-point",
        return_url: "https://somedomain.com/",
        amount: 100.00,
        currency: "USD",
        description: "Some goods"
});
</script>
<form action="https://pay.paymentstrust.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="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Callback URL

В отличие от URL для возвращения клиента (return_url), URL для Callbacks (callback_url) перезаписывать нельзя (согласно требованиям безопасности). Вы указываете URL ссылки для получения Callbacks в настройках аккаунта .

Локализация

Сейчас Checkout поддерживает три основных языка: английский, украинский, | |----------|--------|----------------------------------------------------| |locale|string|Код ISO 639-1 одного из предустановленных языков (en, uk, ru) |

Пример: Платеж с предустановленным языком для Checkout
<script src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
    window.widget.init({
        public_key: "your_public_key", // replace the value with YOUR commerce public key
        baseUrl: "https://pay.paymentstrust.com/hpp/",
        flow: "iframe",
        selector: "merchant-widget-mount-point",
        locale: "uk",
        amount: 100.00,
        currency: "USD",
        description: "Some goods"
    });
</script>
<form action="https://pay.paymentstrust.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="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Кастомизация

Одна из наших любимых настроек Checkout — настройка внешнего вида.

Отображение

Задается в объекте display со следующими ключами:

Ключ Тип Описание
hide_header bool Флаг "Скрыть хедер", по умолчанию: false
hide_footer bool Флаг "Скрыть футер", по умолчанию: false
hide_progress_bar bool Флаг "Скрыть индикатор процесса (шаги выполнения)", по умолчанию: false
hide_method_filter bool Флаг "Скрыть категории для методов", по умолчанию: false
hide_lifetime_counter bool Флаг "Скрыть таймер обратного отсчета", по умолчанию: false

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

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

Задается в объекте display со следующими ключами:

Ключ Тип Описание
show_methods array[method_codes] Флаг "Отобразить определенные методы оплаты"
hide_methods array[method_codes] Флаг "Скрыть определенные методы оплаты"

Дополнительная настройка платежных сервисов

Все платежные сервисы можно настроить в настройках аккаунта : НастройкиПлатежные методы.

Стиль

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

Ключ Описание
pay_button_label Надпись на кнопке "Оплатить" на всех поддерживаемых языках. Варианты: pay, subscribe, donate
show_method_logo Отображать иконку или лого на блоке-превью платежного метода
theme Предустановленные темы, включающие в себя сразу несколько параметров: макет, цветовая схема, шрифт. Варианты: light, dark
success_color Цветовая схема (базовый цвет) для сообщений об успешной оплате
warning_color Цветовая схема (базовый цвет) для сообщений с предупреждениями
danger_color Цветовая схема (базовый цвет) для сообщений об опасности дальнейших изменений
info_color Цветовая схема (базовый цвет) для информационных сообщений
primary_color Базовый цвет
primary_variant Вариативный цвет, который будет сочетаться с primary_color. Если базовый цвет — тёмный, вариативный будет на несколько тонов светлее. Используется в наиболее важных UI-компонентах (переходах, кнопках)
primary_text_color Базовый цвет текста
primary_background_color Базовый цвет фона
on_primary_color Наиболее подходящий цвет для элементов, сочетающийся с цветом фона. Может базироваться на primary_background_color
secondary_color Вспомогательный цвет
secondary_variant Вариативный цвет, который будет сочетаться с secondary_color. Если базовый цвет — тёмный, вариативный будет светлее. Используется во второстепенных UI-компонентах (переходах, кнопках)
secondary_text_color Вспомогательный цвет текста, используемый преимущественно во второстепенных UI компонентов
secondary_background_color Второстепенный цвет фона (для превью платежных методов)
on_secondary_color Наиболее подходящий цвет для элементов, сочетающийся со второстепенным цветом фона. Может базироваться на secondary_background_color
Пример: Замена надписи на кнопке
window.widget.init ({
    public_key: "your_public_key",
    amount: "100.00",
    currency: "USD",
    style: {
        pay_button_label: "Оплатить заказ"
    },
});

Метаданные

Настройки:

Ключ Описание
metadata Набор пар в виде "ключ-значение". Дополнительные данные для инвойса

В примере выше мы предлагали вам передавать уникальный reference_id вместе с остальными данными о платеже. Так связывается платеж и Callbacks по нему, передаваемые PaymentsTrust, и можно отслеживать изменения статуса платежа и соотносить с заказом во внутренней системе продавца (мы использовали этот подход в примере как оптимальный).

Однако, в качестве альтернативы, вы можете задать уникальный идентификатор для заказа в виде order_id и передавать PaymentsTrust API внутри metadata. Те же метаданные будут возвращены в metadata Callbacks, и система соотнесёт платёж и заказ.

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

Платеж с заданными метаданными (по примеру выше)
<script src="https://unpkg.com/@paycore/merchant-widget-js@0.1.8/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    public_key: "your_public_key",
    baseUrl: "https://pay.paymentstrust.com/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    metadata: {
        "usage-limit": "5GB",
        "speed-within-quota": "2MBbps",
        "post-usage-quota": "512kbps"
    }
});
</script>
<form action="https://pay.paymentstrust.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="USD" />
    <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 удобно, но может привести к определенным проблемам с безопасностью и кроссбраузерностью.

Выбирая этот метод, учитывайте:

  • Часть платежных методов, таких как iDEAL, запрещают отображение своих внутренних страниц в iFrame, и оплата с их помощью становится невозможна. Другие методы могут потребовать больше пространства при встраивании, чем выделено для вашего iFrame на странице. Вы также должны подготовиться к возможным различиям в получении Callbacks от разных платежных методов, учитывая, что моменту полного завершения процесса оплаты, клиент может уже закрыть страницу с iFrame.

  • Другая проблема, с которой вы можете столкнуться, — политика обработки данных в cookie-файлах. Checkout использует cookie для обработки данных. Использование iFrame означает, что браузер может налагать внешние ограничения на обработку cookie-файлов в iFrame. Несмотря на то, что существуют методы обхода запретов, позволяющие браузеру принимать файлы cookie с настройками по умолчанию, клиент может включить больше ограничений в отношении cookie. Самые распространенные проблемы возникают с браузерами Apple Safari и Google Chrome: по умолчанию они требуют загрузки инициированной пользователем страницы внутри iFrame. Значит, сперва iFrame должен загрузить страницу с родительского домена, а затем уже пользователь должен кликнуть по кнопке и перейти к Checkout.

Таким образом, PaymentsTrust не может гарантировать, что все платежные методы будут корректно работать внутри iFrame и что поведение внутренних страниц оплаты для выбранных методов будет точно таким же, как в полноэкранной версии. Более того, может отличаться процесс обработки транзакций в тестовом и "боевом" окружении.

Требуется дополнительная помощь с настройками?

Спасибо, что используете продукты PaymentsTrust! Если вам требуется дополнительный совет или помощь, чтобы разобраться в настройках Checkout, свяжитесь, пожалуйста, с нашей службой поддержки .