Содержание

API 2.1

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

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 Дополнительные параметры, переданные в платежной ссылке(см документацию по платежным ссылкам). Данных параметров в запросе НЕ будет, если они не были переданы в платежной ссылке. Алгоритм их формирования смотрите ниже

В случае наличия параметров 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»

Пример:

{
	"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 Дополнительные параметры, переданные в платежной ссылке(см документацию по платежным ссылкам). Данных параметров в запросе НЕ будет, если они не были переданы в платежной ссылке. Алгоритм их формирования смотрите ниже

В случае наличия параметров 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 Сумма чека

Пример:

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

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

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

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

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

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

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

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

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

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