Onpay.ru Wiki

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
========API 1.0========

========Описание запросов========

======Сheck запрос======

====Запрос к мерчанту====

На 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>0</code>
			<pay_for>123456</pay_for>
			<comment>OK</comment>
			<md5>*</md5>
		</result>

=== Возможные коды завершения операции ===

^ Код ^ Значение ^
| 0 | ОК – означает, что “платеж может быть принят” |
| 2 | Платёж отклонён. Onpay не примет этот платеж. |
| 3 | Ошибка в параметрах. Onpay не примет этот платеж. |
| 7 | Ошибка авторизации. MD5 подпись неверна. Onpay не примет этот платеж. |
| 10 | Временная ошибка. Onpay не примет этот платеж. |

======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 | ОК – означает, что “уведомление о платеже принято” |
| 3 | Ошибка в параметрах. Onpay.ru не будет пытаться повторно послать это уведомление в систему Продавца и отметит этот платёж статусом “уведомление не доставлено в API” если тип запроса “pay” |
| 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

====== Справочная информация ======

====Значения полей, содержащих информацию о суммах и платежных системах(на примере)====

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

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

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

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