Различия

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

--- api-for-pay-form [2015/10/19 10:04]
admin
+++ api-for-pay-form [2015/10/19 11:25] (текущий)
admin
@@ Строка 6: / Строка 6: @@
 ) **Запрос на получение информации о платежной форме** (курсы обмена, комиссии, списки платежных интерфейсов, получение локализации ключей...)
-GET запрос отправляется в формате JSON на url идентичный адресу платежной формы - https://secure.onpay.ru/pay/merchant_login
+**GET запрос** отправляется в формате JSON на url идентичный адресу платежной формы - https://secure.onpay.ru/pay/merchant_login
 ) **Запрос на создание платежного ордера**. Ответом является инструкция для дальнейшего перенаправления плательщика для оплаты или показа инструкции.
-POST запрос отправялется в формате json на url - https://secure.onpay.ru/pay
+**POST запрос** отправялется в формате JSON на url - https://secure.onpay.ru/pay
 Шаг получения информации является НЕобязательным для создания платежного ордера. Но он необходим для получения свежих данных, в том числе о курсах обмена. Сайт магазина может делать его раз в сутки, либо после получения ошибки об изменении курса обмена, либо при изменении настроек платежных систем в своем кабинете.
 ===== Получение информации о платежной форме =====
-Для получения информации следует отправить GET запрос в формате JSON на URL " https://secure.onpay.ru/pay/merchant_login", где merchant_login - идентификатор сайта.
+Для получения информации следует отправить **GET запрос** в формате JSON на URL " https://secure.onpay.ru/pay/merchant_login", где merchant_login - идентификатор сайта.\\
 В ответ будет получен JSON следующего формата:
-''{
+  {
   "paysystem_interfaces":{...},
   "paysystems":{...},
@@ Строка 22: / Строка 22: @@
   "phone_codes":{...},
   "locales":{...}
-}''
+  }
 в случае ошибки вида:
-''{
+  {
   "errors":{"key":["text1","text2",...]},
-}''
+  }
-где key - ключ ошибки, значение которого массив текстовых описаний ошибок(может быть одно или несколько).
+где key - ключ ошибки, значение которого массив текстовых описаний ошибок(может быть одно или несколько - text1, text2...).\\
+От сервера Onpay придет JSON с ответом (успешный или с ошибкой).\\
+\\
 Пример ответа с ошибкой:
-''{
+  {
     "errors": {
         "recipient": [
-            "Для использования API платежной формы необходимо обратится в техническую поддержку Onpay для активации данного функционала для магазина"
+            "Для использования API платежной формы необходимо обратиться в техническую поддержку Onpay для активации данного функционала для магазина"
         ]
     }
-}''
+  }
 Пример полного успешного ответа см. в разделе "Пример расчета параметров"
@@ Строка 43: / Строка 44: @@
 ==== Описание параметров ====
 === paysystem_interfaces ===
-Значением является hash, ключами которого являются названия доступных и включенных интерфейсов оплаты(данные значения для использования в запросе на создание ордера как "interface_ticker")\\
+Значением является hash, ключами которого являются названия доступных и включенных интерфейсов оплаты (данные значения нужны для использования в запросе на создание ордера для параметра "interface_ticker")\\
 Значениями ключей-интерфейсов является также хеш, содержащий 2 ключа:\\
-"**paysystem**" - для определения комиссий и курсов обмена, а также списка дополнительных полей,
+"**paysystem**" - 3-буквенный код платежной системы (к нему привязаны комиссии, курсы, а также список дополнительных полей подлежащих заполнению пользователем - вся эта информация находится в соответствующих справочниках)\\
 "**logo**" - урл логотипа для интерфейса.
 Пример:
-''"paysystem_interfaces":{
+"paysystem_interfaces":
+  {
     "SBR":{
       "paysystem":"BBR",
       "logo":"/assets/payment_systems/logo/SBR.png"
     }
-}''
+  }
 === paysystems ===
@@ Строка 62: / Строка 64: @@
 "**currency_code**" - 3-ех символьный код валюты (для отображения плательщику, если необходимо)\\
 "**convert_to**" - платежная система, в которую будет осуществлена автоконвертация, если не указана валюта в которую должен быть сконвертирован платеж. НЕ во все системы можно зачислять средства, поэтому в качестве значения поля "ticker" в запросе на создание ордера необходимо использовать только значения из данного поля, а не любую из платежных систем.\\
-"**commissions**" - комиссии платежной системы, содержит 3 параметра: pip - процентная комиссия, pif - фиксированная комиссия, mci - минимальная комиссия.\\
+"**commissions**" - комиссии платежной системы, содержит 3 параметра:\\
+**pip** - процентная комиссия,\\
+**pif** - фиксированная комиссия,\\
+**mci** - минимальная комиссия.\\
 "**exchange_rates**" - курсы обмена, представленные в виде хеша вида: {"USD":0.01597,"RUR":1.0}. Такая запись означает, что одна единица в данной платежной системе может быть обменяна на 0.01597 единиц в валюте USD или на 1.0 в валюте RUR.\\
 Пример:
-''    "BBR":{
+      "BBR":{
       "min":100.0,
       "max":150000.0,
@@ Строка 81: / Строка 86: @@
       }
     }
-''
 === additional_params ===
@@ Строка 87: / Строка 92: @@
 Пример:
+"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:\\
@@ Строка 104: / Строка 114: @@
 Список полей находится по ключу "**data**", кроме данного ключа могут присутствовать другие, а именно именования интерфейсов оплаты.
-Пример выше расшифровывается как:
+Пример выше расшифровывается как:\\
-''Для платежной системы BBR 4 дополнительных поля: first_name, middle_name, last_name, address.
+Для платежной системы BBR 4 дополнительных поля: first_name, middle_name, last_name, address.\\
-Следовательно для всех интерфейсов данной системы их необходимо передавать, за исключением платежного интерфейса "SBR" (передан отдельным ключом).''
+Следовательно для всех интерфейсов данной системы их необходимо передавать, за исключением платежного интерфейса "SBR" (передан отдельным ключом).\\
+\\
 Следует отметить, что у ключа интерфейса может быть свой вложенный ключ "data", в этом случае для данного интерфейса используются поля из вложенного hash-а (запись в том же формате)
 Значение поля "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",
@@ Строка 141: / Строка 151: @@
     "tr":"+90",
     "na":"+"
-  }''
+  }
 где ключ - двухсимвольное наименование страны, значение - код телефона для данной страны.
@@ Строка 149: / Строка 159: @@
 === locales ===
 значением является hash вида:
-''{
+  {
     "ru":"https://secure.onpay.ru/pay_app/i18n/ru.json",
     "en":"https://secure.onpay.ru/pay_app/i18n/en.json"
-  }''
+  }
 где ключ - двухсимвольное обозначение языка перевода, значение - url для получения файла локализации.
@@ Строка 159: / Строка 169: @@
 Пример:
 Если требуется отобразить ключ локализации "user_phone.errors.required" то нужно использовать значение из файла локализации
+  { "user_phone":{
-''
-{ "user_phone":{
   "errors":{
     "required":"This field is required"
   }
-}''
+  }
 ==== Пример расчета параметров ====
 === Пример полного ответа на запрос получения информации ===
-{
+  {
   "paysystem_interfaces":{
     "SBR":{
@@ Строка 260: / Строка 268: @@
     "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".\\
@@ Строка 273: / Строка 281: @@
 === Пример расчета для интерфейса оплаты SBR ===
-**1) SBR принадлжеит платежной системе BBR, значит для расчета суммы берем курсы обмена из этой платежной системы**
+**1) SBR принадлежит платежной системе BBR, значит для расчета суммы берем курсы обмена из этой платежной системы**
-''"exchange_rates":{
+  "exchange_rates":
-        "USD":0.01597,
+  {"USD":0.01597,
-        "RUR":1.0,
+  "RUR":1.0,}
-}''
@@ Строка 286: / Строка 293: @@
 **3) Считаем сумму в BBR, которая должна поступить от плательщика в платежную систему, чтобы в систему Onpay поступило 6261.740763932373 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-ого знака)
@@ Строка 301: / Строка 308: @@
 **5) Проверяем сумму на ограничения платежного интерфейса**
 Берем ограничения от платежной системы BBR
-''{
+  {
   "min":100.0,
   "max":150000.0
-}''
+  }
 значение 6330.04 находится в данном диапозоне, следовательно плательщик сможет оплатить через данный способ (в случае превышения лимита НЕ стоит предлагать плательщику платежный интерфейс. У разных интерфейсов разные ограничения)
@@ Строка 311: / Строка 318: @@
 **7) Формируем данные для запроса на создание платежного ордера**
-''{
+  {
   "ticker":"USD",
   "interface_ticker":"SBR",
   "pay_amoun":6330.04,
   "receive_amount":100.0
-}''
+  }
 **8) Отображаем плательщику форму для ввода дополнительных полей**
 В случае SBR - таковых нет.\\
 в случае BBR:\\
-''{
+{
   "first_name":"Vladimir",
   "middle_name":"Ilyich",
   "last_name","Lenin",
   "address":"Mausoleum"
-}''
+}
 Другие обязательные поля смотреть в разделе *Создание ордера*
@@ Строка 340: / Строка 347: @@
 | interface_ticker | string | Название способа оплата (через который плательщик будет платить) |
 | recipient | string | идентификатор магазина |
-| pay_mode | string | тип платежа, fix, free или inv |
+| pay_mode | string | тип платежа, fix или free |
 | pay_amount | float | сумма, которую должен заплатить плательщик способом interface_ticker (может быть пустым, в этом слечае будет рассчитано автоматически, в зависимости от receive_amount) |
 | receive_amount | float | сумма, которую должен будет получить магазин в валюте ticker |
@@ Строка 355: / Строка 362: @@
 === Пример запроса ===
 Пример запроса на создание ордера через системы BBR, которая имеет 4 дополнительных поля(first_name, last_name, middle_name, address):
-{
+  {
   "user_email":"test@email.com",
   "pay_for":"test_pay_for",
@@ Строка 373: / Строка 380: @@
     "number":"9001234567"
   }
-}
+  }
-Маски для первичной валидации и сообщения об ошибках для дополнительных полей можно получить при помощи запроса информации.
+Маски для первичной валидации и сообщения об ошибках для дополнительных полей можно получить при помощи запроса информации.\\
-Значениями поля "user_phone.code" может быть одно из значений кодов стран из запроса на получение информации. Для некоторых платежных интерфейсов список кодов ограничивается (см. в разделе *additional_params*)
+Значениями поля "user_phone.code" может быть одно из значений кодов стран из запроса на получение информации. Для некоторых платежных интерфейсов список кодов ограничивается (см. в разделе *additional_params*)\\
 ==== Ответ ====
 === Формат и общее описание ===
 Сервер Onpay отвечает в формате JSON
-''{
+  {
   "redirect_to": {},
   "po_psi_data_request": {},
   "errors": {}
-}''
+  }
-Где, одно из полей, errors, redirect_to или po_psi_data_request НЕ пустое(НЕ пустыми могут быть несколько полей).
+Где одно или несколько из полей из **errors**, **redirect_to** или **po_psi_data_request** НЕ пустое(-ые).
 Алгоритм обработки ответа:\\
-**Если НЕ пустое "errors"**\\
+**Если НЕ пустое "errors"** сайт магазина должен отобразить ошибки плательщику и переформировать данные для отправки (пример: в случае отсутствия обязательного поля - заполнить данное поле). Подробнее см. в разделе "errors")\\
-  сайт магазина должен отобразить ошибки плательщику и переформировать данные для отправки(пример: в случае отсутствия обязательного поля - заполнить данное поле). (подробнее читать в разделе "errors")\\
+**Иначе** (ордер успешно создан, и мы смотрим на два остальных поля redirect_to или po_psi_data_request)\\
-Иначе
+\\
-  **Если НЕ пустое "redirect_to"**
+**Если НЕ пустое "redirect_to"** сайт магазина должен перенаправить плательщика на url, указанный в этом параметре. (подробнее читать в разделе "redirect_to")\\
-    сайт магазина должен перенаправить плательщика на url, указанный в этом параметре. (подробнее читать в разделе "redirect_to")
+**Иначе** сайт магазина, должен сформировать форму из данных, содержащихся в поле "po_psi_data_request", и перенаправить пользователя сабмитом данной формы. (подробнее читать в разделе "po_psi_data_request")\\
-  Иначе
+Чем отличают **redirect_to** или **po_psi_data_request**.\\
-    сайт магазина, должен сформировать форму из данных, содержащихся в поле "po_psi_data_request", и перенаправить пользователя сабмитом данной формы. (подробнее читать в разделе "po_psi_data_request")
+**redirect_to** используется, когда перенаправление покупателя нужно осуществить запросом типа GET\\
+**po_psi_data_request** используется, когда перенаправление покупателя нужно осуществить запросом типа POST\\.
+Пример платежной системы с типом GET киви с выводом инструкции.\\
+Пример платежной системы с типом POST - UNR.\\
+Информацию о типе перенаправления (GET/POST) вы получите в ответ на запрос о создании ордера.
 === errors ===
 в качестве значения errors выступает hash.
 Примеры:
-    ''"errors": {
+    "errors": {
         "receive_amount": [
-            "Ошибка в курсе обмена. Возможно курс обмена изменился. Пожалуйста, попробуйте продолжить операцию еще раз. <a href='http://wiki.onpay.ru/doku.php?id=oshibki#ошибки_платежной_формы' target='_blank'>Подробнее</a>"
+            "Ошибка в курсе обмена. Возможно курс обмена изменился. Пожалуйста, попробуйте продолжить операцию еще раз.
+            <a href='http://wiki.onpay.ru/doku.php?id=oshibki#ошибки_платежной_формы' target='_blank'>Подробнее</a>"
         ]
-    }''
+    }
-    ''"errors": {
+--
+    "errors": {
         "first_name": [
             "pay_form_add_p_message.first_name"
@@ Строка 415: / Строка 427: @@
             "pay_form_add_p_message.last_name"
         ]
-    }''
+    }
-Ключ ошибки - это поле, значение которого неверно.\\
+**Ключ ошибки** - это поле, значение которого неверно.\\
-Значение - массив текстов ошибок.\\
+**Значение** - массив текстов ошибок.\\
 Иногда текст ошибки представлен в виде ключа для локализации, пример: "pay_form_add_p_message.first_name". В таких случаях перевод нужно брать из файлов локализации, url которых можно получить при помощи запроса получения информации.\\
 \\
@@ Строка 425: / Строка 437: @@
 === redirect_to ===
 в качестве значения redirect_to выступает hash вида
-''{
+  {
   "url": "https://secure.onpay.ru/1234567890/instruction",
   "...": "..."
-}''
+  }
 сайт магазина должен осуществить перенаправление плательщика GET запросом на URL, указанный как значение ключа "url". В ответе могут присутствовать другие ключи, они являются служебными и должны игнорироваться сайтом магазина.
@@ Строка 451: / Строка 463: @@
             "order_id"="123"
             "sum"=103.09
-При этом сайт магазина должен передавать значения полей в неизменяемом виде(соблюдая типы данных и не применяя дополнительных функций(округление, изменение регистра))
+При этом сайт магазина должен передавать значения полей в неизменяемом виде (соблюдая типы данных и не применяя дополнительных функций(округление, изменение регистра))
-hash кроме ключей route и data может содержать дополнительные ключи, сайт магазина должен игнорировать их.
+Данный hash кроме ключей route и data может содержать дополнительные ключи, сайт магазина должен игнорировать их.

Onpay.ru Wiki

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

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

Различия

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