DengiOnline

2017-07-29 03:29:14

Protocol of refunds

Refunds protocol is used to refund a successful transaction or to get information about the refund status. Refunded amount can only be less or equal to the payment amount. The protocol allows to make multi-refunds.

The protocol allows refund for the following paysystems:

  • Bank cards 
  • QIWI-Wallet
  • WebMoney
  • Yandex.Money

If required to refund a payment made by another paysystem please contact technical specialists.

 

Request should be sent using POST to a handler at

https://www.onlinedengi.ru/api/dol/refund/create/ — to refund a successful transaction;

https://www.onlinedengi.ru/api/dol/refund/get/ — to get information about the refund status.

Parameters that should be sent to the system by the project are listed in the table below.

In response to the request the System sends an UTF-8 encoded JSON document with status code and description.Request parameters

Parameter Description Format Mandatory
X-DOL-Project Project identificator in the System. 

Please note: Parameter should be passed via request header, (take heed!) not the request body.
integer Yes
X-DOL-Sign
Control request signature.
Signature is calculated with HMAC-SHA1 algorithm from a request body. Project's secret key being used which is agreed upon during technical integration and approved by both parties (Project and the System) for calculating hash-summs for secure payments from the System to the Project.

Please note: Parameter should be passed via request header, (take heed!) not the request body.
hex

 

Yes
dol_id

Payment identificator in the System.

* In case of several partial refunds for one dol_id, we highly recommend to use the order_id parameter for each refund 

integer Yes
1. Required parameters for refunding a successful transaction
amount

Refund amount.
Only used in case of partial refund. Cannot be more than the original transaction amount.

  • If amount has a value of zero, then the request will be treated as unsuccessful.
  • If amount is not specified, herewith:
    • currency is RUB or not specified, then the refund amount is equal to the payment amount;
    • currency is not RUB, then the refund amount is 0.
float (10.2),
delimiter - dot.
No
currency

Refund currency.

    • If the currency is not specified, the refund currency is considered to be RUB.
    • For the conversion the system uses exchange rate prevailing on the date of the invoice

char(3),
ISO 4217 alfa-3

Possible options: USD, RUB, EUR

No
description Refund reason description. string (1000) No
success Callback for successful refund notification. JSON
Пример: {"success":[{"email":"test@email.ru"}, {"url":"https://testsite.ru/refund/123"}]}
No
fail Callback for failed refund notification. JSON
Пример: {"fail":[{"email":"test@email.ru"}, {"url":"https://testsite.ru/refund/123"}]}
No
order_id

Refund identificator in Project's system. If the parameter is specified check will be perfomed if the ID is unique.

* In case of several partial refunds for one dol_id, we highly recommend to use the order_id parameter for each refund

string (128) No

2. Required parameters for getting information about the refund status
refund_id

Refund identificator in the System.

integer Yes

HTTP Status 200 is the criteria of request processed successfully. In this case the response is JSON with the following tags:

Parameter
Description
Format
refund_id Refund identificator in the System integer
dol_id Payment identificator in the System integer
order_id Refund identificator in Project's system string(128)
amount Refund amount in the refund currency float(10.2)
delimiter - dot.
currency Refund currency char(3), ISO 4217, alfa-3 

Possible options: USD, RUB, EUR
amount_rub Refund amount in RUR float(10.2)
delimiter - dot.
state Refund status code (see the list below) integer
description Refund reason description string 

In the case of failed request HTTP Status is different from 200 and response body contains error description.

The full list of possible HTTP-statuses is available here

Example response for successful refund request:

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

 

Example response for failed refund request: 

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

 

The list of possible errors for refund request:

In case of an error correct the wrong value of the parameter specified in the message for the next request.

Number 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.
12 Refund cannot be made for unsuccessful payments.
13 Refund amount is above the payment's.
14 Wrong refund currency
31 Not unique order_id value
Payment has been returned
100 Internal error


For the refund status request the System sends response in JSON format with refunds list. Parameters of each refund are identical to them of refund request response.

Example response for successful refund status request:

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

 

List of refund status codes:

Code Status of refund
1 Refund performed successfully
2 Refund request is being processed
3 Refund error

Example request code (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);
}
}
 
//To get information about the refund status
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)); }
}
 
//To refund a successful transaction
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); } }