Здесь показаны различия между двумя версиями данной страницы.
Both sides previous revision Предыдущая версия Следущая версия | Предыдущая версия | ||
api-2.0 [2014/04/02 10:38] admin |
— (текущий) | ||
---|---|---|---|
Строка 1: | Строка 1: | ||
- | ==== API 2.0 ==== | ||
- | API построено на REST архитектуре. JSON возвращается в ответ на все запросы к API, в том числе и при возникновении ошибок. Имеет предсказуемые, ресурсо-ориентированные URL-адреса, использует HTTP-коды для передачи состояния ошибок, а также использует встроенные функции HTTP-аутентификации и методы GET, POST, PUT, DELETE. | ||
- | |||
- | ==== Запросы от OnPay к сайту мерчанта ==== | ||
- | |||
- | ===== 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><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 ===== | ||
- | |||
- | Для 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> | ||
- | |||
- | ==== Запросы от мерчанта к OnPay ==== | ||
- | |||
- | ===== Получить данные платежа ===== | ||
- | |||
- | адрес - 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><code class="json"> | ||
- | { | ||
- | "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" | ||
- | } | ||
- | </code></pre> | ||
- | |||
- | Пример запроса для постоянной скидки: | ||
- | <pre><code class="json"> | ||
- | { | ||
- | "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" | ||
- | } | ||
- | </code></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 class="json"> | ||
- | { | ||
- | "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" | ||
- | } | ||
- | </code></pre> | ||
- | Пример ответа для постоянной скидки: | ||
- | <pre><code class="json"> | ||
- | { | ||
- | "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" | ||
- | } | ||
- | </code></pre> | ||
- | |||
- | h3. Получение купона | ||
- | |||
- | метод - GET | ||
- | адрес - json_interfaces/coupons/:code, где code - уникальный код купона | ||
- | |||
- | Используется для просмотра текущего состояния купона. | ||
- | | Название | Тип | Описание | | ||
- | | login | string | Логин сайта | | ||
- | | signature | string | Контрольная подпись для "login;code;"get";api_key" | | ||
- | |||
- | Пример запроса: | ||
- | <pre><code class="json"> | ||
- | { | ||
- | "login":"onpay", | ||
- | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | ||
- | } | ||
- | </code></pre> | ||
- | |||
- | Ответ будет аналогичен как и у запроса для создания купона. | ||
- | |||
- | h3. Удаление купона | ||
- | |||
- | метод - DELETE | ||
- | адрес - json_interfaces/coupons/:code, где code - уникальный код купона | ||
- | |||
- | Используется для отключения купона до истечения его срока годности или исчерпания количества использований. | ||
- | | Название | Тип | Описание | | ||
- | | login | string | Логин сайта | | ||
- | | signature | string | Контрольная подпись для "login;code;"delete";api_key" | | ||
- | |||
- | Пример запроса: | ||
- | <pre><code class="json"> | ||
- | { | ||
- | "login":"onpay", | ||
- | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | ||
- | } | ||
- | </code></pre> | ||
- | |||
- | Ответ будет аналогичен как и у запроса для создания купона. | ||
- | |||
- | h1. Ошибки | ||
- | |||
- | В любом ответе могут присутствовать данные об ошибке, они записываются в конец сообщения в следующем формате: | ||
- | | Название | Тип | Описание | | ||
- | | params | string | Перечисляются все ошибочные параметры | | ||
- | | params.code | string | Код ошибки | | ||
- | | params.message | string | Текст ошибки | | ||
- | | params.name | string | Название параметра | | ||
- | | type | string | Тип ошибки | | ||
- | | message | string | Текст сообщения | | ||
- | |||
- | JSON вида: | ||
- | <pre><code class="json"> | ||
- | { | ||
- | "error":{ | ||
- | "params":[ | ||
- | { | ||
- | "code":"required", | ||
- | "message":"Description cannot be blank.", | ||
- | "name":"description" | ||
- | } | ||
- | ], | ||
- | "type":"invalid_param_error", | ||
- | "message":"Invalid data parameters" | ||
- | } | ||
- | }</code></pre> | ||
- | |||
- | h1. Примечания | ||
- | |||
- | 1) Для хеширования строки подписи используется алгоритм SHA1 | ||
- | |||
- | 2) Методы запросов: | ||
- | | Запрос | метод | | ||
- | | check | POST | | ||
- | | pay | POST | | ||
- | | state | GET | | ||
- | | rate | GET | | ||
- | | Создание купона | POST | | ||
- | | Получение купона | GET | | ||
- | | Удаление купона | DELETE | |