========API 2.1========

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

 API построено на REST архитектуре(кроме check и pay запросов). JSON возвращается в ответ на все запросы к API, в том числе и при возникновении ошибок. Имеет предсказуемые, ресурсо-ориентированные URL-адреса, использует HTTP-коды для передачи состояния ошибок, а также использует встроенные функции HTTP-аутентификации и методы GET, POST, PUT, DELETE.

Запросы отправляются на URL, указанный в личном кабинете в настройках магазина.
В личном кабинете также задается пароль для формирования подписи и тип API.


======Check======

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

Для check запроса используются параметры:
^ Название ^ Тип ^ Описание ^
| type | string | Тип запроса (check) |
| pay_for | string | Номер заказа |
| amount | float | Сумма платежа в центах, если параметр mode = free, то будет передан 0 |
| way | string | Валюта платежа |
| mode | string | Тип платежа, fix или free |
| user_email | string | Email плтельщика |
| signature | string | Контрольная подпись, SHA1 от строки - "check;pay_for;amount;way;mode;secret_key" |
| additional_params.onpay_ap_xxx | string | Дополнительные параметры, переданные в платежной ссылке(см документацию по платежным ссылкам). Данных параметров в запросе НЕ будет, если они не были переданы в платежной ссылке. Алгоритм их формирования смотрите ниже |

  * "check"  в строке для контрольной подписи - фиксированное слово (5 букв), а не переменная

В случае наличия параметров additional_params.onpay_ap_xxx в запросе также обязательно будет присутствовать параметр additional_params.onpay_ap_signature. Значение которого есть SHA1 от строки, полученной как конкатенация значений всех доп параметров(отсортированных по названию параметра) + НЕпередаваемого параметра onpay_ap_key, значение которого равно API_KEY в настройках сайта в кабинете мерчанта.

Пример запроса:
При API_KEY = 'test'
<code class="json">{
	"type":"check",
	"pay_for":"55446",
	"amount":500.0,
	"way":"RUR",
	"mode":"fix",
	"user_email":"test@test.com",
	"signature":"37eacbf65fa2982be8e2f82d1cb6aef23bf88aa0"
	"additional_params":{
        	"onpay_ap_a1":"w",
        	"onpay_ap_z1":"q",
        	"onpay_ap_signature":"21ce6c2615c4b325ca406470b533e8ca76759dc4"
	}
}</code>

====Ответ мерчанта====

^ Название ^ Тип ^ Описание ^
| status | boolean | Статус ответа, true для подтверждения, false для отказа. |
| pay_for | string | Номер заказа |
| signature | string | Контрольная подпись, SHA1 от строки - "check;status;pay_for;secret_key" |

  * "check"  в строке для контрольной подписи - фиксированное слово (5 букв), а не переменная
  * status в строке для контрольной подписи - строка ("true" или "false")

Пример:
<code class="json">
{
	"status":true,
	"pay_for":"55446",
	"signature":"f6f250cd7d29ac9947ed97ddaeebb7934849d21e"
}
</code>

======Pay======

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

Для pay запроса используются параметры:
^ Название ^ Тип ^ Описание ^
| type | string | Тип запроса (pay) |
| signature | string | Контрольная подпись, SHA1 от строки - "pay;pay_for;payment.amount;payment.way;balance.amount;balance.way;secret_key", где pay - строковая константа "pay", ";" - символ "точка с запятой" |
| pay_for | string | Номер заказа |
| user.email | string | E-mail плательщика |
| user.phone | string | Телефон плательщика |
| user.note | string | Комментарий плательщика |
| payment.id | int | Номер платежа |
| payment.date_time | string | Дата создания платежа в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm |
| payment.amount | float | Сумма платежа |
| payment.way | string | Валюта платежа |
| payment.rate | float | Курс обмена между валютами balance.way/payment.way |
| payment.release_at | string | Время зачисления платежа, для отложенных платежей строится аналогично payment.date_time, null если уже зачислен |
| balance.amount | float | Сумма, зачисляемая на баланс |
| balance.way | string | Валюта зачисления на баланс |
| order.from_amount | float | Сумма из ордера, которую должен был заплатить плательщик |
| order.from_way | string | Валюта из ордера, в которой должен был заплатить плательщик |
| order.to_amount | float | Сумма из ордера, которая должна была поступить на баланс магазина |
| order.to_way | string | Валюта из ордера, в которой должен был пополниться баланс магазина |
| additional_params.onpay_ap_xxx | string | Дополнительные параметры, переданные в платежной ссылке(см документацию по платежным ссылкам). Данных параметров в запросе НЕ будет, если они не были переданы в платежной ссылке. Алгоритм их формирования смотрите ниже |

  * "pay" в строке для контрольной подписи - фиксированное слово (3 буквы), а не переменная
  * при прямых платежах поля order.* отсутствуют

В случае наличия параметров additional_params.onpay_ap_xxx в запросе также обязательно будет присутствовать параметр additional_params.onpay_ap_signature. Значение которого есть SHA1 от строки, полученной как конкатенация значений всех доп параметров(отсортированных по названию параметра) + НЕпередаваемого параметра onpay_ap_key, значение которого равно API_KEY в настройках сайта в кабинете мерчанта.

Пример запроса:
При API_KEY = 'test'
<code class="json">
{
	"type":"pay",
	"signature":"951e82110d1b796374ad3577f47e20a058c525dc",
	"pay_for":"55446",
	"user":{
		"email":"mail@mail.ru",
		"phone":"9631478946",
		"note":""
	},
	"payment":{
		"id":7121064,
		"date_time":"2013-12-05T12:07:09+04:00",
		"amount":102.0,
		"way":"USD",
		"rate":33.121445,
		"release_at":null
	},
	"balance":{
		"amount":3378.39,
		"way":"RUR"
	},
	"order":{
		"from_amount":102.0,
		"from_way":"USD",
		"to_amount":3378.39,
		"to_way":"RUR"
	}
	"additional_params":{
        	"onpay_ap_a1":"w",
        	"onpay_ap_z1":"q",
        	"onpay_ap_signature":"21ce6c2615c4b325ca406470b533e8ca76759dc4"
	}
}
</code>

====Ответ мерчанта====

^ Название ^ Тип ^ Описание ^
| status | boolean | Статус ответа, true для подтверждения, false для отказа(отказ не является отказом от платежа, а лишь информацией о том, что мерчант не знает о таком платеже, при этом у платежа проставится статус как "не было уведомления", и мерчант сможет активировать его вручную в личном кабинете, если такой платеж в действительности имеет место быть). |
| pay_for | string | Номер заказа |
| signature | string | Контрольная подпись, SHA1 от строки - "pay;status;pay_for;secret_key" |
| receipt | json | Содержит информацию о списке покупок в чеке |
| receipt.items | array | Список товаров в чеке |
| receipt.items.name | string | Название товара |
| receipt.items.price | float | Цена за единицу товара |
| receipt.items.quantity | float | Количество |
| receipt.sum | float | Сумма чека |

  * "pay" в строке для контрольной подписи - фиксированное слово (3 буквы), а не переменная
  * status в строке для контрольной подписи - строка ("true" или "false")

Пример:
<code class="json">
{
  "status":true,
  "pay_for":"55446",
  "signature":"a25de68f9516e91ce8782b11abcd5801d7af20f4"
  "receipt": {
    "items": [
      {
        "name": "product 1",
        "price": 100.00,
        "quantity": 2.8
      },
      {
        "name": "product 2",
        "price": 18.50,
        "quantity": 4
      },
      {
        "name": "product 3",
        "price": 500.00,
        "quantity": 1
      }
    ],
    "sum": 854.00
  }
}
</code>

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

====Получить данные платежа====

адрес -  json_interfaces/payments/:id, где id - номер платежа в системе OnPay

Используется для получения данных о прошедшем платеже. Используемые параметры:
^ Название ^ Тип ^ Описание ^
| login | string | Логин сайта |
| signature | string | Контрольная подпись, SHA1 от строки - "id;login;secret_key" |

Пример запроса:
<code class="json">
{
	"login":"onpay",
	"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}
</code>

В ответ будет выдан JSON с данными:
^ Название ^ Тип ^ Описание |
| signature | string | Контрольная подпись, SHA1 от строки - "payment.id;payment.amount;payment.way;balance.amount;balance.way;secret_key" |
| user.email | string | E-mail плательщика |
| user.phone | string | Телефон плательщика |
| user.note | string | Комментарий плательщика |
| payment.id | int | Номер платежа |
| payment.date_time | string | Дата создания платежа в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm |
| payment.amount | bigint | Сумма платежа |
| payment.way | string | Валюта платежа |
| payment.rate | bigint | Курс обмена между валютами balance.way/payment.way |
| payment.release_at | string | Время зачисления платежа, для отложенных платежей строиться аналогично payment.date_time, null если зачислен мгновенно |
| balance.amount | bigint | Сумма, зачисляемая на баланс |
| balance.way | string | Валюта зачисления на баланс |

Пример ответа:
<code class="json">
{
	"signature":"172de16ada92791b3753b3121d471f5c",
	"user":{
		"email":"mail@mail.ru",
		"phone":"9631478946",
		"note":""
	},
	"payment":{
		"id":"7121064",
		"date_time":"2013-12-05T12:07:09+04:00",
		"amount":10200,
		"way":"USD",
		"rate":33121445,
		"release_at":null
	},
	"balance":{
		"amount":"3300",
		"way":"RUR"
	}
}
</code>

====Получить курс обмена====

адрес -  json_interfaces/rates/:from/to/:to, где from и to - валюта из и валюта назначения соответственно

Используется для получения текущего курса валют
^ Название ^ Тип ^ Описание ^
| login | string | Логин сайта |
| signature | string | Контрольная подпись, SHA1 от строки - "login;from;to;secret_key" |

Пример запроса:
<code class="json">
{
	"login":"onpay",
	"signature":"65ded5353c5ee48d0b7d48c591b8f430"
}</code>

В ответ будет выдан JSON с данными:
^ Название ^ Тип ^ Описание ^
| from | string | Валюта из |
| to | string | Валюта назначения |
| rate | bigint | значение курса * 10e6 |
| signature | string | Контрольная подпись, SHA1 от строки - "from;to;rate;secret_key" |

Пример ответа:
<code class="json">
{
	"from":"USD",
	"to":"RUR",
	"rate":33121445
	"signature":"4671aeaf49c792689533b00664a5c3ef"
}
</code>

====Вывод в Кабинеты Покупателей====

метод - POST

адрес - /json_interfaces/wop_payouts

Используется для осуществления перевода денег с баланса WOP магазина в адрес владельца Кабинета Покупателя wallet.onpay.ru. Используемые параметры:
^ Название ^ Тип ^ Описание ^
| login | string | Название сайта в системе Onpay. |
| amount | float | Сумма для вывода в кабинеты покупателей. |
| email | string | E-mail, на который зарегистрирован кабинет покупателя. |
| code | string | Код протекции. Необязательный параметр. |
| expiration | integer | Срок протекции в сутках. Необязательный параметр. Допустимое значение - целое число в интервале 1..30.  В случае отсутствия параметра в запросе устанавливается срок протекции равный тридцати дням. По истечении срока протекции деньги возвращаются отправителю |
| phone | hash | ассоциативный массив (хэш). |
| phone.number | string | Телефон, на который зарегистрирован в кабинет покупателя. Допустимое значение - десять цифр без разделителей, первая цифра - 9 |
| phone.code | string | код страны для номера телефона. Допустимое значение - "7" |
| signature | string | Контрольная подпись, SHA1 от строки login;amount;email;secret_key в случае передачи в запросе e-mail и SHA1 от строки login;amount;phone_codephone_number;secret_key в случае передачи в запросе номера телефона. Во втором случае производится конкатенация phone_code и phone_number. |

В одном запросе могут быть переданы только хэш с номером телефона или E-mail.

Пример запроса с email:
<code class="json">
{
	"login":"merchant",
	"amount":100.0,
	"email":"payer@email.com",
	"signature":"17679fdf8cbbf20e84d26c237d18c545e2cbf8fc"
}
</code>

Пример запроса с номером телефона:
<code class="json">
{
	"login":"merchant",
	"amount":100.0,
	"phone":{"code":"7","number":"9011234567"},
	"signature":"0a6d90614c4ff1860fd71337c302d4b0b2d6c9ec"
}
</code>

Сумма вывода списывается с баланса сайта в WOP.

Ответ представляет собой JSON. Список параметров в случае успешного завершения операции:

^ Название ^ Тип ^ Описание ^
| payment_id | integer | ID исходящего платежа в системе onpay |
| signature | string | SHA1 от строки payment_id;login;secret_key |

Пример ответа:
<code class="json">
{
	"payment_id":1,
	"signature":"8ef5b527eb99f3392cfa533d6221d78ceab5a7cd"
}
</code>

====Выставление счета в кабинет покупателя====

метод - POST

адрес - /json_interfaces/payment_orders

Используется для создания платежных ордеров и выставления счетов для владельцев кошельков wallet.onpay.ru.

Параметры запроса:

^ Название ^ Тип ^ Описание ^
| pay_for | string | Идентификатор ордера в магазине. Лимит - 100 символов |
| amount | float | Сумма платежного ордера |
| user_email | string | E-mail владельца кошелька. Лимит - 40 символов |
| user_phone | hash | Хэш (ассоциативный массив), содержащий телефон плательщика. Необязательный параметр |
| user_phone.code | string | Код страны телефона плательщика |
| user_phone.number | string | Номер телефона плательщика, состоящий из десяти цифр |
| note | string | Комментарий к платежному ордеру. Лимит - 255 символов. Необязательный параметр |
| login | string | Название сайта в системе Onpay |
| signature | string | Цифровая подпись, sha1 от строки login;user_email;pay_for;way;amount;secret_key |

Пример запроса:

<code class="json">
{
	"login":"merchant",
	"amount":100.0,
	"user_email":"payer@email.com",
	"pay_for":"order",
	"note":"order comment",
	"user_phone":{"code":"7","number":"9011234567"},
	"signature":"200375a39e12e850203581836549126dc4fd42bf"
}
</code>

Параметры ответа, возвращаемые в случае успешного создания ордера:

^ Название ^ Тип ^ Описание ^
| uniq_id | integer | Идентификатор платежного ордера, состоящий из девяти цифр, первая из которых 3 |
| signature | string | Цифровая подпись, sha1 от строки login;uniq_id;secret_key |

Пример ответа:

<code class="json">
{
	"uniq_id":312345678,
	"signature":"e851693315a3d45ca460482f7a9ccb1b3b6022e4" 
}
</code>

====Купоны====

Общий адрес интерфейса - json_interfaces/coupons/

===Создание Купона===

метод - POST\\
адрес -  json_interfaces/coupons/

^ Название ^ Тип ^ Описание ^
| login | string | Логин сайта |
| code | string | Промо-код купона |
| paysystem | string | Тикер платежной системы |
| type | string | Тип купона - для величины в процентах percent, для постоянной суммы const |
| percent_off | bigint | Предоставляемая скидка, в процентах, используется только для типа percent (для const - 0) |
| max_amount | bigint | Ограничение сверху по предоставляемой сумме скидки, используется только для типа percent, указывается в центах. 0 для купона без ограничения (для const - 0) |
| value | bigint | Величина скидки, используется только для типа const, указывается в центах (для percent - 0) |
| min_amount | bigint | Ограничение снизу, купон может использоваться только для платежей выше указанной суммы, указывается в центах, используется только для типа const (для percent - 0) |
| max_redemptions | int | Ограничение сверху по количеству использований |
| expired_at | string | Дата истечения скидочной акции в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm |
| announced | boolean | Если true, то сервис Onpay будет распространять купон |
| signature | string | Контрольная подпись, SHA1 от строки -  "login;paysystem;code;type;percent_off;max_amount;value;min_amount;max_redemptions;expired_at;announced;secret_key" |

Пример запроса для процентной скидки:
<code class="json">
{
	"login":"onpay",
	"code":"1",
	"paysystem":"RUR",
	"type":"percent",
	"percent_off":10,
	"max_amount":100000,
	"value":0,
	"min_amount":0,
	"max_redemptions":1,
	"expired_at":"2013-12-05T12:07:09+04:00",
	"announced":true,
	"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}
</code>

Пример запроса для постоянной скидки:
<code class="json">
{
	"login":"onpay",
	"code":"1",
	"paysystem":"WMR",
	"type":"const",
	"percent_off":0,
	"max_amount":0,
	"value":10000,
	"min_amount":100000,
	"max_redemptions":1,
	"expired_at":"2013-12-05T12:07:09+04:00",
	"announced":true,
	"signature":"d41d8cd98f00b204e9800998ecf8427e"
}
</code>

В ответ будет выдан JSON с данными:
^ Название ^ Тип ^ Описание ^
| code | string | Промо-код купона |
| type | string | Тип купона - для величины в процентах percent, для постоянной суммы const |
| percent_off | bigint | Предоставляемая скидка, в процентах, только для типа percent (для const - 0) |
| max_amount | bigint | Ограничение сверху по предоставляемой сумме скидки, только для типа percent. 0 для купона без ограничения (для const - 0) |
| value | bigint | Величина скидки, только для типа const, указывается в центах (для percent - 0) |
| min_amount | bigint | Ограничение снизу, купон может использоваться только для платежей выше указанной суммы, только для типа const (для percent - 0) |
| max_redemptions | int | Ограничение сверху по количеству использований |
| expired_at | string | Дата истечения скидочной акции в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm |
| redemptions_count | int | Количество использований |
| state | string | Текущее состояние, new для купона с не исчерпанным лимитом использований, complete для использованного максимально допустимое кол-во раз, expired для купона с истекшим временем действия и не исчерпанным лимитом использований, deleted для удаленного купона |
| announced | boolean | Если true, то сервис Onpay будет распространять купон |
| signature | string | Контрольная подпись, SHA1 от строки - "code;type;redemptions_count;state;secret_key" |

Пример ответа для процентной скидки:
<code class="json">
{
	"code":"1",
	"paysystem":"RUR",
	"type":"const",
	"percent_off":10.0,
	"max_amount":100000,
	"value":0.0,
	"min_amount":0,
	"max_redemptions":1,
	"expired_at":"2013-12-05T12:07:09+04:00",
	"redemptions_count":0,
	"state":"new",
	"announced":true,
	"signature":"172de16ada92791b3753b3121d471f5c"
}
</code>

Пример ответа для постоянной скидки:

<code class="json">
{
	"code":"1",
	"paysystem":"WMR",
	"type":"const",
	"percent_off":0.0,
	"max_amount":0,
	"value":10000.0,
	"min_amount":100000,
	"max_redemptions":1,
	"expired_at":"2013-12-05T12:07:09+04:00",
	"redemptions_count":0,
	"state":"new",
	"announced":true,
	"signature":"172de16ada92791b3753b3121d471f5c"
}
</code>

===Получение купона===

метод - GET\\
адрес -  json_interfaces/coupons/:code, где code - уникальный код купона

Используется для просмотра текущего состояния купона.
^ Название ^ Тип ^ Описание ^
| login | string | Логин сайта |
| signature | string | Контрольная подпись, SHA1 от строки - "login;code;get;secret_key" |

  * "get"  в строке для контрольной подписи - фиксированное слово (3 буквы), а не переменная

Пример запроса:
<code class="json">
{
	"login":"onpay",
	"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}
</code>

Ответ будет аналогичен как и у запроса для создания купона.

===Удаление купона===

метод - DELETE\\
адрес -  json_interfaces/coupons/:code, где code - уникальный код купона

Используется для отключения купона до истечения его срока годности или исчерпания количества использований.
^ Название ^ Тип ^ Описание ^
| login | string | Логин сайта |
| signature | string | Контрольная подпись, SHA1 от строки - "login;code;delete;secret_key" |

  * "delete"  в строке для контрольной подписи - фиксированное слово (6 букв), а не переменная

Пример запроса:
<code class="json">
{
	"login":"onpay",
	"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}
</code>

Ответ будет аналогичен как и у запроса для создания купона.

======Ошибки======

В любом ответе могут присутствовать данные об ошибке, они записываются в конец сообщения в следующем формате:
^ Название ^ Тип ^ Описание ^
| params | string | Перечисляются все ошибочные параметры |
| params.code | string | Код ошибки |
| params.message | string | Текст ошибки |
| params.name | string | Название параметра |
| type | string | Тип ошибки |
| message | string | Текст сообщения |

JSON вида:
<code class="json">
{
	"error":{
		"params":[
			{
				"code":"required",
				"message":"Description cannot be blank.",
				"name":"description"
			}
		],
		"type":"invalid_param_error",
		"message":"Invalid data parameters"
	}
}</code>

В случае возникновения ошибки общего характера, не привязанной к определенному параметру(пример - внутренняя ошибка сервера, недоступность БД), ключ 'params' можно не передавать

Тогда JSON будет вида:
<code class="json">
{
	"error":{
		"type":"invalid_param_error",
		"message":"Invalid data parameters"
	}
}</code>
======Примечания======

1) Разделителем целой и дробной части типа float является символ "." (точка).\\
Следующие числа будут выглядеть следующим образом:\\
123 -> 123.0\\
123.0 -> 123.0\\
123.00 -> 123.0\\
123.001 -> 123.0\\
В этом же представлении числа должны быть использованы при подсчете подписи.

2) Методы запросов:
^ Запрос ^ метод ^
| check | POST |
| pay | POST |
| state | GET |
| rate | GET |
| Создание купона | POST |
| Получение купона | GET |
| Удаление купона | DELETE |