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

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


api-notify

Различия

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

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

Both sides previous revision Предыдущая версия
Следущая версия
Предыдущая версия
Последняя версия Both sides next revision
api-notify [2014/10/20 07:09]
admin [Описание и очередность транзакций]
api-notify [2023/08/22 07:11]
admin [Описание и очередность транзакций]
Строка 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|Миграция с Робокассы]]
  
-  * [[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.txt · Последние изменения: 2023/09/25 07:57 — admin