API построено на REST архитектуре(кроме check и pay запросов). JSON возвращается в ответ на все запросы к API, в том числе и при возникновении ошибок. Имеет предсказуемые, ресурсо-ориентированные URL-адреса, использует HTTP-коды для передачи состояния ошибок, а также использует встроенные функции HTTP-аутентификации и методы GET, POST, PUT, DELETE.

Запросы отправляются на URL, указанный в личном кабинете в настройках магазина. В личном кабинете также задается пароль для формирования подписи и тип API.

Для check запроса используются параметры:

• «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"
	}
}

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

Пример:

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

Для pay запроса используются параметры:

• «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"
	}
}

• «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
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

метод - POST

адрес - /json_interfaces/wop_payouts

Используется для осуществления перевода денег с баланса WOP магазина в адрес владельца Кабинета Покупателя wallet.onpay.ru. Используемые параметры:

В одном запросе могут быть переданы только хэш с номером телефона или 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":1,
	"signature":"8ef5b527eb99f3392cfa533d6221d78ceab5a7cd"
}

метод - POST

адрес - /json_interfaces/payment_orders

Используется для создания платежных ордеров и выставления счетов для владельцев кошельков wallet.onpay.ru.

Параметры запроса:

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

{
	"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":312345678,
	"signature":"e851693315a3d45ca460482f7a9ccb1b3b6022e4" 
}

Общий адрес интерфейса - json_interfaces/coupons/

метод - POST
адрес - json_interfaces/coupons/

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

{
	"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":"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 - уникальный код купона

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

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

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

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

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

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

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

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

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

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

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

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

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) Методы запросов: