ДеньгиOnline

2017-07-29 03:29:07

Холдирование

Холдирование — операция блокирования денежных средств в момент совершения операции по банковской карте.

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

Одновременная реализация прямых и холдированных платежей невозможна.

Если выбрано получение средств через холдирование, то Проект должен предоставить следующую информацию:

  1. Период холдирования — время, в течение которого платеж доступен к оплате.
  2. Действие, которое необходимо совершить с захолдированными средствами по истечении периода, указанного в п.1. 
    Для Проекта возможны 2 действия:
    1. complete — погашение холда (т.е. подтверждение оплаты), в этом случае захолдированные средства будут перечислены Проекту;
    2. reversal — отмена холда, в этом случае захолдированные средства будут возвращены Пользователю.
  3. Оповещение о холдировании средств – необходимо ли получать информацию о факте холдирования транзакции на обработчик Проекта (по API).
  4. URL (адрес) обработчика – если, согласно п.3, необходимо получать информацию о холдировании по API.

Схема работы по основному протоколу с холдированием

1. Порядок выставления счета при холдировании

Не отличается от процедуры выставления счета по основному протоколу.

2. Оповещение Проекта при холдировании

После создания счёта на стороне ДОЛ, Система оповещает об этом Проект.

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

Уведомление Проекта о факте холдирования происходит аналогично общему случаю, но с дополнительными параметрами:

Параметр Описание Формат
expire_time Дата и время истечения срока жизни холда string;
YYYY-MM-DD hh:mm:ss
expire_action Действие по умолчанию после истечения времени жизни холда (expire_time).
Доступные значения:
  1. complete — подтвердить холд(списание);
  2. reversal — отменить холд (возврат денежных средств)
string

Параметры ответа Проекта

На каждый запрос Системы от Проекта должен приходить ответ в формате XML и кодировке UTF-8, содержащий следующий параметр:

Параметр Значение параметра Описание значения параметра
code YES Проект подтвердил, что перечисленные по транзакции средства заморожены
CANCEL Равнозначно действию reversal (денежные средства вернуть пользователю)

Внимание! При отсутствии ответа Система будет повторять попытки оповестить Проект с интервалами 30sec, 5m, 5m, 5m, 5m, 20m, 20m... до момента, пока период холдирования, установленный по умолчанию, не истечет.

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

3. API холдирования

Проект может выполнять следующие действия с захолдированными средствами (с транзакцией в статусе Hold («Заморожен»)):

  1. Погашение холда — по запросу Проекта (см. параметры в таблице ниже) или автоматически (действие, выполняемое при истечении срока жизни холда — снятие средств с карты клиента (Complete)).
  2. Отмена холда — по запросу Проекта(см. параметры в таблице ниже) или автоматически (действие, выполняемое при истечении срока жизни холда — отмена холда(Reversal)).

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

Проект отправляет запрос методом POST обработчику Системы по адресу https://www.onlinedengi.ru/api/dol/hold/.

Параметры запроса на подтверждение холдирования

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

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

Внимание! Значение параметра должно передаваться в заголовке, а не в теле запроса
hex Обязательный
dol_id Идентификатор платежа в системе Деньги Online integer Обязательный
action Идентификатор желаемого действия.
Возможные значения:
  • complete — погашение холда (т.е. подтверждение оплаты);
  • reversal — отмена холда
string Обязательный

Параметры ответа Системы

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

Параметр Описание параметра Формат параметра
code Код операции integer
comment Текстовое описание операции string

Коды и описания состояния холдирования*

Код (code) Описание (comment) Окончательность статуса
400 Некорректные параметры запроса

Статус окончательный. Проверьте параметры запроса

404 Платеж не найден Статус окончательный. Проверьте параметры запроса
500 Платеж не имеет статуса предавторизации. Complete/Reversal невозможны

Статус неокончательный.

Проверьте статус предавторизационного платежа (желаемые — 22, 25 - Hold) и повторите запрос

501 Платеж успешно проведен ранее Статус окончательный. Действий не требуется
506 Платеж отменен ранее Статус окончательный. Действий не требуется
508 Запрос на подтверждение предавторизации успешно принят

Статус окончательный. 

Не является статусом платежа!

Чтобы удостовериться, что платеж в нужном статусе – проверяйте статус платежа до получения окончательного (см. Перечень статусов платежа по классификатору Системы)

509 Запрос на отмену предавторизации успешно принят

* Не являются статусами платежа! 

Пример запроса на отмену холда:

[{"dol_id":239338949,
"action":"reversal"}]

Пример ответа в случае успешной обработки запроса:

[{"code":"508",
"comment":"Запрос на подтверждение предавторизации успешно принят"}]

Пример ответа в случае ошибки обработки запроса:

[{"code":"404",
"comment":"Платеж не найден"}]

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

<?php 
$project = 1234; 
$key = '123456'; 
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/hold/'); 
$response = $client->request(array('dol_id' => 239338949, 'action' => 'reversal')); 
 
echo "<br> 
Код описания: ". $response -> code. "<br> 
Комментарий по коду: ".$response -> comment. "<br>"; 
 
classDolClient 
{ 
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); 
	} 
} 
?>