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

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


api-notify

Различия

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

Ссылка на это сравнение

Both sides previous revision Предыдущая версия
Следущая версия
Предыдущая версия
api-notify [2014/10/20 07:09]
admin [Описание и очередность транзакций]
api-notify [2023/09/25 07:57] (текущий)
admin [Типы API Onpay.ru]
Строка 10: Строка 10:
 Для включения работы по API, Вам нужно:​\\ Для включения работы по API, Вам нужно:​\\
 1. Активировать функцию **“Уведомление по API”** в разделе ​ Настройки Магазина в Кабинете Продавца Onpay\\ 1. Активировать функцию **“Уведомление по API”** в разделе ​ Настройки Магазина в Кабинете Продавца Onpay\\
-2. Указать **API URL** в соответствии со скриптом API на Вашем сервере.\\+2. Указать **API URL** в соответствии со скриптом API на Вашем сервере. В **API URL** возможно использование кириллицы.\\
 3. Установить секретный ключ для “уведомлений по API”, который должен быть таким же, как в скрипте на Вашем сервере,​ чтобы позволить генерацию контрольных подписей.\\ 3. Установить секретный ключ для “уведомлений по API”, который должен быть таким же, как в скрипте на Вашем сервере,​ чтобы позволить генерацию контрольных подписей.\\
  
 +Разрешается использование параметров в указываемом API URL, по которому будут приходить уведомления. При этом накладывается ограничение в виде списка зарезервированных API Onpay параметров,​ которые запрещается использовать в API URL настроек магазина. Список зарезервированных параметров прилагается:​\\
 +//​onpay_id\\
 +pay_for\\
 +order_amount\\
 +order_currency\\
 +balance_amount\\
 +balance_currency\\
 +exchange_rate\\
 +type\\
 +comment\\
 +paymentDateTime\\
 +md5//
 ====Описание и очередность транзакций==== ====Описание и очередность транзакций====
  
-\\ 
 **Onpay.ru производит 2 вида запросов к системе Продавца через API:**\\ **Onpay.ru производит 2 вида запросов к системе Продавца через API:**\\
 1. Запрос **“check”** используется,​ чтобы получить разрешение от системы Продавца на прием платежа от Клиента. После удачного получения разрешения,​ Onpay.ru одобрит платёж. С этого момента,​ если Клиент действительно производит платёж,​ Продавец может видеть его во вкладке **“Платежи”** в [[http://​wiki.onpay.ru/​doku.php?​id=cabinet|Кабинете Продавца]].\\ 1. Запрос **“check”** используется,​ чтобы получить разрешение от системы Продавца на прием платежа от Клиента. После удачного получения разрешения,​ Onpay.ru одобрит платёж. С этого момента,​ если Клиент действительно производит платёж,​ Продавец может видеть его во вкладке **“Платежи”** в [[http://​wiki.onpay.ru/​doku.php?​id=cabinet|Кабинете Продавца]].\\
 2. Запрос **“pay”** является,​ по сути, уведомлением для системы Продавца,​ о том, что для него принят платеж. После получения уведомления,​ система Продавца может автоматически отправить заказанные товары или сервисы Клиенту.\\ 2. Запрос **“pay”** является,​ по сути, уведомлением для системы Продавца,​ о том, что для него принят платеж. После получения уведомления,​ система Продавца может автоматически отправить заказанные товары или сервисы Клиенту.\\
-\\ 
-**Onpay.ru имеет несколько типов АПИ:**\\ 
-1. Основное АПИ (версия 2.0). В Кабинете продавца выбран по умолчанию (поле селектора на HTTPS 2.0).  
-2. API 1.0. Старое апи. С этим АПИ, в частности,​ работают все загружаемые модули с onpaysolutions.ru\\ 
-3. Специальное АПИ для Insales (его настройка [[insales|описана отдельно]])\\ 
-4. Гибридные АПИ для упрощения миграции (переход с [[robokassa-migration|Робокассы]] и [[interkassa-migration|Интеркассы]])\\ 
 \\ \\
 **Очередность транзакции:​**\\ **Очередность транзакции:​**\\
Строка 38: Строка 43:
 \\ \\
 Продавцы могут помечать платежи,​ как “Принятые” вручную во вкладке **“Платежи”** если API не доступен.\\ Продавцы могут помечать платежи,​ как “Принятые” вручную во вкладке **“Платежи”** если API не доступен.\\
-\\ +==== Типы API Onpay.ru ==== 
- +1. Основное АПИ (версия 2.0). В Кабинете продавца выбран по умолчанию (поле селектора на HTTPS 2.0).  
-  * [[description_of_the_api|Описание ​API]]+2. API 1.0. Старое апи. С этим АПИ, в частности,​ работают все загружаемые модули с onpaysolutions.ru\\ 
 +3. Специальное АПИ для Insales (его настройка ​[[insales|описана отдельно]])\\ 
 +4. Гибридные АПИ для упрощения миграции (переход с [[robokassa-migration|Робокассы]] и [[interkassa-migration|Интеркассы]])\\
  
 +  * **[[description_of_the_api|Описание API (2.1)]]**
 +  * [[description_of_the_old_api|Старое API (1.0)]]
   * [[Insales-api|API Insales]]   * [[Insales-api|API Insales]]
 +  * [[interkassa-migration|Миграция с Интеркассы]]
 +  * [[robokassa-migration|Миграция с Робокассы]]
 +  * [[flutter_onpay_sdk|SDK для flutter]]
  
-  * [[description_of_the_old_api|Старое API]] 
  
-======Описание запросов====== 
- 
-====check запрос==== 
- 
-На URL отправляется Post запрос со следующими параметрами:​ 
- 
-^ поле ^ формат ^ значение ^ 
-| type | string | "​check"​ | 
-| amount | float | сумма receive_amount из будущего ордера,​ то есть значение,​ которое ввел пользователь,​ или которое было передано в запросе к платежной форме в виде параметра "​price"​. Иными словами,​ это сумма, которую должен получить магазин,​ если комиссия платежной системы берется с плательщика,​ или сумма, которую должен заплатить плательщик,​ если комиссия взимается с магазина. Если платеж является свободным( не на фиксированную сумму),​ то данное поле имеет значение - 0 | 
-| order_amount | float | тоже самое, что и поле "​amount"​. | 
-| order_currency | string | 3 символа,​ обозначающие валюту. Значение берется либо из параметров ссылки,​ при переходе по которой была открыта форма, либо из настроек магазина,​ если таковых параметров не было. Список параметров,​ из которых берется значение,​ в порядке уменьшения приоритета:​ "​currency",​ "​ticker",​ "​to"​. | 
-| pay_for | string | номер платежа или его описание,​ содержит значение пришедшее в параметре платежной ссылки "​pay_for"​ или введенное плательщиков в поле на форме "​Платеж за" | 
-| md5 | string | подпись md5. Вычисляется по следующему алгоритму:​ upcase(md5(string)),​ string - это строка,​ формируемая как "​type;​pay_for;​order_amount;​order_currency;​api_key"​(без кавычек),​ где type - константа "​check",​ pay_for, order_amount и order_currency соответствуют значениям полей запроса,​ api_key - секретный ключ магазина,​ "​задаваемый в личном кабинете,​ ";"​ - символ "​точка с запятой,​ md5 - хеш-функция,​ upcase - функция приведения к верхнему регистру | 
- 
-Если URL сайта содержит параметры,​ то они тоже будут присутствовать в POST запросе. 
- 
-Пример запроса от сервера Onpay к серверу магазина:​ 
- 
- 
- POST https://​merchant_server/​script ​ 
- order_amount=100.0 ​ 
- order_currency=USD ​ 
- pay_for=123456 ​ 
- type=check ​ 
- md5=* 
- 
- 
-Сервер магазина на check-запрос возвращает следующие данные:​ 
- 
-^ поле ^ формат ^ значение ^ 
-| code | int | код результата обработки операции(значения см. ниже) | 
-| pay_for | string | ID Клиента или заказа в системе Мерчанта для которых производится этот платеж | 
-| comment | string | обычно,​ описание ошибки для внутреннего использования (например,​ протоколирования). Значение в этом поле хранится в деталях платежа,​ в интерфейсе магазина в Onpay | 
-| md5 | string | подпись md5. Вычисляется по следующему алгоритму:​ upcase(md5(string)),​ string - это строка,​ формируемая как "​type;​pay_for;​order_amount;​order_currency;​code;​secret_key_api_in"​(без кавычек),​ где type - константа "​check",​ pay_for, order_amount,​ order_currency и code соответствуют значениям полей ответа,​ api_key - секретный ключ магазина,​ задаваемый в личном кабинете, ​ ";"​ - символ "​точка с запятой,​ md5 - хеш-функция,​ upcase - функция приведения к верхнему регистру | 
- 
-Пример ответа сервера магазина серверу Onpay: 
- 
- 
- <?xml version="​1.0"​ encoding="​UTF-8"?>​ 
- <​result>​ 
- <​code><​code>​0</​code></​code>​ 
- <​pay_for>​123456</​pay_for>​ 
- <​comment>​OK</​comment>​ 
- <​md5>​*</​md5>​ 
- </​result>​ 
- 
- 
-====pay запрос==== 
- 
-На URL отправляется Post запрос со следующими параметрами:​ 
- 
-^ поле ^ формат ^ описание ^ 
-| type | string |  "​pay"​ | 
-| onpay_id | int |  номер платежа внутри системы Onpay (не является номером ордера для покупателя в формате 3хххххххх) ​ | 
-| amount | float | сумма, пришедшая от плательщика(возможно в другой платежной системе),​ при недоплате по свободному платежному ордеру,​ в этом параметре будет передано 0.0 | 
-| balance_amount | float | сумма платежа,​ которая будет зачислена магазину. ​ Исходя из значения только этого поля можно говорить о том, сколько денег действительно поступило на счет | 
-| balance_currency | string | платежная система,​ в которой прошел платеж и в которой зачислились магазину деньги | 
-| order_amount | float | в этом параметре передается сумма платежа,​ которая была заявлена в платежном ордере. То есть, если в платежном ордере установлена сумма 1500.0 рублей,​ а клиент перечислил только 100.0 рублей,​ в этом параметре будет передано 1500.0 рублей. Нельзя по данному полю сделать вывод о поступивших средствах на счет мерчанта. При недоплате по свободному платежному ордеру,​ в этом параметре будет передано 0.0 | 
-| order_currency | string | платежная система,​ в которой был создан ордер | 
-| exchange_rate | float | курс обмена между платежными системами balance_currency/​order_currency | 
-| pay_for | string | номер платежа или его описание,​ содержит значение пришедшее в параметре платежной ссылки "​pay_for"​ или введенное плательщиков в поле на форме "​Платеж за" | 
-| paymentDateTime | string | дата создания платежа в формате "​CCYY-MM-DDThh:​mm:​ssTZD"​ где TZD смещение часового пояса в формате [+-]hh:mm. | 
-| note | string | текст, описание платежа или дополнительные сведения | 
-| user_email | string | E-mail плательщика | 
-| user_phone | string | телефон плательщика,​ если он его указывал,​ иначе пустая строка | 
-| protection_code | string | код протекции платежа (если он есть) | 
-| day_to_expiry | int | количество дней действия кода протекции | 
-| paid_amount | float | сумма, которую должен был заплатить плательщик,​ без вычета комиссий платежной системы. Если у платежа нет ордера,​ то передается значение,​ равное полю "​amount"​.(ордера нет у платежей на вывод и у прямых платежей) | 
-| md5 | string | подпись md5. Вычисляется по следующему алгоритму:​ upcase(md5(string)),​ где string - это строка,​ формируемая как «type;​pay_for;​onpay_id;​order_amount;​order_currency;​api_key»(без кавычек),​ где type, pay_for, onpay_id, order_amount и order_currency соответствуют значениям полей запроса,​ api_key - секретный ключ магазина,​ задаваемый мерчантом в зеленом кабинете,​ md5 - хеш-функция,​ upcase - функция приведения к верхнему регистру. | 
- 
-Если URL сайта содержит параметры,​ то они тоже будут присутствовать в POST запросе. 
- 
-Пример запроса от сервера Onpay к серверу магазина: ​ 
- 
- POST https://​merchant_server/​script 
- onpay_id=12345 - номер платежа внутри системы onpay 
- pay_for=123456 - описание платежа (задается в платежной форме в поле pay_for) 
- amount=76.58 - сумма, заплаченная плательщиком 
- order_amount=100.0 - сумма, на которую был создан платежный ордер (задается в платежной форме в поле receive_amount) 
- order_currency=USD - валюта,​ на которую был создан платежный ордер (выбирается в платежной форме) 
- balance_amount=76.58 - сумма, которая будет зачислена на баланс мерчанта 
- balance_currency=EUR - валюта зачисления на баланс 
- exchange_rate=0.7658 - курс обмена 
- paymentDateTime=2006-03-24T19:​00:​00+03:​00 ​ - дата создания ордера 
- type=pay - тип запроса 
- md5=* - цифровая подпись 
- note=* - текст (задается в форме в поле note) 
- user_email=* - email плательщика (задается в форме в поле user_email) 
- user_phone=* - email плательщика (задается в форме в поле user_phone) 
- protection_code=* - код протекции (задается при переводе денег) 
- day_to_expiry=* - срок действия кода протекции 
- paid_amount=* - сумма, которую должен был заплатить плательщик 
- 
-Сервер магазина на pay-запрос возвращает следующие данные:​ 
- 
-^ поле ^ формат ^ значение ^ 
-| code | int | код результата обработки операции(значения см. ниже) | 
-| pay_for | string | ID Клиента или заказа в системе Мерчанта для которых производится этот платеж | 
-| comment | string | обычно,​ описание ошибки для внутреннего использования (например,​ протоколирования). Значение в этом поле хранится в деталях платежа,​ в интерфейсе магазина в Onpay | 
-| onpay_id | | транзакции (платежа) сохранённой в OnPay (должен быть таким же, как и в запросе от OnPay) | 
-| order_id | | транзакции (заказа) сохранённый в системе Мерчанта (опциональный,​ для лучшего отслеживания платежей) | 
-| md5 | string | подпись md5. Вычисляется по следующему алгоритму:​ upcase(md5(string)),​ string - это строка,​ формируемая как “type;​pay_for;​onpay_id;​order_id;​order_amount;​order_currency;​code;​secret_key_api_in”(без кавычек),​ где type - константа "​pay",​ pay_for, onpay_id, order_id, order_amount,​ order_currency и code соответствуют значениям полей ответа,​ api_key - секретный ключ магазина,​ задаваемый в личном кабинете, ​ ";"​ - символ "​точка с запятой,​ md5 - хеш-функция,​ upcase - функция приведения к верхнему регистру | 
- 
-Пример ответа скрипта мерчанта серверу OnPay: 
- 
- 
- 
- <?xml version="​1.0"​ encoding="​UTF-8"?>​ 
- <​result>​ 
- <​code>​0</​code>​ 
- <​comment>​OK</​comment>​ 
- <​onpay_id>​12345</​onpay_id>​ 
- <​pay_for>​123456</​pay_for>​ 
- <​order_id>​98765</​order_id>​ 
- <​md5>​*</​md5>​ 
- </​result>​ 
- 
- 
-==== Возможные коды завершения операции ==== 
- 
-^ Код ^ Значение ^ 
-| 0 | ОК – означает,​ что “уведомление о платеже принято” если тип запроса был “pay” или “может быть принято” если тип запроса был “check” | 
-| 2 | Только для запросов типа “check” Платёж отклонён. В этом случае Onpay.ru не примет платёж от Клиента. | 
-| 3 | Ошибка в параметрах. Onpay.ru не будет пытаться повторно послать это уведомление в систему Продавца и отметит этот платёж статусом “уведомление не доставлено в API” если тип запроса “pay”. Если тип запроса “check” – Onpay не примет этот платеж. | 
-| 7 | Ошибка авторизации. MD5 подпись неверна. | 
-| 10 | Временная ошибка. Onpay.ru попробует повторно послать это уведомление несколько раз в течение следующих 72 часов после чего пометит платёж статусом “уведомление не доставлено в API” | 
- 
-==== Упрощенный формат ==== 
- 
-Для ответов на запросы,​ сервер магазина может использовать упрощенный формат. 
- 
-В упрощенном варианте ответ возвращается в текстовой виде. Каждый параметр передается в виде name=value с новой строки. Пробельные символы между названием параметра,​ символом "​="​ и значением игнорируются. __Пустые строки не допускаются__. 
- 
-Вид упрощенного ответа:​ 
-   ​параметр1=значение1 
-   ​параметр2=значение2 
-   ... 
- 
-Пример ответа мерчанта на check-запрос:​ 
-   ​code=0 
-   ​pay_for=123456 
-   ​comment=OK 
-   ​md5=1BC29B36F623BA82AAF6724FD3B16718 
- 
-Пример ответа мерчанта на pay-запрос 
-   ​code=0 
-   ​comment=OK 
-   ​onpay_id=111 
-   ​pay_for=22222 
-   ​order_id=98765 
-   ​md5=1BC29B36F623BA82AAF6724FD3B16718 
- 
-====== Справочная информация ====== 
  
 ====Недоступность сервера магазина==== ====Недоступность сервера магазина====
  
-Если сервер магазина недоступен для “check” запроса или возвращает ​какой-либо код кроме “0”, система Onpay не примет платёж от Клиента. +Если сервер магазина недоступен для “check” запроса или возвращает НЕположительный ответ, система ​Onpay не примет платёж от Клиента.
- +
-Если сервер магазина недоступен для “pay” запроса,​ система Onpay будет повторно отправлять запрос несколько раз в течение следующих 72 часов. Повторяющиеся запросы посылаются с увеличивающимися интервалами. +
- +
-====Возвращаемые ошибки==== +
- +
-На стороне сервера Onpay в зависимости от ответа сервера магазина могут быть сгенерированы следующие ошибки (и в дальнейшем показаны в личном кабинете):​ +
- +
-7.1.1. С сервером магазина нет соединения. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.1.1 +
-7.1.2. Платеж отклонен получателем. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.1.2 +
-7.1.3. Ошибка авторизации - подпись не совпадает. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.1.3 +
-7.1.4. Магазин возвращает неверные данные - pay_for не совпадает. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.1.4 +
-7.1.5. Магазин возвращает неверные данные - неверное значение поля (code). http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.1.5 +
-7.2.1. С сервером мерчанта нет соединения. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.2.1 +
-7.2.2. Ошибка авторизации - подпись не совпадает. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.2.2 +
-7.2.3. Магазин возвращает неверные данные - pay_for не совпадает. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.2.3 +
-7.3.1. Магазин возвращает данные в некорректном формате (требуется XML или упрощенный текстовый формат). http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.1 +
-7.3.2. Магазин возвращает неверные данные - отсутствует обязательный параметр (code). http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.2 +
-7.3.3. Магазин возвращает неверные данные - отсутствует обязательный параметр (pay_for). http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.3 +
-7.3.4. Магазин возвращает неверные данные - отсутствует обязательный параметр (md5). http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.4 +
-7.3.5. Ошибка в параметрах запроса. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.5 +
-7.3.6. Ошибка авторизации. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.6 +
-7.3.7. Временная ошибка. http://​wiki.onpay.ru/​doku.php?​id=oshibki#​7.3.7 +
-7.2.5. ​Если возвращен код отличный от 0, сообщение ошибки берется из поля "​comment"​. +
- +
-====Значения полей, содержащих информацию о суммах и платежных системах(на примере)==== +
- +
-Цена товара назначена в USD, а плательщик платит в RUR +
- +
-Поля для Check-запроса +
-| Цена товара | Тип платежа | amount | order_amount | order_currency | +
-| 10 USD | fix | 10 | 10 | USD | +
-| 10 USD | free | 0 | 0 | USD |  +
- +
-Поля для Pay-запроса +
-Комиссия платежной системы равна 10%, а курс обмена RUR/USD = 30/1 +
- +
-При свободных платежах +
-Если плательщик платит в той валюте,​ в которой был создан ордер +
-| Цена товара | Конверсия | amount | balance_amount | balance_currency | order_amount | order_currency | paid_amount | +
-| 10 USD | false | 10 | 10 | USD | 10 | USD | 11.11 | +
-| 10 USD | true | 10 | 10 | USD | 10 | USD | 11.11 | +
- +
-Если плательщик платит не в той валютев которой был создан ордер +
-| Цена товара | Конверсия | amount | balance_amount | balance_currency | order_amount | order_currency | paid_amount | +
-| 10 USD | false | 300 | 300 | RUR | 10 | USD | 333.33 | +
-| 10 USD | true | 300 | 10 | USD | 10 | USD | 333.33 | +
- +
-При фиксированных платежах +
-Если плательщик платит в той валюте,​ в которой был создан ордер +
-| Цена товара | Конверсия | amount | balance_amount | balance_currency | order_amount | order_currency | paid_amount | +
-| 10 USD | false | 10 | 10 | USD | 10 | USD | 11.11 | +
-| 10 USD | true | 10 | 10 | USD | 10 | USD | 11.11 | +
- +
-Если плательщик платит не в той валюте,​ в которой был создан ордер +
-| Цена товара | Конверсия | amount | balance_amount | balance_currency | order_amount | order_currency | paid_amount | +
-| 10 USD | false | 300 | 300 | RUR | 10 | USD | 333.33 | +
-| 10 USD | true | 300 | 300 | RUR | 10 | USD | 333.33 | +
- +
-Примечания  +
-1) В случае free-платежей значения параметров order_amount,​ balance_amount ​и параметров balance_currency,​ order_currency будут иметь одинаковое значение в том случае,​ если ​плательщик заплатил в той ​же платежной системе, в которой был создан платежный ордер и в случае если при несовпадении платежных систем включена конвертация +
-2) В случае fix-платежей значения параметров order_amount,​ balance_amount и параметров balance_currency,​ order_currency будут иметь одинаковое значение в том случае,​ если плательщик заплатил в той же платежной системе +
- +
-====Параметр excange_rate==== +
- +
-Параметр excange_rate при изменение курсов обмена +
- +
-В том случае,​ если у платежного ордера валюта оплаты и валюта назначения различаются,​ и курс обмена между этими валютами меняется,​ возможна смена курса в промежуток времени между созданием платежного ордера и соответствующего ему входящего платежа. ​Курс обмена может увеличиться,​ либо уменьшиться. +
- +
-Если магазина хочет получить сумму 200 WMZ. Плательщик желает оплатить ее в EUR. Курс обмена на момент оплаты и создания платежного ордера - 1 EUR = 1.4 WMZ. Комиссий для простоты нет. Платежный ордер создается с такими суммами:​ к оплате - 124.86 EUR, к получению - 200.0 WMZ. Рассмотрим три случая поведения курса обмена. +
- +
-| Сценарий | Курс обмена на момент создания платежа | Оплаченная сумма (amount в запросе pay) EUR | Сумма к получению (order_amount в запросе pay) WMZ | excange_rate в запросе pay | +
-| Курс не изменился | 1.4 | 142.86 | 200.0 | 1.4 | +
-| Курс повысился | 1.42 | 142.86 | 202.86 | 1.4 | +
-| Курс понизился | 1.38 | 142.86 | 197.15 | 1.4 | +
- +
-В платеж и в pay запрос к серверу магазина попадает сумма, вычисленная по новому курсу на момент создания платежа. В pay запросе к серверу магазина приходит старый курс, который был на момент создания ордера. +
- +
  
 +Если сервер магазина недоступен для “pay” запроса,​ система Onpay будет повторно отправлять запрос несколько раз в течение следующих 72 часов. Повторяющиеся запросы посылаются с увеличивающимися интервалами. При этом платеж будет зачислен на счет магазина.
api-notify.1413788953.txt.gz · Последние изменения: 2014/10/20 07:09 — admin