Различия

Здесь показаны различия между двумя версиями данной страницы.

--- api-for-pay-form [2015/10/19 09:56]
admin
+++ api-for-pay-form [2015/10/19 10:21]
admin
@@ Строка 1: / Строка 1: @@
 ====== API платежной формы ======
 ===== Общее описание =====
 Взаимодействие с платежным агрегатором Onpay возможно без перенаправления плательщика на платежную форму.
@@ Строка 16: / Строка 14: @@
 ===== Получение информации о платежной форме =====
 Для получения информации следует отправить GET запрос в формате JSON на URL " https://secure.onpay.ru/pay/merchant_login", где merchant_login - идентификатор сайта.
 В ответ будет получен JSON следующего формата:
-''{
+  {
   "paysystem_interfaces":{...},
   "paysystems":{...},
@@ Строка 25: / Строка 22: @@
   "phone_codes":{...},
   "locales":{...}
-}''
+  }
 в случае ошибки вида:
-''{
+  {
   "errors":{"key":["text1","text2",...]},
-}''
+  }
 где key - ключ ошибки, значение которого массив текстовых описаний ошибок(может быть одно или несколько).
 Пример ответа с ошибкой:
-''{
+  {
     "errors": {
         "recipient": [
@@ Строка 40: / Строка 37: @@
         ]
     }
-}''
+  }
 Пример полного успешного ответа см. в разделе "Пример расчета параметров"
 ==== Описание параметров ====
 === paysystem_interfaces ===
 Значением является hash, ключами которого являются названия доступных и включенных интерфейсов оплаты(данные значения для использования в запросе на создание ордера как "interface_ticker")\\
 Значениями ключей-интерфейсов является также хеш, содержащий 2 ключа:\\
@@ Строка 54: / Строка 49: @@
 Пример:
-''"paysystem_interfaces":{
+"paysystem_interfaces":
+  {
     "SBR":{
       "paysystem":"BBR",
       "logo":"/assets/payment_systems/logo/SBR.png"
     }
-}''
+  }
 === paysystems ===
 Значением является hash, содержащий следующие ключи:\\
 "**min**" - сумма минимального платежа через данный способ в единицах данной системы\\
@@ Строка 72: / Строка 67: @@
 Пример:
-''    "BBR":{
+      "BBR":{
       "min":100.0,
       "max":150000.0,
@@ Строка 87: / Строка 82: @@
       }
     }
-''
-=== additional_params ===
+=== additional_params ===
 Значением является hash, ключи которого - именование платежной системы
 Пример:
+"BBR":
-''"BBR":{
+  {
-      "data":[
+      "data":
-        {"name":"first_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']{2,30}$","label":"pay_form_add_p_label.first_name","message":"pay_form_add_p_message.first_name"},
+        [
-        {"name":"middle_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']{2,30}$","label":"pay_form_add_p_label.middle_name","message":"pay_form_add_p_message.middle_name"},
+        {"name":"first_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']
-        {"name":"last_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']{2,30}$","label":"pay_form_add_p_label.last_name","message":"pay_form_add_p_message.last_name"},
+        {2,30}$","label":"pay_form_add_p_label.first_name","message":"pay_form_add_p_message.first_name"},
-        {"name":"address","regexp":"^[a-zA-Z\\s'0-9,\\-А-Яа-яЁё,\\d\\/\\\\.\\,\"]{4,250}$","label":"pay_form_add_p_label.address","message":"pay_form_add_p_message.address"}
+        {"name":"middle_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']
+        {2,30}$","label":"pay_form_add_p_label.middle_name","message":"pay_form_add_p_message.middle_name"},
+        {"name":"last_name","regexp":"^[A-ZА-Яa-zа-яёЁ\\-\\s']
+        {2,30}$","label":"pay_form_add_p_label.last_name","message":"pay_form_add_p_message.last_name"},
+        {"name":"address","regexp":"^[a-zA-Z\\s'0-9,\\-А-Яа-яЁё,\\d\\/\\\\.\\,\"]
+        {4,250}$","label":"pay_form_add_p_label.address","message":"pay_form_add_p_message.address"}
       ],
       "SBR":[]
-    }''
+    }
-Значением может быть null или hash
+Значением может быть null или hash:\\
-Если null - значит для данной платежной системы нет дополнительных полей.
+**Если null** - значит для данной платежной системы нет дополнительных полей.\\
-Если hash - значит в запросе на создание платежного ордера должны присутствовать перечисленные поля.
+**Если hash** - значит в запросе на создание платежного ордера должны присутствовать перечисленные поля.\\
-Список полей находится по ключу "data", кроме данного ключа могут присутствовать другие, а именно именования интерфейсов оплаты.
+Список полей находится по ключу "**data**", кроме данного ключа могут присутствовать другие, а именно именования интерфейсов оплаты.
 Пример выше расшифровывается как:
@@ Строка 119: / Строка 118: @@
 Значение поля "data" - массив hash-ей, каждый из которых описывает одно дополнительное поле.
-hash описания может содержать следующие ключи:
+hash описания может содержать следующие ключи:\\
-*name* - название параметра, именно оно должно быть использовано при запросе на создание ордера.
+**name** - название параметра, именно оно должно быть использовано при запросе на создание ордера.\\
-*regexp* - regex для первичной валидации значения на стороне сайта магазина.
+**regexp** - regex для первичной валидации значения на стороне сайта магазина.\\
-*label* - ключ локализации (перевод брать из файлов локализации, см. в разделе "locales"), который должен быть использован для отображения плательщику названия поля.
+**label** - ключ локализации (перевод брать из файлов локализации, см. в разделе "locales"), который должен быть использован для отображения плательщику названия поля.\\
-*message* - ключ локализации (перевод брать из файлов локализации, см. в разделе "locales"), который должен быть использован для отображения ошибки плательщику при нарушении regex-а.
+**message** - ключ локализации (перевод брать из файлов локализации, см. в разделе "locales"), который должен быть использован для отображения ошибки плательщику при нарушении regex-а.\\
-*countries* - данный ключ, присутствует только у полей с name равным "user_phone", значение данного поля - список стран, с телефонов которых можно платить данным способом. (Полный список стран см. в разделе "phone_codes"). При выборе плательщиком данного способа список возможных кодов стран должен быть ограничен.
+**countries** - данный ключ, присутствует только у полей с name равным "user_phone", значение данного поля - список стран, с телефонов которых можно платить данным способом. (Полный список стран см. в разделе "phone_codes"). При выборе плательщиком данного способа список возможных кодов стран должен быть ограничен.\\
-*type* - данный ключ указывает тип дополнительного поля(если ключ отсутствует, то "input type='text'"). может принимать значение "checkbox", в данном случае поле regexp будет равно "true". Это означает что валидное значение параметра в запросе на создание ордера будет строка "true", а плательщику в форме должен отображаться checkbox.
+**type** - данный ключ указывает тип дополнительного поля(если ключ отсутствует, то "input type='text'"). может принимать значение "checkbox", в данном случае поле regexp будет равно "true". Это означает что валидное значение параметра в запросе на создание ордера будет строка "true", а плательщику в форме должен отображаться checkbox.\\
-*hint* - содержит ключ локализации подсказки к полю. Перевод должен быть отображен плательщику рядом с полем. (может быть пустым, в данном случае отображать не следует)
+**hint** - содержит ключ локализации подсказки к полю. Перевод должен быть отображен плательщику рядом с полем. (может быть пустым, в данном случае отображать не следует)
 === phone_codes ===
 Значением является hash вида:
-''{
+  {
     "ru":"+7",
     "ua":"+38",
@@ Строка 149: / Строка 147: @@
     "tr":"+90",
     "na":"+"
-  }''
+  }
 где ключ - двухсимвольное наименование страны, значение - код телефона для данной страны.
@@ Строка 158: / Строка 154: @@
 === locales ===
 значением является hash вида:
-''{
+  {
     "ru":"https://secure.onpay.ru/pay_app/i18n/ru.json",
     "en":"https://secure.onpay.ru/pay_app/i18n/en.json"
-  }''
+  }
 где ключ - двухсимвольное обозначение языка перевода, значение - url для получения файла локализации.
@@ Строка 170: / Строка 164: @@
 Пример:
 Если требуется отобразить ключ локализации "user_phone.errors.required" то нужно использовать значение из файла локализации
+  { "user_phone":{
-''
-{ "user_phone":{
   "errors":{
     "required":"This field is required"
   }
-}''
+  }
 ==== Пример расчета параметров ====
 === Пример полного ответа на запрос получения информации ===
+  {
-{
   "paysystem_interfaces":{
     "SBR":{
@@ Строка 278: / Строка 264: @@
     "en":"https://secure.onpay.ru/pay_app/i18n/en.json"
   }
-}
+  }
+В данном случае сайт мерчанта должен отобразить плательщику 3 способа оплаты (из раздела "paysystem_interfaces"): "SBR", "BBR" и "USD" с логотипами, ссылки которых указаны в том же разделе.\\
+Названия должны быть взяты из нужного файла локализации по ключам "paysystem_interface.SBR.name", "paysystem_interface.BBR.name", "paysystem_interface.USD.name". В качестве доп описания можно использовать ключи вида  "paysystem_interface.XXX.description".\\
-В данном случае сайт мерчанта должен отобразить плательщику 3 способа оплаты (из раздела "paysystem_interfaces"): "SBR", "BBR" и "USD" с логотипами, ссылки которых указаны в том же разделе.
+\\
-Названия должны быть взяты из нужного файла локализации по ключам "paysystem_interface.SBR.name", "paysystem_interface.BBR.name", "paysystem_interface.USD.name". В качестве доп описания можно использовать ключи вида  "paysystem_interface.XXX.description".
+Одно из значений "SBR", "BBR", "USD" должно быть использовано в качестве значения параметра "interface_ticker" в запросе на создание ордера.\\
+\\
-Одно из значений "SBR", "BBR", "USD" должно быть использовано в качестве значения параметра "interface_ticker" в запросе на создание ордера.
+Из hash-а "paysystems" из полей "convert_to" получаем возможный список значений для поля "ticker" запроса на создание платежной формы. В нашем случае это "RUR" и "USD".\\
+\\
-Из hash-а "paysystems" из полей "convert_to" получаем возможный список значений для поля "ticker" запроса на создание платежной формы. В нашем случае это "RUR" и "USD".
+Если плательщик выберет вариант "BBR" или "USD" то он также должен заполнить соответствующие дополнительные поля, для способа "SBR" их нет.\\
+\\
-Если плательщик выберет вариант "BBR" или "USD" то он также должен заполнить соответствующие дополнительные поля, для способа "SBR" их нет.
 Если магазину необходимо получить 100 USD (в запросе на создание платежного ордера поля ticker="USD", receive_amount=100.0), то он должен рассчитать сумму, которую должен заплатить плательщик через интерфейс оплаты.
 === Пример расчета для интерфейса оплаты SBR ===
+**1) SBR принадлжеит платежной системе BBR, значит для расчета суммы берем курсы обмена из этой платежной системы**
-*1) SBR принадлжеит платежной системе BBR, значит для расчета суммы берем курсы обмена из этой платежной системы*
+  "exchange_rates":
+  {"USD":0.01597,
-''"exchange_rates":{
+  "RUR":1.0,}
-        "USD":0.01597,
-        "RUR":1.0,
-}''
-*2) Считаем сумму в BBR, которая должна поступить в систему Onpay для обмена на 100 USD*
+**2) Считаем сумму в BBR, которая должна поступить в систему Onpay для обмена на 100 USD**
 сумма = 100 / 0.01597 = 6261.740763932373
-*3) Считаем сумму в BBR, которая должна поступить от плательщика в платежную систему, чтобы в систему Onpay поступило 6261.740763932373 BBR*
+**3) Считаем сумму в BBR, которая должна поступить от плательщика в платежную систему, чтобы в систему Onpay поступило 6261.740763932373 BBR*
-Используем комиссии платежной системы BBR
+Используем комиссии платежной системы BBR**
-''{
+  {
         "pip":1.0,
         "pif":5.0,
         "mci":0.0
-}''
+  }
 сумма = (6261.740763932373 + pif) / (1 - (pip / 100))  (обратный расчет комиссии) = (6261.740763932373 + 5.0) / (1 - (1.0 / 100))  = 6330.041175689265 = 6330.04 (математическое округление до 2-ого знака)
-*4) Проверяем минимальную комиссию*
+**4) Проверяем минимальную комиссию**
-комиссия = 6330.04 - 6261.75 = 68.31
+комиссия = 6330.04 - 6261.75 = 68.31\\
-если комиссия меньше чем mci, то делаем пересчет суммы как:
+если комиссия меньше чем mci, то делаем пересчет суммы как:\\
-сумма до обмена + mci (6261.75 + mci)
+сумма до обмена + mci (6261.75 + mci)\\
-в нашем случае это не требуется, так как рассчитанная комиссия больше чем значение минимальной.
+в нашем случае это не требуется, так как рассчитанная комиссия больше чем значение минимальной.\\
-*5) Проверяем сумму на ограничения платежного интерфейса*
+**5) Проверяем сумму на ограничения платежного интерфейса**
 Берем ограничения от платежной системы BBR
-''{
+  {
   "min":100.0,
   "max":150000.0
-}''
+  }
 значение 6330.04 находится в данном диапозоне, следовательно плательщик сможет оплатить через данный способ (в случае превышения лимита НЕ стоит предлагать плательщику платежный интерфейс. У разных интерфейсов разные ограничения)
-*6) Результирующая сумма к оплате*
+**6) Результирующая сумма к оплате**
 Для получения магазином 100 USD плательщик может заплатить 6330.04 BBR
-*7) Формируем данные для запроса на создание платежного ордера*
+**7) Формируем данные для запроса на создание платежного ордера**
-''{
+  {
   "ticker":"USD",
   "interface_ticker":"SBR",
   "pay_amoun":6330.04,
   "receive_amount":100.0
-}''
+  }
+**8) Отображаем плательщику форму для ввода дополнительных полей**
-*8) Отображаем плательщику форму для ввода дополнительных полей*
+В случае SBR - таковых нет.\\
-В случае SBR - таковых нет.
+в случае BBR:\\
-в случае BBR:
+{
-''{
+  "first_name":"Vladimir",
-  "first_name":"Test",
+  "middle_name":"Ilyich",
-  "middle_name":"Testovich",
+  "last_name","Lenin",
-  "last_name","Testov",
+  "address":"Mausoleum"
-  "address":"Address"
+}
-}''
 Другие обязательные поля смотреть в разделе *Создание ордера*
 ===== Создание ордера =====
 ==== Запрос ====
 === Обязательные параметры ===
 Для создания ордера необходимо отправить POST запрос на адрес https://secure.onpay.ru/pay в формате JSON со следующими обязательными параметрами:
 | Название | Тип | Значение и описание |
@@ Строка 382: / Строка 358: @@
 === Пример запроса ===
 Пример запроса на создание ордера через системы BBR, которая имеет 4 дополнительных поля(first_name, last_name, middle_name, address):
+  {
-{
   "user_email":"test@email.com",
   "pay_for":"test_pay_for",
@@ Строка 402: / Строка 376: @@
     "number":"9001234567"
   }
-}
+  }
 Маски для первичной валидации и сообщения об ошибках для дополнительных полей можно получить при помощи запроса информации.
 Значениями поля "user_phone.code" может быть одно из значений кодов стран из запроса на получение информации. Для некоторых платежных интерфейсов список кодов ограничивается (см. в разделе *additional_params*)
 ==== Ответ ====
 === Формат и общее описание ===
 Сервер Onpay отвечает в формате JSON
-''{
+  {
   "redirect_to": {},
   "po_psi_data_request": {},
   "errors": {}
-}''
+  }
 Где, одно из полей, errors, redirect_to или po_psi_data_request НЕ пустое(НЕ пустыми могут быть несколько полей).
-Алгоритм обработки ответа:
+Алгоритм обработки ответа:\\
-Если НЕ пустое "errors"
+**Если НЕ пустое "errors"** сайт магазина должен отобразить ошибки плательщику и переформировать данные для отправки(пример: в случае отсутствия обязательного поля - заполнить данное поле). (подробнее читать в разделе "errors")\\
-  сайт магазина должен отобразить ошибки плательщику и переформировать данные для отправки(пример: в случае отсутствия обязательного поля - заполнить данное поле). (подробнее читать в разделе "errors")
+**Иначе**\\
-Иначе
+\\
-  Если НЕ пустое "redirect_to"
+**Если НЕ пустое "redirect_to"** сайт магазина должен перенаправить плательщика на url, указанный в этом параметре. (подробнее читать в разделе "redirect_to")\\
-    сайт магазина должен перенаправить плательщика на url, указанный в этом параметре. (подробнее читать в разделе "redirect_to")
+**Иначе** сайт магазина, должен сформировать форму из данных, содержащихся в поле "po_psi_data_request", и перенаправить пользователя сабмитом данной формы. (подробнее читать в разделе "po_psi_data_request")\\
-  Иначе
-    сайт магазина, должен сформировать форму из данных, содержащихся в поле "po_psi_data_request", и перенаправить пользователя сабмитом данной формы. (подробнее читать в разделе "po_psi_data_request")
 === errors ===
 в качестве значения errors выступает hash.
 Примеры:
-    ''"errors": {
+    "errors": {
         "receive_amount": [
             "Ошибка в курсе обмена. Возможно курс обмена изменился. Пожалуйста, попробуйте продолжить операцию еще раз. <a href='http://wiki.onpay.ru/doku.php?id=oshibki#ошибки_платежной_формы' target='_blank'>Подробнее</a>"
         ]
-    }''
+    }
-    ''"errors": {
+--
+    "errors": {
         "first_name": [
             "pay_form_add_p_message.first_name"
@@ Строка 450: / Строка 416: @@
             "pay_form_add_p_message.last_name"
         ]
-    }''
+    }
-Ключ ошибки - это поле, значение которого неверно.
-Значение - массив текстов ошибок.
-Иногда текст ошибки представлен в виде ключа для локализации, пример: "pay_form_add_p_message.first_name". В таких случаях перевод нужно брать из файлов локализации, url которых можно получить при помощи запроса получения информации.
+Ключ ошибки - это поле, значение которого неверно.\\
+Значение - массив текстов ошибок.\\
+Иногда текст ошибки представлен в виде ключа для локализации, пример: "pay_form_add_p_message.first_name". В таких случаях перевод нужно брать из файлов локализации, url которых можно получить при помощи запроса получения информации.\\
+\\
 Если присутствует ключ ошибки "system", значит допущена фатальная ошибке при запросе(примеры: неверный формат, пустой запрос)
 === redirect_to ===
 в качестве значения redirect_to выступает hash вида
-''{
+  {
   "url": "https://secure.onpay.ru/1234567890/instruction",
   "...": "..."
-}''
+  }
 сайт магазина должен осуществить перенаправление плательщика GET запросом на URL, указанный как значение ключа "url". В ответе могут присутствовать другие ключи, они являются служебными и должны игнорироваться сайтом магазина.

Onpay.ru Wiki

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

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

Различия

Инструменты страницы