ДеньгиOnline

2017-07-29 03:29:07

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

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

Возвращена может быть сумма меньше или равная сумме платежа. Данный протокол позволяет осуществлять множественные (частичные) возвраты.

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

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

В остальных случаях для осуществления возврата денежных средств необходимо обратиться в отдел возвратов лицензиара Системы (или, если лицензиар - ДОЛ, по адресу claim@dengionline.com).

1. Запрос возврата (по успешно совершённому платежу)

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

С помощью запроса на адрес https://www.onlinedengi.ru/api/dol/refund/create/ проект передает набор параметров.

Для передачи параметров запроса используются следующие правила:

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

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

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

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

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

integer Обязательный
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 выполняется только один возврат

Обратите внимание! Если Система передает от имени Проекта данные для чеков по ФЗ-54, то при выполнении запроса возврата необходимо передавать некоторые дополнительные параметры:

Параметр Описание параметра Формат параметра Обязательность параметра
customer_contact Телефон или e-mail покупателя, на которые будет отправлен чек

/^[\d]+$/ или /@/

Да
receipt Массив данных в формате JSON для формирования чека, где каждый товар характеризуется следующими параметрами:  string

Да, если:

  • совершается частичный возврат, или

  • при выставлении счета данные для чека по какой-либо причине не передавались




Quantity Количество товара decimal(10.3), разделитель - точка
Price Цена товара с учетом всех скидок и наценок decimal(10.2), разделитель - точка
Tax Ставка НДС: 1 – 18%; 2 – 10%; 3 – расч. 18/118; 4 – расч. 10/110; 5 – 0%; 6 – НДС не облагается integer
Text Наименование позиции string(128)

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

Признаком успешного обращения к Системе служит получение Проектом ответа с HTTP Status 200. В случае неудачного обращения проекту будет отдан HTTP Status, отличный от 200, а в качестве тела сообщения будет выведено текстовое описание ошибки, возникшей в процессе работы. Полный перечень HTTP-статусов, возможных к получению в ответе со стороны Системы, доступен здесь

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

Параметр
Описание параметра
Формат параметра
refund_id Идентификатор возврата в Системе integer
dol_id Идентификатор платежа в Системе integer
order_id Идентификатор возврата в системе Проекта string(128)
amount Сумма возврата в валюте возврата float(10.2),
разделитель — точка
currency Валюта возврата char(3), ISO 4217, alfa-3 

Возможные значения: USD, RUB, EUR
amount_rub Сумма возврата в рублях float(10.2),
разделитель — точка
state

Код состояния возврата:

1 - успех;

2 - в работе.

integer
description Описание причины возврата string 

Если возврат невозможно совершить, Система пришлет ответ в формате JSON в кодировке UTF-8, содержащий следующие тэги:

Параметр
Описание параметра
Формат параметра
error Числовой код ошибки integer

message

Описание причины, по которой невозможно выполнить возврат для платежа integer

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

Код ошибки Возможное значение 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 Внутренняя ошибка

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

 

[
{
"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"
}
]

 

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

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

С помощью запроса на адрес https://www.onlinedengi.ru/api/dol/refund/get/ проект передает набор параметров.

 Для передачи параметров запроса используются следующие правила:

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

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

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

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

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

integer Обязательный
refund_id Идентификатор возврата в системе Деньги Online integer Обязательный

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

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

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

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

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

 

[
{
"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"
}
]

 

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