API 2.0

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

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'

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

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

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

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

status в строке для контрольной подписи - строка («true» или «false»)

Пример:

{
"status":true,
"pay_for":"55446",
"signature":"f6f250cd7d29ac9947ed97ddaeebb7934849d21e"
}

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'

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

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

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

Пример:

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

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

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

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

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

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

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

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

В ответ будет выдан 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	Валюта зачисления на баланс

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

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

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

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

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

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

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

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

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

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

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

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

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

метод - 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:

{
"login":"merchant",
"amount":100.0,
"email":"payer@email.com",
"signature":"17679fdf8cbbf20e84d26c237d18c545e2cbf8fc"
}

Пример запроса с номером телефона:

{
"login":"merchant",
"amount":100.0,
"phone":{"code":"7","number":"9011234567"},
"signature":"0a6d90614c4ff1860fd71337c302d4b0b2d6c9ec"
}

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

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

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

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

{
"payment_id":1,
"signature":"8ef5b527eb99f3392cfa533d6221d78ceab5a7cd"
}

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

метод - 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

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

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

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

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

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

{
"uniq_id":312345678,
"signature":"e851693315a3d45ca460482f7a9ccb1b3b6022e4"
}

Купоны

Общий адрес интерфейса - 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»

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

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

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

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

В ответ будет выдан 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":"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":"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"
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ошибки

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

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

JSON вида:

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

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

Тогда JSON будет вида:

{
"error":{
"type":"invalid_param_error",
"message":"Invalid data parameters"
}
}

Примечания

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