Инструменты пользователя

Инструменты сайта


payment-links-specs

Платежные ссылки агрегатора Onpay.ru

ВНИМАНИЕ. Все запросы к платежной форме выполняются только методом GET. Селектор POST/GET в Кабинете продавца меняет тип запросов API мерчанта, т.е. каким образом Onpay будет присылать запрос мерчанту с уведомлением о свершившейся оплате.

Мерчант – пользователь сервиса Onpay.ru обладающий правами получать платежи от третьих лиц («продавец») через систему Onpay (сайт продающий услуги или товары, интернет магазин, интернет -сервис и т.п.)

Клиент – любой пользователь системы мерчанта(«покупатель»), желающий переводить деньги Мерчанту через сервис Onpay (покупатель который оплачивает на сайте Мерчанта товары или услуги)

Настройки панели управления, касающиеся платежных ссылок

При помощи настроек в личном кабинете продавца можно:

1) определить набор методов оплаты, которые будут присутствовать на платежной форме, а также задать им группировку и сортировку,

2) выбрать шаблон внешнего вида формы, а также настроить подходящие цвета,

3) определить набор и названия полей, которые плательщик должен будет заполнить,

4) включить и настроить защиту платежных ссылок. Для этого используются настройки из следующей таблицы.

Название Возможные
значения
Описание
Проверять
MD5 на
ссылках
Да
Нет
Если опция включена – все ссылки и формы, ведущие на платежную страницу сервис Onpay, должны иметь контрольную подпись MD5 (для платежей на фиксированную сумму, для свободных - необязательно). Описание метода формирования подписи см. ниже.
Если опция выключена - пользователи смогут изменять параметры платежей заданные вами (например, оплатить заказ стоимостью 100руб платежом с суммой 1 руб). Выключайте эту опцию, только если это приемлемо для Вашего ресурса, например, если Вы не продаете товары с фиксированной стоимостью, а предоставляете пользователям возможность пополнить счет на любую произвольную сумму. То есть настройка имеет смысл только для платежей «с фиксированной суммой».
Ключ для
API IN
10-20 символов Используется для вычисления контрольной подписи при отправке уведомлений о поступлении платежей в вашу систему и сверки с контрольной подписью, полученной при переходе пользователей по ссылкам-формам с вашего сайта.
Внимание! Никогда не указывайте секретные ключи в ссылках, формах или других публично доступных местах, т.к. зная его, злоумышленник сможет подделывать уведомления о платежах и платежные ссылки!
Запрет свободных платежей Да
Нет
Если опция включена, то плательщик сможет совершить оплату только перейдя с Вашего сайта, на котором должна быть сформирована ссылка со всеми необходимыми параметрами и подписью MD5

Параметры платежной ссылки

Платежные ссылки должны вести на страницу:

http://secure.onpay.ru/pay/{merchant_login}

Где {merchant_login} – это логин Мерчанта, в сервисе Onpay, которому предназначается платеж.

Список параметров платежной ссылки:

Название Возможные значения Описание
pay_mode «free» или «fix» Режим платежа. free – пользователь сможет менять сумму платежа в платежной форме, fix – пользователю будет показана сумма к зачислению (т.е. за вычетом всех комиссий) без возможности её редактирования. Обязательно указать сумму платежа price и назначение pay_for
price Дробное число, до 2-х знаков после запятой. Сумма платежа. Внимание! При формировании контрольной подписи число содержит не менее 1-го знака после запятой. Т.е. «100» в подписи будет «100.0», а не «100». Внимание! Все суммы в платежках и платежах округляются вниз до 2-ух знаков после запятой. Т.е., число «100.1155» будет округлено до «100.11».
ticker 3-х символьное наименование валюты (по умолчанию RUR) Основная валюта ценника.
pay_for String (100max) (Для «прямых» платежей можно использовать только цифры!) Номер заказа, заявки, аккаунт пользователя и т.п. для идентификации платежа в системе магазина.
md5 string(32) Подпись параметров ссылки, для защиты от изменений пользователем. Принцип формирования см. ниже.
convert «yes» или «no» (по умолчанию «yes») Принудительная конвертация платежей в валюту ценника. Если включена – все поступающие платежи будут конвертироваться в валюту ценника. Т.е. если в ссылке установлена стоимость 100RUR, а клиент оплатил с помощью USD – вы получите на счет 100RUR. Если выключена, вы получите ту валюту, которой платит клиент. Т.е. например, пользователь платит 3.5WMZ за ваш товар стоимостью 100RUR – вы получите 3.5WMZ на свой WMZ счет в системе Onpay (при этом уведомление по API будет содержать 100RUR). ВНИМАНИЕ! Если оплата поступает из НЕбалансовой системы(система, не имеющая собственного баланса, пример - OSP), то конвертация будет происходить в валюту ценника.
url_success http:* / https:* (255max) Ссылка, на которую будет переадресован пользователь после успешного завершения платежа. Внимание! Не может содержать параметры запроса (все, что идет после «?» в ссылке). Если Вам нужны параметры после «?» в ссылке используйте url_success_enc.
url_success_enc http:* / https:* (255max) Необязательный параметр, содержащий ссылку для перехода в случае успешного платежа, закодированную в base64. Параметр url_success_enc имеет приоритет над параметром url_success в том смысле, что если в ссылке будут присутствовать оба параметра, параметр url_success будет проигнорирован. Если в ссылке присутствует только параметр url_success, а параметра url_success_enc - нет, то будет использован параметр url_success, но по техническим причинам он будет обрезан справа начиная с первого встретившегося символа '&'.
url_fail http:* / https:* (255max) Ссылка, на которую будет переадресован пользователь после неудачного завершения платежа. Внимание! Не может содержать параметры запроса (все, что идет после «?» в ссылке). Если Вам нужны параметры после «?» в ссылке используйте url_fail_enc.
url_fail_enc http:* / https:* (255max) Необязательный параметр, содержащий ссылку для перехода в случае неудачного или отмененного платежа, закодированную в base64. Параметр url_fail_enc имеет приоритет над параметром url_fail в том смысле, что если в ссылке будут присутствовать оба параметра, параметр url_fail будет проигнорирован. Если в ссылке присутствует только параметр url_fail, а параметра url_fail_enc - нет, то будет использован параметр url_fail, но по техническим причинам он будет обрезан справа начиная с первого встретившегося символа '&'.
user_email String (40max) E-mail плательщика
user_phone String (40max) Телефон плательщика
note String (255max) Заметка. В этом параметре можно передать любой комментарий, который будет передан через API вашему сайту при поступлении платежа (в запросе типа PAY)
ln «en» или «ru»(по умолчанию «ru») Язык отображения платежной формы
f 1, 7, 8, 9, 10, 11 Вариант дизайна платежной формы
one_way 3-х символьное наименование валюты Формы оплаты одним способом (выбрана валюта и сумма платежа, для ввода доступен только e-mail пользователя) Для использования форм с выбранной платежной системой в ссылку необходимо передать параметры: one_way - валюта, отличная от RUR, pay_mode - «fix», pay_for - номер заказа, price - цена, ticker - RUR
price_final «true» Комиссию платежной системы взымать с продавца. К стоимости заказа не будет прибавляться комиссия платежной системы на ввод. Если параметр не указан, или в нем передано значение отличное от «true», то комиссия будет взыматься с плательщика
onpay_ap_xxx string Дополнительные параметры


Конструктор платежных ссылок, находящийся на странице «Настройки по умолчанию» Личного Кабинета будет всегда использовать параметры url_success_enc и url_fail_enc. Использование параметров в ссылках, задаваемых в настройках по-умолчанию разрешено.

Параметр price_final

Значение Price_final указывает, с кого должна взиматься комиссия платежных систем. 1% (комиссия Onpay.ru) всегда берется с продавца (мерчанта) при выводе денег.

1) Эти данные привидены для платежа, сумма которого 10 USD, а плательщик платит в рублях. Причем комиссия платежной системы равна 10%, а курс обмена RUR/USD = 30/1 2) Первые два столбца показывают настройки мерчанта, вторые два показывают реально прошедшие суммы, три последних показывают значения полей в запросах API.

Цена товара price_final convert Плательщик платит Мерчант получает order_amount order_currency paid_amount (RUR)
10 USD false (по умолчанию) yes 333.33 RUR 300.0 RUR 300.0 RUR 333.33
10 USD false (по умолчанию) no 333.33 RUR 10 USD 10 USD 333.33
10 USD true yes 300.0 RUR 270.0 RUR 270.0 RUR 300.0
10 USD true no 300.0 RUR 9 USD 9 USD 300.0

Параметр pay_mode

Работа параметра pay_mode в случае переплаты, недоплаты, оплаты не тем способом или повторной оплаты

При формировании квитанции (ордера) к оплате на фиксированную сумму (fix), система по-разному работает с «ошибочными» платежами. Возьмем самый типичный пример: ордер был сформирован на определенную сумму, покупатель платит выбранной платежной системой (платежные терминалы), но не имеет возможности оплатить копейка-в-копейку (терминалы не принимают мелочь). В этом случае возможны три сценария:

  • Вариант 1. Покупатель не прочитал мелкий шрифт про 5%-ную комиссию владельца терминала. Как итог - не хватило каких то копеек для совершения покупки. В этом случае вся сумма будет зачислена на кошелек Onpay, с которого он либо оплатит без комиссий чуть меньше нужной суммы (согласовав с магазином), либо пополнит кошелек на небольшую сумму и оплатит полную сумму. Оставшиеся копейки можно будет потратить, например, на оплату телефона.
  • Вариант 2. Покупатель оплатил покупку полностью - идет зачисление на счет Продавца. Переплата в 5 рублей и менее не инициирует создание кошелька. Если покупатель желает получить «сдачу» - он может потребовать ее у Продавца (тот зачислит разницу на баланс телефона или создаст для него кошелек Onpay).
  • Вариант 3. У покупателя только большая купюра, очевидно, что ему не хочется дарить более 100 рублей, когда он платит за товар стоимостью 370 рублей 500-рублевой купюрой. В этом случае для покупателя создается специальный «кошелек» (уведомление о его создании высылается ему на почту, которую он указывал при формировании ордера). С данного кошешька можно без комиссий оплатить товар в этом же магазине, или же вывести «сдачу», например, пополнив баланс собственного телефона.

Теперь опишем в таблице то, что происходит, терминами API.

  • pay_mode - параметр, определяющий тип платежа: free или fix. Если не указан в ссылке, то по умолчанию pay_mode=free.
  • free - это электронные платежи на произвольную сумму, как правило используются интернет-сервисами для пополнения баланса пользователя на сайте.
  • fix - это платежи на фиксированную сумму равную стоимости товара.
  • В зависимости от того, какой способ выбран, пользователю будет предлагаться к оплате разные суммы, с учетом комиссий выбранного способа. Комиссии автоматически рассчитываются таким образом, чтобы магазин получил сумму точно равную стоимости товара.
  • Способ - способ оплаты, под этим термином подразумевается: платежная система; метод платежа выбранный покупателем в «Платежной форме»; онлайновый - способ платежа, выполняемый в текущем времени с проверкой вводимых данных; офлайновый - способ оплаты по которому невозможно отклонить оплату в случае ввода неверных данных (например: терминалы, банковские переводы).
  • Кошелек - кошелек в Onpay, специально создаваемый для возврата ошибочных платежей.
режим pay_mode Сумма относительно суммы в ордере Способ верный, онлайновый Способ не тот, онлайновый Способ верный, офлайновый Способ не тот, офлайновый
FIX НЕДОплата Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») В Кошелек в RUR В Кошелек в RUR
FIX Сумма как в ордере или до 5 руб. больше Зачисление продавцу Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») Зачисление Зачисление (в валюте фактического зачисления)
FIX ПЕРЕплата на более чем 5 руб. Зачисление, «сдача» - в Кошелек в RUR Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») Зачисление, «сдача» - в Кошелек в RUR Зачисление (в валюте фактического зачисления), «сдача» - в Кошелек в RUR
FREE НЕДОплата Зачисление продавцу Зачисление (в валюте цены товара) Зачисление Зачисление (в валюте цены товара, и только если конвертация невозможна в валюте фактического зачисления)
FREE Сумма как в ордере или до 5 руб. больше Зачисление продавцу Зачисление (в валюте цены товара) Зачисление Зачисление (в валюте цены товара, и только если конвертация невозможна в валюте фактического зачисления)
FREE ПЕРЕплата на более чем 5 руб. Зачисление продавцу Зачисление (в валюте цены товара) Зачисление Зачисление (в валюте цены товара, и только если конвертация невозможна в валюте фактического зачисления)

Повторная оплата: Во всех случаях в режиме и fix и free деньги зачисляются в Кошелек.

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

Дополнительные параметры, передаваемые в платежную форму сайтом мерчанта. Будут возвращены в check и pay запросе. Все дополнительные параметры должны начинаться с префикса *onpay_ap_*, затем должно идти название параметра(только латинские символы в нижнем регистре и цифры, кроме 2 зарезервированных названия: onpay_ap_key и onpay_ap_signature). Количество параметров не ограничено, НО, строка, полученная как JSON представление всех доп параметров не должна превышать 65000 символов.

При передаче доп параметров мерчант должен также передать параметр *onpay_ap_signature*. Значение которого есть SHA1 от строки, полученной как конкатенация значений всех доп параметров(отсортированных по названию параметра) + НЕпередаваемого параметра onpay_ap_key, значение которого равно API_KEY в настройках сайта в кабинете мерчанта.

Примеры: В случае, если API_KEY = 'test'

onpay_ap_z1 = 'q'
onpay_ap_z2 = 'w'
onpay_ap_signature = '0693732538320eb7fe487f4f15e85abf9d148573'
onpay_ap_z1 = 'q'
onpay_ap_a1 = 'w'
onpay_ap_signature = '21ce6c2615c4b325ca406470b533e8ca76759dc4'

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

ВНИМАНИЕ!!! Передача дополнительных параметров работает только при выборе API2.0 в кабинете мерчанта. Другие типы API дополнительные параметры НЕ поддерживают.

Включение защиты параметров

В личном кабинете можно включить опцию защиты платежной ссылки подписью MD5, в этом случае, при переходе на платежную форму, Onpay проверит наличие подписи MD5 и ее корректность.

Для использования проверки подписи, ордер должен быть «фиксированным», то есть должны присутствовать параметры: price и pay_for. В ином случае, даже при наличии подписи, она проверяться не будет, а ордер будет создан «свободный».

Формат строки для контрольной подписи (без кавычек): «pay_mode;price;ticker;pay_for;convert;secret_key»
Например: fix;100.0;WMR;123;yes;secret_key , где:

  • pay_mode - строка «fix».
  • price - переданный параметр, цена (Обращайте внимание на формат данных, входящих в подпись! Сумма в формате #.# - один знак после точки, даже если число не имеет дробной части).
  • ticker - валюта заказа, в которой магазин должен получить деньги, передавать в ссылке не обязательно, берется из настроек магазина по умолчанию.
  • pay_for - переданный параметр.
  • convert - переданный параметр, передавать в ссылке не обязательно (Даже если вы не указываете параметр “convert” в ссылке, то в строке для формирования подписи md5 необходимо указать “yes” (без кавычек) на месте этого параметра).
  • secret_key - секретный ключ API магазина, задаваемый в настройках в личном кабинете.

Для защиты от «свободных» платежей (если они не нужны), необходимо включить в личном кабинете флаг «Запрет платежей без API», если эта функция будет включена, то плательщик не сможет создать «свободный» ордер, а только «фиксированный», у которого включена проверка MD5.

payment-links-specs.txt · Последние изменения: 2024/03/07 06:04 — support