Здесь показаны различия между двумя версиями данной страницы.
Both sides previous revision Предыдущая версия Следущая версия | Предыдущая версия | ||
payment-links-specs [2015/01/19 12:29] admin |
payment-links-specs [2024/03/07 06:04] (текущий) support |
||
---|---|---|---|
Строка 38: | Строка 38: | ||
| pay_for | String (100max) (Для «прямых» платежей можно использовать только цифры!) | Номер заказа, заявки, аккаунт пользователя и т.п. для идентификации платежа в системе магазина. | | | pay_for | String (100max) (Для «прямых» платежей можно использовать только цифры!) | Номер заказа, заявки, аккаунт пользователя и т.п. для идентификации платежа в системе магазина. | | ||
| md5 | string(32) | Подпись параметров ссылки, для защиты от изменений пользователем. Принцип формирования см. ниже. | | | md5 | string(32) | Подпись параметров ссылки, для защиты от изменений пользователем. Принцип формирования см. ниже. | | ||
- | | convert | "yes" или "no" (по умолчанию "yes") | Принудительная конвертация платежей в валюту ценника. Если включена – все поступающие платежи будут конвертироваться в валюту ценника. Т.е. если в ссылке установлена стоимость 100RUR, а клиент оплатил с помощью USD – вы получите на счет 100RUR. Если выключена, вы получите ту валюту, которой платит клиент. Т.е. например, пользователь платит 3.5WMZ за ваш товар стоимостью 100RUR – вы получите 3.5WMZ на свой WMZ счет в системе Onpay (при этом уведомление по API будет содержать 100RUR). | | + | | 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 | 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_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 | 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, но по техническим причинам он будет обрезан справа начиная с первого встретившегося символа '&'. | | + | | 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_email | String (40max) | E-mail плательщика | | ||
| user_phone | String (40max) | Телефон плательщика | | | user_phone | String (40max) | Телефон плательщика | | ||
| note | String (255max) | Заметка. В этом параметре можно передать любой комментарий, который будет передан через API вашему сайту при поступлении платежа (в запросе типа PAY) | | | note | String (255max) | Заметка. В этом параметре можно передать любой комментарий, который будет передан через API вашему сайту при поступлении платежа (в запросе типа PAY) | | ||
| ln | "en" или "ru"(по умолчанию "ru") | Язык отображения платежной формы | | | ln | "en" или "ru"(по умолчанию "ru") | Язык отображения платежной формы | | ||
- | | f | 7, 8, 9, 10, 11 | Вариант дизайна платежной формы | | + | | f | 1, 7, 8, 9, 10, 11 | Вариант дизайна платежной формы | |
| one_way | 3-х символьное наименование валюты | Формы оплаты одним способом (выбрана валюта и сумма платежа, для ввода доступен только e-mail пользователя) Для использования форм с выбранной платежной системой в ссылку необходимо передать параметры: one_way - валюта, отличная от RUR, pay_mode - "fix", pay_for - номер заказа, price - цена, ticker - RUR | | | one_way | 3-х символьное наименование валюты | Формы оплаты одним способом (выбрана валюта и сумма платежа, для ввода доступен только e-mail пользователя) Для использования форм с выбранной платежной системой в ссылку необходимо передать параметры: one_way - валюта, отличная от RUR, pay_mode - "fix", pay_for - номер заказа, price - цена, ticker - RUR | | ||
| price_final | "true" | Комиссию платежной системы взымать с продавца. К стоимости заказа не будет прибавляться комиссия платежной системы на ввод. Если параметр не указан, или в нем передано значение отличное от "true", то комиссия будет взыматься с плательщика | | | price_final | "true" | Комиссию платежной системы взымать с продавца. К стоимости заказа не будет прибавляться комиссия платежной системы на ввод. Если параметр не указан, или в нем передано значение отличное от "true", то комиссия будет взыматься с плательщика | | ||
+ | | onpay_ap_xxx | string | Дополнительные параметры | | ||
\\ | \\ | ||
Конструктор платежных ссылок, находящийся на странице "Настройки по умолчанию" Личного Кабинета будет всегда использовать параметры url_success_enc и url_fail_enc. Использование параметров в ссылках, задаваемых в настройках по-умолчанию разрешено.\\ | Конструктор платежных ссылок, находящийся на странице "Настройки по умолчанию" Личного Кабинета будет всегда использовать параметры url_success_enc и url_fail_enc. Использование параметров в ссылках, задаваемых в настройках по-умолчанию разрешено.\\ | ||
Строка 77: | Строка 78: | ||
* Вариант 3. У покупателя только большая купюра, очевидно, что ему не хочется дарить более 100 рублей, когда он платит за товар стоимостью 370 рублей 500-рублевой купюрой. В этом случае для покупателя создается специальный «кошелек» (уведомление о его создании высылается ему на почту, которую он указывал при формировании ордера). С данного кошешька можно без комиссий оплатить товар в этом же магазине, или же вывести «сдачу», например, пополнив баланс собственного телефона. | * Вариант 3. У покупателя только большая купюра, очевидно, что ему не хочется дарить более 100 рублей, когда он платит за товар стоимостью 370 рублей 500-рублевой купюрой. В этом случае для покупателя создается специальный «кошелек» (уведомление о его создании высылается ему на почту, которую он указывал при формировании ордера). С данного кошешька можно без комиссий оплатить товар в этом же магазине, или же вывести «сдачу», например, пополнив баланс собственного телефона. | ||
- | Теперь опишем то, что происходит, терминами API. | + | Теперь опишем в таблице то, что происходит, терминами API. |
- | * pay_mode - параметр, определяющий тип платежа: free или fix. Если не указан в ссылке, то по умолчанию pay_mode=free | + | * pay_mode - параметр, определяющий тип платежа: free или fix. Если не указан в ссылке, то по умолчанию pay_mode=free. |
* free - это электронные платежи на произвольную сумму, как правило используются интернет-сервисами для пополнения баланса пользователя на сайте. | * free - это электронные платежи на произвольную сумму, как правило используются интернет-сервисами для пополнения баланса пользователя на сайте. | ||
* fix - это платежи на фиксированную сумму равную стоимости товара. | * fix - это платежи на фиксированную сумму равную стоимости товара. | ||
- | В зависимости от того, какой способ выбран, пользователю будет предлагаться к оплате разные суммы, с учетом комиссий выбранного способа. Комиссии автоматически рассчитывается таким образом, чтобы магазин получил сумму точно равную стоимости товара. | + | * В зависимости от того, какой способ выбран, пользователю будет предлагаться к оплате разные суммы, с учетом комиссий выбранного способа. Комиссии автоматически рассчитываются таким образом, чтобы магазин получил сумму точно равную стоимости товара. |
- | Способ = Способ оплаты, платежная система, метод платежа выбранный покупателем в Платежной форме | + | * Способ - способ оплаты, под этим термином подразумевается: платежная система; метод платежа выбранный покупателем в "Платежной форме"; онлайновый - способ платежа, выполняемый в текущем времени с проверкой вводимых данных; офлайновый - способ оплаты по которому невозможно отклонить оплату в случае ввода неверных данных (например: терминалы, банковские переводы). |
- | онлайновый способ платежа, выполняемый в текущем времени с проверкой вводимых данных. | + | * Кошелек - кошелек в Onpay, специально создаваемый для возврата ошибочных платежей. |
- | офлайновый способ оплаты по которому невозможно отклонить оплату в случае ввода неверных данных (например: терминалы, банковские переводы). | + | |
- | Кошелек = кошелек в Onpay, специально создаваемый для возврата ошибочных платежей | + | |
- | ^ режим pay_mode ^ Сумма относительно суммы в ордере ^ способ верный, онлайновый ^ способ не тот, онлайновый ^ способ верный, офлайновый ^ способ не тот, офлайновый ^ | + | ^ режим pay_mode ^ Сумма относительно суммы в ордере ^ Способ верный, онлайновый ^ Способ не тот, онлайновый ^ Способ верный, офлайновый ^ Способ не тот, офлайновый ^ |
| FIX | НЕДОплата | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | В Кошелек в RUR | В Кошелек в RUR | | | FIX | НЕДОплата | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | В Кошелек в RUR | В Кошелек в RUR | | ||
| FIX | Сумма как в ордере или до 5 руб. больше | Зачисление продавцу | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | Зачисление | Зачисление (в валюте фактического зачисления) | | | FIX | Сумма как в ордере или до 5 руб. больше | Зачисление продавцу | Отказ (ошибка «получатель денег запретил прием платежей с произвольными параметрами») | Зачисление | Зачисление (в валюте фактического зачисления) | | ||
Строка 98: | Строка 97: | ||
Во всех случаях в режиме и fix и free деньги зачисляются в Кошелек. | Во всех случаях в режиме и 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 дополнительные параметры НЕ поддерживают. | ||
+ | ** | ||
==== Включение защиты параметров ==== | ==== Включение защиты параметров ==== | ||
Строка 105: | Строка 127: | ||
Формат строки для контрольной подписи (без кавычек): «pay_mode;price;ticker;pay_for;convert;secret_key» \\ | Формат строки для контрольной подписи (без кавычек): «pay_mode;price;ticker;pay_for;convert;secret_key» \\ | ||
- | Например: fix;100.0;WMR;123;yes;secret_key , где:\\ | + | Например: fix;100.0;WMR;123;yes;secret_key , где: |
- | pay_mode - строка "fix"\\ | + | * pay_mode - строка "fix". |
- | price - переданный параметр, цена (Обращайте внимание на формат данных, входящих в подпись! Сумма в формате #.# - один знак после точки, даже если число не имеет дробной части)\\ | + | * price - переданный параметр, цена (Обращайте внимание на формат данных, входящих в подпись! Сумма в формате #.# - один знак после точки, даже если число не имеет дробной части). |
- | ticker - валюта заказа, в которой магазин должен получить деньги, передавать в ссылке не обязательно, берется из настроек магазина по умолчанию.\\ | + | * ticker - валюта заказа, в которой магазин должен получить деньги, передавать в ссылке не обязательно, берется из настроек магазина по умолчанию. |
- | pay_for - переданный параметр\\ | + | * pay_for - переданный параметр. |
- | convert - переданный параметр, передавать в ссылке не обязательно (Даже если вы не указываете параметр “convert” в ссылке, то в строке для формирования подписи md5 необходимо указать “yes” (без кавычек) на месте этого параметра) \\ | + | * convert - переданный параметр, передавать в ссылке не обязательно (Даже если вы не указываете параметр “convert” в ссылке, то в строке для формирования подписи md5 необходимо указать “yes” (без кавычек) на месте этого параметра). |
- | secret_key - секретный ключ API магазина, задаваемый в настройках в личном кабинете.\\ | + | * secret_key - секретный ключ API магазина, задаваемый в настройках в личном кабинете. |
Для защиты от "свободных" платежей (если они не нужны), необходимо включить в личном кабинете флаг "Запрет платежей без API", если эта функция будет включена, то плательщик не сможет создать "свободный" ордер, а только "фиксированный", у которого включена проверка MD5. | Для защиты от "свободных" платежей (если они не нужны), необходимо включить в личном кабинете флаг "Запрет платежей без API", если эта функция будет включена, то плательщик не сможет создать "свободный" ордер, а только "фиксированный", у которого включена проверка MD5. |