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

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


api-notify

Это старая версия документа.


Общая информация по API

Определения

Продавец (он же мерчант) – пользователь системы Onpay.ru (интернет-магазин, НКО, ИП и т.п.) обладающий правами получать платежи от третьих лиц через систему Onpay.ru
Клиент – любой пользователь системы Продавца, желающий переводить деньги Продавцу через систему Onpay.ru (покупка товаров и услуг, благотворительные пожертвования и проч.)

Подключение API

Для включения работы по API, Вам нужно:
1. Активировать функцию “Уведомление по API” в разделе Настройки Магазина в Кабинете Продавца Onpay
2. Указать API URL в соответствии со скриптом API на Вашем сервере.
3. Установить секретный ключ для “уведомлений по API”, который должен быть таким же, как в скрипте на Вашем сервере, чтобы позволить генерацию контрольных подписей.

Описание и очередность транзакций


Onpay.ru производит 2 вида запросов к системе Продавца через API:
1. Запрос “check” используется, чтобы получить разрешение от системы Продавца на прием платежа от Клиента. После удачного получения разрешения, Onpay.ru одобрит платёж. С этого момента, если Клиент действительно производит платёж, Продавец может видеть его во вкладке “Платежи” в Кабинете Продавца.
2. Запрос “pay” является, по сути, уведомлением для системы Продавца, о том, что для него принят платеж. После получения уведомления, система Продавца может автоматически отправить заказанные товары или сервисы Клиенту.

Onpay.ru имеет несколько типов АПИ:
1. Основное АПИ (версия 2.0). В Кабинете продавца выбран по умолчанию (поле селектора на HTTPS 2.0). 2. API 1.0. Старое апи. С этим АПИ, в частности, работают все загружаемые модули с onpaysolutions.ru
3. Специальное АПИ для Insales (его настройка описана отдельно)
4. Гибридные АПИ для упрощения миграции (переход с Робокассы и Интеркассы)

Очередность транзакции:
1. Клиент переходит по платежной ссылке на форму Onpay и заполняет данные(если необходимо).
2. Onpay.ru отправляет “check” запрос в адрес Продавца, удостоверяясь, что система Продавца может (и разрешает) принять платёж. Система Продавца проверяет все параметры запроса (существуют ли в системе ID Клиента и заказа, может ли Клиент платить и т.д.).
a. Если система Продавца не позволяет перевод (любой итог, кроме получения кода 0 от системы Продавца) – платёж не будет принят от Клиента.
b. Если API Продавца разрешает перевод (код 0) – Onpay разрешает Клиенту платить.
3. Клиент производит оплату
4. Onpay сохраняет платёж со статусом “Получен” и отправляет запрос типа “pay” в систему Продавца с теми же параметрами, что и запрос “check”, плюс ID платежа и дата/время момента, когда платёж был одобрен.
a. если система Продавца приняла уведомление (код 0) – Onpay.ru изменяет статус этого платежа с “Получен” на “Принят”
b. если система Продавца сообщает о некритичной ошибке – Onpay.ru попробует известить систему Продавца позже. Onpay.ru будет посылать извещения с возрастающими временными интервалами, до тех пор пока система Продавца не примет уведомление или пока не пройдёт 72 часа.
Платежи со статусами “получен” и “принят” могут быть просмотрены во вкладке “Платежи” в Кабинете Продавца Onpay.ru.

Продавцы могут помечать платежи, как “Принятые” вручную во вкладке “Платежи” если 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 не примет платёж от Клиента.

Если сервер магазина недоступен для “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 запросе к серверу магазина приходит старый курс, который был на момент создания ордера.

api-notify.1413788953.txt.gz · Последние изменения: 2014/10/20 07:09 — admin