ДеньгиOnline

2017-01-16 19:48:06

Рекуррентные платежи

Рекуррентный (периодический) платеж — безакцептное списание денежных средств со счета банковской карты (электронного кошелька) плательщика в пользу проекта, всегда ссылается на родительский платеж.

Родительский платеж — платеж с дополнительным параметрами запроса, которые позволяют сделать на его основе рекуррентные платежи

Структура:

Родительский платеж

  • рекуррентный платеж 1
  • рекуррентный платеж 2
  • ...
  • рекуррентный платеж N

Создание родительского платежа

1. Cоздание родительского платежа

Производится как инициация обычного платежа (согласно процедуре выставления счета по основному протоколу) с указанием дополнительных параметров.

Параметры запроса при создании родительского платежа:

Параметр Описание параметра Формат параметра
Обязательность
параметра
recurrent_init Инициирование родительского рекуррентного платежа без указания периода Параметр должен принимать значение «1». Да
payment_period Период рекуррентных платежей в днях integer
Желательно 7, 14, 30 и т.п.
Да
closed_at Дата прекращения действия рекуррентных платежей Дата в формате ГГГГ-ММ-ДД Да

Проект отсылает запрос методом POST обработчику Системы по адресу https://www.onlinedengi.ru/wmpaycheck.php.

2. Оплата родительского платежа

Родительский платеж должен быть успешно оплачен. 

Внимание! Если родительскому платежу при оплате не присвоен статус Success / Успех (даже если денежные средства списались, но по каким-либо причинам при техническом оповещении проекта произошел сбой), то данный платеж не будет считаться родительским платежом.

Действия с рекуррентными платежами в Системе ДеньгиOnline:

Внимание! Все действия возможны только для проектов, которым разрешены рекуррентные платежи.

Действия возможны только для тех рекуррентных платежей, чей родительский платеж находится в статусе Success / Успех

Для осуществления действия Проект отсылает в запросе набор параметров (обязательный для каждого действия + свой) методом POST обработчику Системы по определенному адресу:

  Действие Адрес обработчика
1 Получение информации о родительских платежах (максимум 5000 последних) https://www.onlinedengi.ru/api/dol/recurent/get/
2 Получение информации о рекуррентных платежах (максимум 5000 последних) https://www.onlinedengi.ru/api/dol/recurent/list/
3 Изменение периода рекуррентного платежа или его закрытие https://www.onlinedengi.ru/api/dol/recurent/change/
4 Инициализация рекуррентного платежа на основании родительского платежа https://www.onlinedengi.ru/api/dol/recurent/init/

Признаком успешности выполнения запроса к Системе служит получение HTTP Status 200.

В случае неудачного обращения проекту будет отдан HTTP Status, отличный от 200, в качестве тела сообщения будет выведено текстовое описание ошибки, возникшей в процессе работы.

Полный перечень HTTP-статусов, возможных к получению в ответе со стороны Системы, доступен здесь

Параметры запроса, обязательные при любом действии с рекуррентными платежами 

Параметр Описание параметра Формат параметра
Обязательность
параметра
X-DOL-Project Идентификатор Проекта в Системе. 

Внимание! Значение параметра должно передаваться в заголовке , а не в теле запроса
integer Обязательный
X-DOL-Sign
Контрольная подпись запроса.
Формируется по алгоритму HMAC-SHA1 от полного тела запроса. В качестве ключа для формирования запроса используется секретное слово проекта, оговоренное сторонами и используемое для формирования хэш-кода при запросе на проведение платежа со стороны Деньги Online в Проект. 

Внимание! Значение параметра должно передаваться в заголовке, а не в теле запроса
hex Обязательный
dol_id Идентификатор платежа в системе Деньги Online integer Обязательный*

* Параметр dol_id является обязательным, если в действии не передается параметр paymode, и необязательным, если в действии передается параметр paymode. При одновременной передаче обоих параметров dol_id считается более приоритетным.

1. Получение информации о родительских платежах (максимум 5000 последних) 

Действие предназначено для получения информации о родительских платежах. Ответ на запрос может содержать максимум 5000 последних родительских платежей. 

Для выполнения действия отсылается на адрес https://www.onlinedengi.ru/api/dol/recurent/get/ методом POST набор из обязательных и дополнительных параметров.

Таблица дополнительных параметров для получения информации о родительских платежах

Параметр Описание параметра Формат параметра
Обязательность
параметра
paymode Идентификатор платежного метода integer

Обязательный*

start Начало периода выборки Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС

Нет.

Если параметры не будут указаны, будет выведена выборка всех родительских платежей, но в пределах последних 5000 шт

end Конец периода выборки Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС

 * Параметр paymode является обязательным, если в действии не передается параметр dol_id, и необязательным, если в действии передается параметр dol_id.При одновременной передаче обоих параметров dol_id считается более приоритетным. Если не указан ни один из параметров dol_id и paymode, будет отдана ошибка c сообщением message: «Invalid request» («Некорректный запрос»).

 После обработки переданных Проектом данных Система присылает ответ в формате JSON, содержащий (помимо переданных в запросе dol_id и/или paymode) следующие тэги:

Таблица тэгов, содержащихся в ответе

Параметр Описание параметра Формат параметра
nick Идентификатор пользователя или заказа varchar
status Статус платежа

Success / Успех

amount_rub Сумма платежа в рублях decimal(10.2)
date_payment Дата рекуррентного платежа Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
count Количество успешных платежей в рамках данного родительского платежа integer
last_payment Дата последнего рекуррентного платежа Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
period Периодичность платежа integer (дни)
message Сообщение об ошибке

string

Возможные варианты:

    • Payment inactive or unsuccessful / Платеж неуспешен или неактивен
    • Not valid date format / Неверный формат даты
    • Payment not found / Платеж не найден
    • Invalid request / Некорректный запрос
error В случае ошибки - ее код integer

Примеры запросов и ответов

Варианты запроса Пример ответа в случае успеха Пример ответа в случае неудачи
{"dol_id":146785469} {
"dol_id":146785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"period":"30",
"count":1,
"last_payment":"2013-05-03 18:45:33", "date_payment":"2013-11-22 10:58:39"
}
 
{"paymode":34} {
"dol_id":146785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"period":"30",
"count":1,
"last_payment":"2013-05-03 18:45:33", "date_payment":"2013-11-22 10:58:39"
},
{
"dol_id":200780469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"20.00",
"period":"360",
"count":10,
"last_payment":"2013-10-30 15:05:20", "date_payment":"2013-11-22 10:58:39"
}
 
{"start":"2013.05.01", "end":"2013.06.01", "paymode":34} -- {
"error":4,
"message":"Not valid date format",
}

2. Получение информации о рекуррентных платежах (максимум 5000 последних) 

Действие предназначено для получения информации о рекуррентных платежах. Ответ на запрос может содержать максимум 5000 последних рекуррентных платежей. 

Для выполнения действия отсылается на адрес https://www.onlinedengi.ru/api/dol/recurent/list/ методом POST набор из обязательных и дополнительных параметров.

Таблица дополнительных параметров для получения информации о рекуррентных платежах

Параметр Описание параметра Формат параметра
Обязательность
параметра
paymode Идентификатор платежного метода integer

Обязательный*

start Начало периода выборки Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС

Нет.

Если параметры не будут указаны, будет выведена выборка всех рекуррентных платежей, но в пределах последних 5000 шт

end Конец периода выборки Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
status Cтатус платежей

string

Возможные варианты:

    • New
    • Success
    • Fail
    • In progress
    • Fatal
    • Decline
Нет

* Параметр paymode является обязательным, если в действии не передается параметр dol_id, и необязательным, если в действии передается параметр dol_id.При одновременной передаче обоих параметров dol_id считается более приоритетным. Если не указан ни один из параметров dol_id и paymode, будет отдана ошибка c сообщением message: «Invalid request» («Некорректный запрос»).

После обработки переданных Проектом данных Система присылает ответ в формате JSON, содержащий (помимо переданных в запросе dol_id и/или paymode) следующие тэги:

Таблица тэгов, содержащихся в ответе

Параметр Описание параметра Формат параметра
nick Идентификатор пользователя или заказа varchar
status Статус платежа

string

 Возможные варианты:

    • New
    • Success
    • Fail
    • In progress
    • Fatal
    • Decline
amount_rub Сумма платежа в рублях decimal(10.2)
date_payment Дата рекуррентного платежа Дата в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
parent Идентификатор родительского платежа integer
message Сообщение об ошибке

string

Возможные варианты:

    • Payment inactive or unsuccessful / Платеж неуспешен или неактивен
    • Not valid date format / Неверный формат даты
    • Payment not found / Платеж не найден
    • Invalid request / Некорректный запрос
error В случае ошибки - ее код integer

Примеры запросов и ответов

Варианты запроса Пример ответа в случае успеха Пример ответа в случае неудачи
{"start":"2013-05-01", "end":"2013-06-01", "paymode":34}

{"start":"2013-05-01", "end":"2013-06-01", "status":"Sucess"}
{
"dol_id":186785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"parent": 177783562,
"date_payment":"2013-05-03 18:45:33"
},
{
"dol_id":186785569,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"parent": 177783562,
"date_payment":"2013-05-04 18:45:33"
}
 

3. Изменение периода рекуррентного платежа или его закрытие

3.1. Изменение периода рекуррентного платежа 

Действие предназначено для изменения периода рекуррентного платежа. 

Для выполнения действия отсылается на адрес https://www.onlinedengi.ru/api/dol/recurent/change/ методом POST набор из обязательных и дополнительных параметров.

Таблица дополнительных параметров для изменения периода рекуррентного платежа

Параметр Описание параметра Формат параметра
Обязательность
параметра
period Новый период платежа (в днях) integer Обязательный

После обработки переданных Проектом данных Система присылает ответ в формате JSON, содержащий (помимо переданного в запросе dol_id) следующие тэги:

Таблица тэгов, содержащихся в ответе

Параметр Описание параметра Формат параметра
message Сообщение об изменении состояния платежа

string

Возможные варианты:

    • Period updated / Период изменен
    • No change / Изменений не произведено
    • Payment inactive or unsuccessful / Платеж неуспешен или неактивен
    • Payment not found / Платеж не найден
    • Wrong dol_id / Неверный dol_id
error В случае ошибки - ее код integer

Примеры запросов и ответов

Варианты запроса Пример ответа в случае успеха Пример ответа в случае неудачи
{"dol_id":177783562, "period":360} {
"dol_id":177783562,
"message":"Period updated",
}

{
"message":"Wrong dol_id",
"error":"4"
}

3.2. Закрытие родительского платежа 

Действие предназначено для закрытия родительского платежа. 

Для выполнения действия отсылается на адрес https://www.onlinedengi.ru/api/dol/recurent/change/ методом POST набор из обязательных и дополнительных параметров.

Таблица дополнительных параметров для закрытия родительского платежа

Параметр Описание параметра Формат параметра
Обязательность
параметра
close Команда закрытия родительского платежа Принимает значение close = 1 Обязательный

После обработки переданных Проектом данных Система присылает ответ в формате JSON, содержащий (помимо переданного в запросе dol_id) следующие тэги:

Таблица тэгов, содержащихся в ответе

Параметр Описание параметра Формат параметра
message Сообщение об изменении состояния платежа

string

Возможные варианты:

    • Recurring payment stopped / Рекуррентный платеж прекращен
    • No change / Изменений не произведено
    • Payment inactive or unsuccessful / Платеж неуспешен или неактивен
    • Payment not found / Платеж не найден
    • Wrong dol_id / Неверный dol_id
error В случае ошибки - ее код integer

Примеры запросов и ответов

Варианты запроса Пример ответа в случае успеха Пример ответа в случае неудачи
{"dol_id":177783562, "close":1} {
"dol_id":177783562,
"message":"Recurring payment stopped",
}
{
"error":4,
"message":"Payment inactive or unsuccessful",
}

 

4. Инициализация рекуррентного платежа на основании родительского платежа 

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

Для выполнения действия отсылается на адрес https://www.onlinedengi.ru/api/dol/recurent/init/ методом POST набор из обязательных и дополнительных параметров.

Таблица дополнительных параметров для инициализации рекуррентного платежа на основании родительского

Параметр Описание параметра Формат параметра
Обязательность
параметра
amount_rub Сумма платежа (только рубли) double (4) Нет.
Если параметр не передан, то сумма будет равна сумме родительского платежа

После обработки переданных Проектом данных Система присылает ответ в формате JSON, содержащий следующие тэги:

Таблица тэгов, содержащихся в ответе

Параметр Описание параметра Формат параметра
dol_id

Идентификатор платежа в системе Деньги Online.

Если платеж в системе создан (успешный или ошибочный), то dol_id будет передан новый

integer

message Сообщение об изменении состояния платежа

string

Возможные варианты:

    • Success / Успех,
    • In progress / В обработке
    • Fail / Отказ
    • Decline / Отмена авторизации
    • Fatal / Невозможность
    • Closed / Платеж закрыт
    • Recurrent not allowed / Не разрешено проведение рекуррентных платежей
    • Payment not found / Платеж не найден
error В случае ошибки - ее код integer

Примеры запросов и ответов

Варианты запроса Пример ответа в случае успеха Пример ответа в случае неудачи
{"dol_id":177783562, "amount_rub":300} {
"dol_id":177783575,
"message":"Success",
}

{
"message":"Payment not found",
"error":"4",
}

Список возможных ошибок обработки запросов

Код error Описание Продолжать ли запросы с теми же параметрами? Варианты решения типовых проблем
2 Ошибка при проведении инициализации платежа Да Повторите попытку через некоторое время
4 Инициализация платежа невозможна Нет Дополнительных действий не требуется
6 Отмена авторизации платежа

Да, но не более 4 раз в течение 14 дней после получения первой ошибки

Повторите попытку не более 4 раз в следующие 14 календарных дней.

Внимание! Не повторяйте запрос более 4 раз в следующие 14 суток!

Последующие попытки непременно приведут к блокировке проекта банком!

Пример реализации запроса на языке PHP 

class DolClient
{
	protected $project;
	protected $key;
	protected $url;
	public function __construct($project, $key, $url)
	{
		 $this->project = $project; $this->key = $key; $this->url = $url; 
	}
	public function request($data)
	{
		if (is_string($data))
			{ $post_data = $data; }
		else
			{ $post_data = json_encode($data); }
		$headers = array(
			'X-DOL-Project: '. $this->project,
			'X-DOL-Sign: '. hash_hmac('sha1', $post_data, $this->key),
		);
		$sh = curl_init();
		curl_setopt($sh, CURLOPT_URL, $this->url);
		curl_setopt($sh, CURLOPT_CONNECTTIMEOUT, 5);
		curl_setopt($sh, CURLOPT_TIMEOUT, 60);
		curl_setopt($sh, CURLOPT_RETURNTRANSFER, TRUE );
		curl_setopt($sh, CURLOPT_SSL_VERIFYPEER, FALSE);
		curl_setopt($sh, CURLOPT_SSL_VERIFYHOST, FALSE);
		curl_setopt($sh, CURLOPT_POST, TRUE );
		curl_setopt($sh, CURLOPT_POSTFIELDS, $post_data);
		curl_setopt($sh, CURLOPT_HTTPHEADER, $headers);
		$response = curl_exec($sh);
		$curl_errno = curl_errno($sh);
		$curl_error = curl_error($sh);
		$http_code = curl_getinfo($sh, CURLINFO_HTTP_CODE);
		curl_close($sh);
		if ($curl_errno > 0)
		{ throw new Exception($curl_error, $curl_errno); }
		if ($http_code 	!= 200)
		{ throw new Exception($response, $http_code); }
		var_dump($response);
		return json_decode($response);
	}
}
$project= 1234;
$key = 123456;
 
// Получение информации о рекуррентных базовых платежах 
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/get/');
$response = $client->request(array('paymode' => 57));
 
//Получение информации о рекуррентных платежах 
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/list/');
$response = $client->request(array('paymode' => 57, 'start' => "2014-01-30"));
 
//Инициализация рекуррентного платежа на основании родительского платежа 
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/init/');
$response = $client->request(array('dol_id' => 242479910, 'amount_rub' => '0.5'));
 
//Изменение периода рекуррентного платежа или его закрытие
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/change/');
$response = $client->request(array('dol_id' => 242479910, 'close' => 1));