h1. API 2.0

toc

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

h1. Запросы от OnPay к сайту мерчанта

h2. Check

Для check запроса используются параметры:

Название	Тип	Описание
type	string	Тип запроса (check)
expired_at	string	Cрок действия ордера в формате «CCYY-MM-DDThh:mm:ssTZD» где TZD смещение часового пояса в формате [+-]hh:mm
pay_for	string	Номер заказа
amount	bigint	Сумма платежа в центах, если параметр mode = free, то будет передан 0
way	string	Валюта платежа
mode	string	Тип платежа, fix или free
signature	string	Контрольная подпись, строка для построения «check;pay_for;amount;way;mode;api_key»

Пример запроса: <pre>

{
"type":"check",
"pay_for":"55446",
"expired_at":"2014-02-03T18:43:21+04:00"
"amount":50000,
"way":"RUR",
"mode":"fix",
"signature":"82f67760dbc5331963b7e00bc6df77f1"
}

</pre>

h3. Ответ мерчанта

Название	Тип	Описание
code	int	Код ответа, 0 для подтверждения, 1 для отказа.
type	string	Тип запроса (check)
pay_for	string	Номер заказа
signature	string	Контрольная подпись, строка для построения «code;pay_for;api_key»

Пример: <pre>

{
"code":0,
"type":"check",
"pay_for":"55446",
"signature":"172de16ada92791b3753b3121d471f5c"
}

</pre>

h2. Pay

Для pay запроса используются параметры:

Название	Тип	Описание
type	string	Тип запроса (pay)
signature	string	Контрольная подпись, строка для построения «pay;pay_for;payment.amount;payment.way;balance.amount;balance.way;api_key»
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	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	Валюта зачисления на баланс

Пример запроса: <pre>

{
"type":"pay",
"pay_for":"55446",
"signature":"82f67760dbc5331963b7e00bc6df77f1",
"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"
}
}
</pre>

h3. Ответ мерчанта

Название	Тип	Описание
code	int	Код ответа, 0 для подтверждения, 1 для отказа(отказ не является отказом от платежа, а лишь информацией о том, что мерчант не знает о таком платеже, при этом у платежа проставится статус как «не было уведомления», и мерчант сможет активировать его вручную в личном кабинете, если такой платеж в действительности имеет место быть).
type	string	Тип запроса (pay)
pay_for	string	Номер заказа
signature	string	Контрольная подпись, строка для построения «code;pay_for;api_key»

Пример: <pre>

{
"code":0,
"type":"pay",
"pay_for":"55446",
"signature":"172de16ada92791b3753b3121d471f5c"
}

</pre>

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

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

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

Используется для получения данных о прошедшем платеже. Используемые параметры:

Название	Тип	Описание
login	string	Логин сайта
signature	string	Контрольная подпись «id;login;api_key»

Пример запроса: <pre>

{
"login":"onpay",
"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}

</pre>

В ответ будет выдан JSON с данными:

Название	Тип	Описание
signature	string	Контрольная подпись «payment.id;payment.amount;payment.way;balance.amount;balance.way;api_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	Валюта зачисления на баланс

Пример ответа: <pre>

{
"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"
}
}
</pre>

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

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

Используется для получения текущего курса валют

Название	Тип	Описание
login	string	Логин сайта
signature	string	Контрольная подпись «login;from;to;api_key»

Пример запроса: <pre>

{
"login":"onpay",
"signature":"65ded5353c5ee48d0b7d48c591b8f430"
}

</pre>

В ответ будет выдан JSON с данными:

Название	Тип	Описание
from	string	Валюта из
to	string	Валюта назначения
rate	bigint	значение курса * 10e6
signature	string	Контрольная подпись «from;to;rate;api_key»

Пример ответа: <pre>

{
"from":"USD",
"to":"RUR",
"rate":33121445
"signature":"4671aeaf49c792689533b00664a5c3ef"
}

</pre>

h2. Купоны

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

h3. Создание Купона

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

Название	Тип	Описание
login	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
signature	string	Контрольная подпись для «login;type;percent_off;max_amount;value;min_amount;max_redemptions;expired_at;api_key»

Пример запроса для процентной скидки: <pre>

{
"login":"onpay",
"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",
"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}

</pre>

Пример запроса для постоянной скидки: <pre>

{
"login":"onpay",
"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",
"signature":"d41d8cd98f00b204e9800998ecf8427e"
}

</pre>

В ответ будет выдан 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 для удаленного купона
signature	string	Контрольная подпись «code;type;redemptions_count;state;api_key»

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

{
"code":"3whhZ4U0J9B0tATiOb",
"type":"const",
"percent_off":10,
"max_amount":100000,
"value":0,
"min_amount":0,
"max_redemptions":1,
"expired_at":"2013-12-05T12:07:09+04:00",
"redemptions_count":0,
"state":"new",
"signature":"172de16ada92791b3753b3121d471f5c"
}

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

{
"code":"3whhZ4U0J9B0tATiOb",
"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",
"redemptions_count":0,
"state":"new",
"signature":"172de16ada92791b3753b3121d471f5c"
}

</pre>

h3. Получение купона

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

Используется для просмотра текущего состояния купона.

Название	Тип	Описание
login	string	Логин сайта
signature	string	Контрольная подпись для «login;code;»get«;api_key»

Пример запроса: <pre>

{
"login":"onpay",
"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}

</pre>

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

h3. Удаление купона

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

Используется для отключения купона до истечения его срока годности или исчерпания количества использований.

Название	Тип	Описание
login	string	Логин сайта
signature	string	Контрольная подпись для «login;code;»delete«;api_key»

Пример запроса: <pre>

{
"login":"onpay",
"signature":"1d15f90df20da53d7206e9f7db7d2c9d"
}

</pre>

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

h1. Ошибки

В любом ответе могут присутствовать данные об ошибке, они записываются в конец сообщения в следующем формате:

Название	Тип	Описание
params	string	Перечисляются все ошибочные параметры
params.code	string	Код ошибки
params.message	string	Текст ошибки
params.name	string	Название параметра
type	string	Тип ошибки
message	string	Текст сообщения

JSON вида: <pre>

{
"error":{
"params":[
{
"code":"required",
"message":"Description cannot be blank.",
"name":"description"
}
],
"type":"invalid_param_error",
"message":"Invalid data parameters"
}
}

</pre>

h1. Примечания

1) Для хеширования строки подписи используется алгоритм SHA1

2) Методы запросов:

Запрос	метод
check	POST
pay	POST
state	GET
rate	GET
Создание купона	POST
Получение купона	GET
Удаление купона	DELETE