Это старая версия документа.
API построено на REST архитектуре. JSON возвращается в ответ на все запросы к API, в том числе и при возникновении ошибок. Имеет предсказуемые, ресурсо-ориентированные URL-адреса, использует HTTP-коды для передачи состояния ошибок, а также использует встроенные функции HTTP-аутентификации и методы GET, POST, PUT, DELETE.
Для 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><code class="json">{ "type":"check", "pay_for":"55446", "expired_at":"2014-02-03T18:43:21+04:00" "amount":50000, "way":"RUR", "mode":"fix", "signature":"82f67760dbc5331963b7e00bc6df77f1" }</code></pre>
Ответ мерчанта
Название | Тип | Описание |
code | int | Код ответа, 0 для подтверждения, 1 для отказа. |
type | string | Тип запроса (check) |
pay_for | string | Номер заказа |
signature | string | Контрольная подпись, строка для построения «code;pay_for;api_key» |
Пример:
<pre><code class="json"> { "code":0, "type":"check", "pay_for":"55446", "signature":"172de16ada92791b3753b3121d471f5c" } </code></pre>
Для 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><code class="json"> { "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></code>
Ответ мерчанта
Название | Тип | Описание |
code | int | Код ответа, 0 для подтверждения, 1 для отказа(отказ не является отказом от платежа, а лишь информацией о том, что мерчант не знает о таком платеже, при этом у платежа проставится статус как «не было уведомления», и мерчант сможет активировать его вручную в личном кабинете, если такой платеж в действительности имеет место быть). |
type | string | Тип запроса (pay) |
pay_for | string | Номер заказа |
signature | string | Контрольная подпись, строка для построения «code;pay_for;api_key» |
Пример:
<pre><code class="json"> { "code":0, "type":"pay", "pay_for":"55446", "signature":"172de16ada92791b3753b3121d471f5c" } </code></pre>
адрес - json_interfaces/payments/:id, где id - номер платежа в системе OnPay
Используется для получения данных о прошедшем платеже. Используемые параметры:
Название | Тип | Описание |
login | string | Логин сайта |
signature | string | Контрольная подпись «id;login;api_key» |
Пример запроса:
<pre><code class="json"> { "login":"onpay", "signature":"1d15f90df20da53d7206e9f7db7d2c9d" } </code></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><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" } } </pre></code>
адрес - json_interfaces/rates/:from/to/:to, где from и to - валюта из и валюта назначения соответственно
Используется для получения текущего курса валют
Название | Тип | Описание |
login | string | Логин сайта |
signature | string | Контрольная подпись «login;from;to;api_key» |
Пример запроса:
<pre><code class="json"> { "login":"onpay", "signature":"65ded5353c5ee48d0b7d48c591b8f430" }</code></pre>
В ответ будет выдан JSON с данными:
Название | Тип | Описание |
from | string | Валюта из |
to | string | Валюта назначения |
rate | bigint | значение курса * 10e6 |
signature | string | Контрольная подпись «from;to;rate;api_key» |
Пример ответа:
<pre><code class="json"> { "from":"USD", "to":"RUR", "rate":33121445 "signature":"4671aeaf49c792689533b00664a5c3ef" } </code></pre>
Общий адрес интерфейса - 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 |