Onpay.ru Wiki

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
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><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>

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

| Название | Тип | Описание |
| 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>

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><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>

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

| Название | Тип | Описание |
| 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>

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

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

адрес -  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>

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

адрес -  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>

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><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 |
Onpay.ru Wiki

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

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

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