Размещение PayQR

Чтобы реализовать совершение покупок или оплату через PayQR на стороне интернет-сайта нужно только подключить javascript и добавить кнопку, вызывающую popup-окно PayQR (или кнопки). Именно через атрибуты этой кнопки первоначально передается содержание покупки и другие параметры совершения покупки или оплаты от интернет-сайта серверу PayQR. В процессе совершения покупки или оплаты сервер PayQR взаимодействует с интернет-сайтом, и интернет-сайт может актуализировать какие-то данные покупки до ее оплаты при наличии соответствующих обработчиков у интернет-сайта (например, применять скидки для конкретного покупателя и увеличить сумму заказа при выбранном определенном способе доставки покупки).

<script src="https://payqr.ru/popup.js?merchId=000000-00000" charset="utf-8"></script>

<button
    class="payqr-button"
    style="width:163px;height:36px"
    data-scenario="buy"
    data-amount="18990.50"
    data-orderId="1523452"
    type="button"
    >Купить быстрее</button>

Подключение скрипта

Мы подготовили специальный маленький скрипт popup.js, в котором располагаются необходимые стили и обработчики для показа popup-окна PayQR. Скрипт спроектирован так, чтобы не увеличивать время загрузки страницы – его элементы начинают загружаться только тогда, когда основой контент интернет-сайта уже загружен. Также скрипт корректно ведет себя при его вызове на мобильных устройствах, адаптируя свою логику под возможности конкретного мобильного устройства.

Скрипт подключается к интернет-сайту кодом в разделе head, как и любой другой javascript-файл. В параметре merchId кода указывается уникальный номер магазина в PayQR, который можно узнать в своем личном кабинете в разделе «Магазины».

<script src="https://payqr.ru/popup.js?merchId=000000-00000" charset="utf-8"></script>

Добавление кнопки

Обработчики PayQR для создания счетов на оплату от интернет-сайта подключаются через размещенный на интернет-сайте скрипт к кнопке <button class="payqr-button">Купить быстрее</button>. Наличие класса payqr-button в кнопке обязательно.

Если PayQR используется как метод совершения покупок (что рекомендуется для достижения наилучших результатов), используйте в кнопке те атрибуты и те параметры, которые необходимы в вашей системе учета, программном обеспечении и так далее для создания заказа (получения его номера) и дальнейшей оплаты этого заказа. Чаще всего в таких случаях, помимо содержания корзины, требуется еще имя покупателя и его номер телефона – запрашивайте их через PayQR атрибутами data-firstname-required и data-phone-required, соответственно. Но помните, что чем меньше данных запрашивается у покупателей на интернет-сайтах, тем выше конверсия в успешные покупки, с PayQR ситуация гораздо лучше, но все-таки это правило работает и здесь.

Если PayQR используется только как метод оплаты покупок, то тут все аналогично обычному интернет-эквайрингу – в кнопку минимально нужно передать номер заказа (data-orderid), сумму к оплате по этому заказу (data-amount) и содержание заказа (data-cart).

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

<button
    class="payqr-button"
    style="width:163px;height:36px"
    data-scenario="buy"
    data-cart=
    '[{
        "article": "25425423",
        "name": "Товар",
        "imageUrl": "http://goods.ru/item1.jpg",
        "amount": "18990.50",
        "quantity": "1"
    }]'
    data-phone-required="required"
    data-amount="18990.50"
    type="button"
    >Купить быстрее</button>

<button
    class="payqr-button"
    style="width:163px;height:36px"
    data-scenario="buy"
    data-cart=
    '[{
        "article": "25425423",
        "name": "Товар1",
        "imageUrl": "http://goods.ru/item1.jpg",
        "amount": "18990.50",
        "quantity": "1"
    },
    {
        "article": "52345234",
        "name": "Товар2",
        "imageUrl": "http://goods.ru/item2.jpg",
        "amount": "999.90",
        "quantity": "1"
    }]'
    data-phone-required="required"
    data-amount="19990.40"
    type="button"
    >Купить быстрее</button>

<button
    class="payqr-button"
    style="width:163px;height:36px"
    data-scenario="buy"
    data-cart=
    '[{
        "article": "25425423",
        "name": "Товар",
        "imageUrl": "http://goods.ru/item1.jpg",
        "amount": "18990.50",
        "quantity": "1"
    }]'
    data-phone-required="required"
    data-amount="18990.50"
    data-deliverycases-required="required"
    type="button"
    >Купить быстрее</button>

<button
    class="payqr-button"
    style="width:163px;height:36px"
    data-scenario="pay"
    data-cart=
    '[{
        "article": "Форсаж",
        "name": "Оплата за интернет подключение.",
        "imageUrl": "http://internet.ru/provider.jpg",
    }]'
    data-orderid-required="required"
    data-amount-required="required"
    type="button"
    >Купить быстрее</button>

Оформление и сценарии

class

строка: payqr-button

Имя класса, по которому подключается кнопка для работы с PayQR.

payqr-button - режим popup-окна PayQR, когда совершение покупок и оплата покупок осуществляется через платежный сервис PayQR (с использованием приложения PayQR или без него, покупатель определяет самостоятельно).

style

строка

Стиль кнопки для настройки ширины и высоты.

В этом параметре можно задать размеры кнопки, например: style="width:150px;height:33px". Для корректного отображения кнопки PayQR старайтесь соблюдать соотношение ширины к высоте как 1:4.7.

type

строка: button

Технический параметр

Обязательно должен присутствовать в коде кнопки PayQR

data-scenario

строка: buy, pay

Внешний вид по сценарию покупки или оплаты в приложении.

buy

используется сценарий покупки (все кнопки и тексты в popup-окне и приложении со словом "Купить").

pay

используется сценарий оплаты (все кнопки и тексты в popup-окне и приложении со словом "Оплатить").

Данные

data-merchid

строка

Уникальный номер магазина в PayQR.

Указывается в кнопке только, если номер магазина для конкретного заказа (кнопки) на интернет-сайте отличается от номера магазина, указанного в коде скрипта popup.js.

data-orderid

строка

Номер заказа.

Номер заказа в учетной системе интернет-сайта.
Если номер заказа не заполняется на уровне кнопки, то его необходимо передать PayQR в дальнейшем ответом на уведомление от PayQR о событии invoice.order.creating.
Пользователь не сможет приступить к оплате в PayQR, пока не получен номер заказа от интернет-сайта.

data-ordergroup

строка

Номер товарной группы.

Любой дополнительный идентификатор по желанию интернет-сайта (например, идентификатор пользовательской сессии или идентификатор корзины).

data-amount

число

Сумма заказа.

Сумма заказа - обязательное поле. При необходимости интернет-сайт может изменить указанную в кнопке сумму заказа в дальнейшем ответом на уведомление от PayQR о событии invoice.order.creating.
Пользователь не сможет приступить к оплате в PayQR, пока не получена сумма заказа от интернет-сайта.

data-cart

строка: в формате JSON

Содержание заказа (список товаров/услуг или общее описание).

Каждая позиция в списке товаров/услуг - это один элемент массива в формате JSON с перечисленными ниже атрибутами. В data-cart посылать можно столько элементов (товаров/услуг), сколько необходимо.
Товары/услуги будут отображаться в списке в PayQR именно в том порядке, в котором элементы массивов были переданы интернет-сайтом в поле data-cart в кнопке. При необходимости интернет-сайт может изменить указанное в кнопке содержание заказа в дальнейшем ответом на уведомление от PayQR о событии invoice.order.creating.
Из перечисленных ниже атрибутов массива обязательно к указанию только название позиции. Артикул и количество обязательны, когда нет других идентифицирующих данных для заказа (номера заказа или номера товарной группы).

article

строка
Внутренний идентификатор позиции продавца (артикул)

name

строка
Название позиции

category

строка
Категория позиции по внутреннему классификатору PayQR

quantity

число
Количество товаров/услуг в позиции

amount

число
Стоимость позиции (всех товаров/услуг в позиции)

imageUrl

URL
Ссылка продавца на изображение позиции

data-firstname-required

строка: default, deny, required

Заполняет ли пользователь имя.

default

указывает, что значение берется из настроек в личном кабинете.

deny

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

required

используется, когда нужно запросить у пользователя имя для оформления заказа.

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-middlename-required

строка: default, deny, required

Заполняет ли пользователь отчество.

default

указывает, что значение берется из настроек в личном кабинете.

deny

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

required

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-lastname-required

строка: default, deny, required

Заполняет ли пользователь фамилию.

default

указывает, что значение берется из настроек в личном кабинете.

deny

означает, что приложение не будет предлагать пользователю заполнить фамилию, и значение будет пустым.

required

используется, когда нужно запросить у пользователя фамилию для оформления заказа.

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-phone-required

строка: default, deny, required

Заполняет ли пользователь телефон.

default

указывает, что значение берется из настроек в личном кабинете.

deny

означает, что приложение не будет предлагать пользователю заполнить телефон, и значение будет пустым.

required

используется, когда нужно запросить у пользователя телефон для оформления заказа.

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-email-required

строка: default, deny, required

Заполняет ли пользователь e-mail.

default

указывает, что значение берется из настроек в личном кабинете.

deny

означает, что приложение не будет предлагать пользователю заполнить e-mail, и значение будет пустым.

required

используется, когда нужно запросить у пользователя e-mail для оформления заказа.

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-delivery-required

строка: default, deny, required, nonrequired

Заполняет ли пользователь адрес доставки.

default

указывает, что значение берется из настроек в личном кабинете.

deny

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

required

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

nonrequired

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-deliverycases-required

строка: default, deny, required

Выбирает ли пользователь метод доставки.

default

указывает, что значение берется из настроек в личном кабинете.

deny

означает, что пользователю не будут показываться методы доставки, и значение будет пустым.

required

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-pickpoints-required

строка: default, deny, required

Заполняет ли пользователь точки самовывоза.

default

указывает, что значение берется из настроек в личном кабинете.

deny

означает, что пользователю не будут показываться точки самовывоза, и значение будет пустым.

required

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-promocode-required

строка: default, deny, nonrequired

Заполняет ли пользователь promo код.

default

указывает, что значение берется из настроек в личном кабинете.

deny

не предлагать.

nonrequired

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-promocode-details

строка: в формате JSON

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

Эти параметры могут использоваться получателем денежных средств для информирования покупателей/плательщиков о том, какие именно промо-коды можно вводить при покупке/платеже через PayQR и когда того требует реализованная логика обработки промо-кодов

article

строка
Внутренний идентификатор типа промо-кодов

description

строка
Собственное пояснение получателя денежных средств к полю ввода промо-кода

data-promocard-required

строка: default, deny, nonrequired

Предлагать покупателю указать номер карты лояльности

default

указывает, что значение берется из настроек в личном кабинете.

deny

не предлагать.

nonrequired

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

Если значение не заполнено, то оно будет получено из настроек в личном кабинете.

data-promocard-details

строка: в формате JSON

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

Эти параметры могут использоваться получателем денежных средств для информирования покупателей/плательщиков о том, номера каких именно карт лояльности можно вводить при покупке/платеже через PayQR и когда того требует реализованная логика обработки карт лояльности

article

строка
Внутренний идентификатор типа карт лояльности

description

строка
Собственное пояснение получателя денежных средств к полю ввода карты лояльности

data-userdata

строка

Пользовательские данные с свободном формате.

Маркетинг

data-crosssales

строка: в формате JSON

Перекрестные продажи (cross-sale).

Мотивация покупателя потратить больше денег на покупку через продажу товаров других категорий.
Список товаров будет отображаться в popup-окне пользователя.

article

строка
Внутренний идентификатор позиции продавца (артикул)

name

строка
Название позиции

category

строка
Категория позиции по внутреннему классификатору PayQR

quantity

число
Количество позиции

amount

число
Стоимость всей товарной позиции

imageUrl

URL
Ссылка на изображение позиции

Актуализация кнопки

Возникают ситуации, когда невозможно в силу ряда причин определить момент изменения корзины на клиентской стороне. Для этого случая можно зарегистрировать обработчик payQR.onRefreshing, в нем вы можете вызвать код актуализации кнопки по запрошенным данным корзины. Данные кнопки передаются в параметре data в формате JSON: например, значение data-amount кнопки будет в свойстве amount, а значение data-cart - в свойстве cart. Как только кнопка будет актуализирована, строго необходимо вызвать callback(), переданный в параметрах обработчика, указав в качестве аргумента данные кнопки или по желанию только изменения.

Будьте внимательны и, если вы определяете обработчик payQR.onRefreshing, всегда вызывайте callback(newData) в нем.

<script>
    $(function() {
        payQR.onRefreshing(function(data, callback) {
            // data.amount
            // data.cart
            ...
            // callback({ amount: 1234 });
        });
    });
</script>

Обработка создания заказа

На странице интернет-сайта с размещенной кнопкой PayQR вы можете зарегистрировать обработчик payQR.onOrderCreated, который будет срабатывать при успешном создании заказа в учетной системе получателя денежных средств. Обработчик будет вызываться с объектом { "orderGroup": "...", "orderId": "...", "amount": "...", "userData": "..." }

Условие вызова обработчика:
Закрытие popup-окна PayQR или возвращение на страницу WEB-сайта получателя денежных средств со специальной WEB-страницы PayQR (если нажатие на кнопку PayQR происходило на мобильном устройстве) после того, как в учетной системе получателя денежных средств произошло создание заказа.

<script>
  $(function() {
    payQR.onOrderCreated(function(data) {
      // ...
    });
  });
</script>

Обработка оплаты

На странице интернет-сайта с размещенной кнопкой PayQR вы также можете зарегистрировать обработчик payQR.onPaid, который будет срабатывать на интернет-сайте при успешной оплате заказа через PayQR. Обработчик будет вызываться с объектом { "orderGroup": "...", "orderId": "...", "amount": "...", "userData": "..." }.

Если на странице есть несколько кнопок PayQR и вы хотите идентифицировать по какой именно кнопке произошла обработка оплаты, вы можете добавить необходимые данные в параметр data-userdata кнопки, а затем получить их в зарегистрированном обработчике в поле userData. С помощью параметра data-userdata интернет-сайт может реализвать любую бизнес-логику, например, направить покупателя на определенную страницу сайта после оплаты.

<script>
    $(function() {
        payQR.onPaid(function(data) {
            // data.orderGroup
            // data.orderId
            // data.amount
            // data.userData
        });
    });
</script>