Инструменты пользователя
Содержание
Платежные ссылки агрегатора 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.