ДеньгиOnline

2017-01-16 19:48:06

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

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

Для реализации механизма холдирования Проект до начала технической интеграции должен предоставить следующую информацию:

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

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 холдирования

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

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

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

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

Параметр Описание параметра Формат параметра
Обязательность
параметра
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); 
	} 
} 
?>