ДеньгиOnline

2017-01-16 19:48:06

Протокол возвратов

Протокол возвратов используется для запроса возврата по успешно совершённому платежу или получения информации о статусе возврата. Возвращена может быть сумма меньше или равная сумме платежа. Данный протокол позволяет осуществлять множественные возвраты.

Возвраты по данному протоколу возможны для следующих платежных систем:

  • Банковские карты
  • QIWI кошелек
  • WebMoney
  • Яндекс.Деньги

В остальных случаях для осуществления возврата денежных средств необходимо связаться со специалистами Деньги Online по адресу claim@dengionline.com

Проект отсылает запрос методом POST обработчику Системы по адресу

https://www.onlinedengi.ru/api/dol/refund/create/ — для запроса возврата по успешно совершенному платежу;

https://www.onlinedengi.ru/api/dol/refund/get/ — для получения информации о статусе возврата.

 

Параметры, которые Проект должен передать Системе, перечислены в таблице ниже.

В ответ на запрос Система присылает документ JSON, содержащий код статуса запроса и его расшифровку в кодировке UTF-8.

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

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

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

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

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

* Если с одним параметром dol_id запрашивается более одного частичного возврата, то в каждом запросе обязательно передаётся уникальный order_id, присвоенный Проектом

integer Обязательный
1. Параметры, необходимые для запроса возврата по успешно совершённому платежу
amount

Сумма возврата в валюте возврата.
Используется при неполном возврате. Не может превышать сумму совершённого платежа.

  • Если параметр amount = 0.00, то обращение будет рассматриваться как неудачное (ошибка).
  • Если параметр amount не указан, при этом:
    • параметр currency не указан или указан RUB, то суммой к возврату считается сумма платежа;
    • параметр currency не RUB, то суммой к возврату будет 0
float (10.2)
разделитель — точка.
Нет
currency

Валюта возврата.

  • Если параметр currency не указан, то валютой суммы возврата считается RUB.
  • Конвертация проводится по курсу, действующему на момент выставления счета на оплату

char(3),
ISO 4217 alfa-3

Возможные значения: USD, RUB, EUR

Нет
description Описание причины возврата string (1000) Нет
success Данные для отправки оповещения об успешном возврате JSON
Пример: {"success":[{"email":"test@email.ru"}, {"url":"https://testsite.ru/refund/123"}]}
Нет
fail Данные для отправки оповещения об ошибке при возврате JSON
Пример: {"fail":[{"email":"test@email.ru"}, {"url":"https://testsite.ru/refund/123"}]}
Нет
order_id

Идентификатор возврата в системе Проекта. Параметр проверяется на уникальность.

  • Если с одним параметром dol_id запрашивается более одного частичного возврата, то в каждом обязательно передается order_id, присвоенный Проектом
string (128) Нет,
если для dol_id выполняется только один возврат
2. Параметры, необходимые для получения информации о статусе возврата
refund_id Идентификатор возврата в системе Деньги Online integer Обязательный

Ответ на запрос

Признаком успешности выполнения запроса к Системе служит получение HTTP Status 200. В этом случае Система присылает ответ в формате JSON, содержащий следующие тэги:

  • refund_id — идентификатор возврата в системе Деньги Online;
  • dol_id — идентификатор платежа в системе Деньги Online;
  • order_id — идентификатор возврата в системе Проекта;
  • amount — сумма возврата в валюте возврата;
  • currency — валюта возврата;
  • amount_rub — сумма возврата в рублях;
  • state — код состояния возврата, см. список кодов;
  • description — описание причины возврата.

 

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

Полный перечень HTTP-статусов, возможных к получению в ответе со стороны Системы, доступен здесь:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

 

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

 

[
{
"refund_id":71976,
"dol_id":146785469,
"order_id":"",
"amount":"3.00",
"amount_rub":"3.00",
"currency":"RUB",
"state":1,
"description":"Refund for payment 146785469"
}
]
[
{
"refund_id":213571,
"dol_id":297835255,
"order_id":"",
"amount":"0.12",
"amount_rub":"9.45",
"currency":"USD",
"state":2,
"description":"Refund for payment 297835255"
}
]

 

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

 

[
{
"error":13,
"message":"Refund amount is above the payments"
}
]

 

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

При получении ошибки для повторного запроса на возврат исправьте некорректное значение параметра, указанного в message.

Код ошибки Возможное значение message Описание ошибки

1

Refund amount is above the limit Сумма возврата больше суммы, доступной для возврата

Wrong refund amount

Некорректная сумма возврата
2 Refund cannot be made Возврат по данному платежу не может быть выполнен
11 Refund cannot be made for payment older than 6 month Платеж старше 6 месяцев не может быть возвращен
12 Refund cannot be made for unsuccessful payments Неуспешный платеж не может быть возвращен
13 Refund amount is above the payments Сумма возврата больше суммы исходного платежа
14

Wrong refund currency

Некорректная валюта возврата

31

Not unique order_id value

Значение order_id не прошло проверку на уникальность

Payment has been returned

По указанному сочетанию dol_id и order_id уже совершен возврат,

или для нескольких возвратов по одному dol_id не указаны уникальные значения order_id

100 Internal error Внутренняя ошибка

Запрос о статусе возврата платежа

В ответ на запрос о статусе возврата Система присылает документ JSON, содержащий список возвратов, при этом параметры каждого возврата идентичны таковым при создании возврата.

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

 

[
{
"refund_id":71976,
"dol_id":146785469,
"order_id":"",
"amount":"3.00",
"amount_rub":"3.00",
"currency":"RUB",
"state":1,
"description":"Refund for payment 146785469"
}
,
{
"refund_id":71978,
"dol_id":146785469,
"order_id":"",
"amount":"3.00",
"amount_rub":"3.00",
"currency":"RUB",
"state":1,
"description":"Refund for payment 146785469"
}
]

 

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

Код статуса Состояние возврата
1 Возврат выполнен успешно
2 Возврат выполняется
3 Ошибка возврата

Пример реализации запроса на языке 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);
}
}

//Получение информации о статусе возврата
class DolRefundGet
{
protected $client;
public function __construct($project, $key)
{ $this->client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/refund/get/'); }
public function findByDolId($dol_id)
{ return $this->client->request(array('dol_id' => $dol_id)); }
public function findByRefundId($refund_id)
{ return $this->client->request(array('refund_id' => $refund_id)); }
}

//Запрос возврата
class DolRefundCreate
{
protected $client;
public function __construct($project, $key)
{ $this->client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/refund/create/'); }
public function createNew($dol_id, $amount, $currency, $description, $order_id, $email)
{ $params = array( 'dol_id' => $dol_id, 'amount' => $amount, currency' => $currency, 'description' => $description, 'order_id' => $order_id, 'success' => array(array('email' => $email), ), 'fail' => array(array('email' => $email), ), ); return $this->client->request($params); }
}