Платежные ссылки агрегатора 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).
url_success	http:* / https:* (255max)	Ссылка, на которую будет переадресован пользователь после успешного завершения платежа. Внимание! Не может содержать параметры запроса (все, что идет после «?» в ссылке). Если Вам нужны параметры после «?» в ссылке используйте url_success_enc.
url_success_enc	http:* / https:* (255max)	Необязательный параметр, содержащий ссылку для перехода в случае успешного платежа, закодированную согласно RFC3986 с отличием лишь в том, что по историческим соображениям пробелы заменяются знаком '+'. Такое кодирование реализует функция PHP urlencode. Параметр 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)	Необязательный параметр, содержащий ссылку для перехода в случае неудачного или отмененного платежа, закодированную согласно RFC3986 с отличием лишь в том, что по историческим соображениям пробелы заменяются знаком '+'. Такое кодирование реализует функция PHP urlencode. Параметр 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	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», то комиссия будет взыматься с плательщика

Конструктор платежных ссылок, находящийся на странице «Настройки по умолчанию» Личного Кабинета будет всегда использовать параметры 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 деньги зачисляются в Кошелек.

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

В личном кабинете можно включить опцию защиты платежной ссылки подписью 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.