DengiOnline

2017-12-11 18:18:17

Recurrent payments

Recurrent (periodic) payment — implies writing off funds from the payer's bank card (e-wallet) without notice in favor of the Project. Recurrent payments always provide links to the parent payment. 

Parent payment — is a payment with extra subscription attributes, designed for recurrent payments initialization in future. 

Structure: 

  • Parent payment
    • recurrent payment 1
    • recurrent payment 2
    • ...
    • recurrent payment N


Stages of creating and conducting parent payments

1. Create the parent payment

It is created as a regular payment (via the invoice creating procedure through the Main protocol) and then additional parameters are added.

Request parameters for the parent payment
Parameter Description Format Mandatory
recurrent_init Initiation of the parent recurrent payment without any specified period The value is to be equal to "1". Yes
payment_period Recurrent payments period (days) integer
Recommended values — 7, 14, 30, etc.
Yes
closed_at Recurrent payments termination date Date in the YYYY-ММ-DD format Yes

The project sends a request using the POST method to the System handler located at https://www.onlinedengi.ru/wmpaycheck.php.

2. The parent payment is to be delivered successfully 

NOTE! If the parent payment doesn't have the Success status (even if the funds have been transferred, but the notification has not been delivered to the Project), then the payment is not recognized as a parent payment. 

Actions available with recurrent payments in the System

NOTE! All actions are available only to the Projects for which recurrent payments are allowed.

To perform an action the Project send a UTF-8 encoding request with the set of parameters (mandatory and additional) via POST method to the specified URL:

  Action Address the System handler located at
1 Retrieving information about recent parent payments (max 5000 payments) https://www.onlinedengi.ru/api/dol/recurent/get/
2 Retrieving information about recent recurrent payments (max 5000 payments) https://www.onlinedengi.ru/api/dol/recurent/list/
3 Changing the period of recurrent payment or suspending it https://www.onlinedengi.ru/api/dol/recurent/change/
4 Initializing the recurring payment based on the parent payment https://www.onlinedengi.ru/api/dol/recurent/init/

A successful request to the System results in getting HTTP Status 200. In case of failure, the Project will receive another HTTP Status (other than 200) and the body of the message will contain error description. The full list of HTTP statuses that can be returned by the System is available here.

Request parameters obligatory for any action with recurrent payments:  

Parameter Description Format Mandatory

X-DOL-Project

Project ID in the System 

NOTE! The parameter value must be placed in the request header and not in the body.

integer

Yes

X-DOL-Sign

Request signature.

Created from the complete body of the request using the HMAC-SHA1 algorithm. A request is generated using the key which is a project secret word, agreed by the parties and used to generate the HASH code when prompted to carry out a payment from the System to the Project. 

NOTE! The parameter value must be placed in the request header and not in the body.

hex

Yes

dol_id

Payment ID in the System

integer

Yes*

 * The dol_id parameter is mandatory if the paymode parameter is not specified in the action, and is optional if the paymode value is specified. If both parameters are sent, the dol_id value is used.

1. Retrieving information about recent parent payments (max 5000 payments) 

To perform an action the Project send a UTF-8 encoding request with the set of parameters (mandatory and additional) via POST method to https://www.onlinedengi.ru/api/dol/recurent/get/

Additional parameters for retrieving information about recent parent payments (max 5000)

Parameter Description Format Mandatory

paymode

Payment mode ID

integer

No
If neither of the dol_id or paymode parameters is specified, the action returns error message «Payment not found».

start

Beginning of the selection period

YYYY-ММ-DD HH:ММ:SS format

No
If the parameters are not indicated then all parent payments are selected (limited to the last 5000).

 

end

End of the selection period

YYYY-ММ-DD HH:ММ:SS format

After processing the data provided by the Project, the System returns a JSON response which contains the following tags (alongside the dol_id and/or paymode parameters): 

Parameter Description Format

nick

User or Order ID

varchar

status

Payment status

Success

amount_rub

Payment amount in rubles.

decimal(10.2)

date_payment

Parent payment date

YYYY-ММ-DD HH:ММ:SS format

count

The number of successful payments for the parent payment.

integer

last_payment

The last recurrent payment date

YYYY-ММ-DD HH:ММ:SS format

period

Payment interval

integer (days)

message

Error message

string

Possible options

  • Payment inactive or unsuccessful
  • Not valid date format
  • Payment not found

error

Error code (in case of an error)

integer

Request and response examples

Request Response example in case of success Response example in case of failure

{"dol_id":146785469}

{
"dol_id":146785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"period":"30",
"count":1,
"last_payment":"2013-05-03 18:45:33", "date_payment":"2012-11-22 10:58:39"
}

 

{"paymode":34}

{
"dol_id":146785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"period":"30",
"count":1,
"last_payment":"2013-05-03 18:45:33", "date_payment":"2012-11-22 10:58:39"
},
{
"dol_id":200780469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"20.00",
"period":"360",
"count":10,
"last_payment":"2013-10-30 15:05:20", "date_payment":"2012-11-22 10:58:39"
}

 

{"start":"2013.05.01", "end":"2013.06.01", "paymode":34}

--

{
"error":4,
"message":"Not valid date format",
}

2. Retrieving information about recent recurrent payments (max 5000 payments) 

To perform an action the Project send a UTF-8 encoding request with the set of parameters (mandatory and additional) via POST method to https://www.onlinedengi.ru/api/dol/recurent/list/

Additional parameters for retrieving information about recent recurrent payments (max 5000)

Parameter Description Format Mandatory

paymode

Payment mode ID

integer

No
If neither of the dol_id or paymode parameters is specified, the action returns error message «Payment not found».

start

Beginning of the selection period

YYYY-ММ-DD HH:ММ:SS format

No
If the parameters are not indicated then all recurrent payments are selected (limited to the last 5000).

 

end

End of the selection period

YYYY-ММ-DD HH:ММ:SS format

status

Payment status

string 

Possible options:

  • New
  • Success
  • Fail
  • In progress
  • Fatal
  • Decline

No

After processing the data provided by the Project, the System returns a JSON response which contains the following tags (alongside the dol_id and/or paymode parameters):

Parameter Parameter description Format

nick

User or Order ID

varchar

status

Payment status

string 

Possible options:

  • New
  • Success
  • Fail
  • In progress
  • Fatal
  • Decline

amount_rub

Payment amount in rubles

decimal(10.2)

date_payment

Recurrent payment date

YYYY-ММ-DD HH:ММ:SS format

parent

Parent payment ID

integer

message

Error message

string 

Possible options:

  • Payment inactive or unsuccessful
  • Not valid date format
  • Payment not found

error

Error code (in case of an error)

integer

Request and response examples 

Request Response example in case of success Response example in case of failure

{"start":"2013-05-01", "end":"2013-06-01", "paymode":34}
{"start":"2013-05-01", "end":"2013-06-01", "status":"Success"}

{
"dol_id":186785469,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"parent": 177783562,
"date_payment":"2013-05-03 18:45:33"
},
{
"dol_id":186785569,
"paymode":"34",
"status":"Success",
"nick":"UserNICK",
"amount_rub":"3.00",
"parent": 177783562,
"date_payment":"2013-05-04 18:45:33"
}

 

3. Change period of recurrent payment or suspending it

To perform an action the Project send a UTF-8 encoding request with the set of parameters (mandatory and additional) via POST method to https://www.onlinedengi.ru/api/dol/recurent/change/

3.1. Changing recurrent payment period 

Additional parameters for the recurrent payment period change
Parameter Description Format Mandatory
period New payment period (days) integer Yes

After processing the data provided by the Project, the System returns a JSON response which contains the following tags (alongside the dol_id parameter): 

Parameter Description Format

message

Message about payment status change

string 

Possible options:

  • Period updated

  • No change

  • Payment inactive or unsuccessful

  • Payment not found

 

error

Error code (in case of an error)

integer

Request and response examples 

Request Response example in case of success

Response example in case of failure

{"dol_id":177783562, "period":360}

{
"dol_id":177783562,
"message":"Period updated",
}

 

3.2. Suspending recurrent payments

Additional parameters for the parent payment closing

Parameter Description Format Mandatory

close

Command to close the parent payment

Value: close = 1

Yes

After processing the data provided by the Project, the System returns a JSON response which contains the following tags (alongside the dol_id parameter):

Parameter Description Format

message

Message about payment status change

string 

Possible options:

  • Recurring payment stopped

  • No change

  • Payment inactive or unsuccessful

  • Payment not found

 

error

Error code (in case of an error)

integer

Request and response examples 

Request Response example in case of success

Response example in case of failure

{"dol_id":177783562, "close":1}

{
"dol_id":177783562,
"message":"Recurring payment stopped",
}

{
"error":4,
"message":"Payment inactive or unsuccessful",
}

4. Initializing recurring payments based on the parent payment 

To perform an action the Project send a UTF-8 encoding request with the set of parameters (mandatory and additional) via POST method to https://www.onlinedengi.ru/api/dol/recurent/init/

Additional parameters for recurrent payments initialization based on the parent payment 

Parameter Description Format Mandatory

amount_rub

Payment amount (only rubles).

double (4)

No
In case the value is not specified, the amount will be equal to the parent payment amount.

After processing the data provided by the Project, the System returns a JSON response which contains the following tags:

Parameter Description Format
dol_id

Payment ID in the System

If a payment (successful or unsuccessful) is created in the system, then the new dol_id will be generated

integer

message

Message about payment status change

string 

Possible options:

  • Success

  • In progress

  • Fail

  • Decline

  • Fatal

  • Closed

  • Recurrent not allowed

  • Payment not found

error

Error code (in case of an error)

integer

Request and response examples 

Request Response example in case of success

Response example in case of failure

{"dol_id":177783562, "amount_rub":300} {
"dol_id":177783575,
"message":"Success",
}
{
"message":"Payment not found",
"error":"4", 
}

List of possible request processing errors 

Number

Description

Is it possible to send requests using identical parameters?

Ways to solve the problem

2

An error occurred while initializing the payment

Yes

Try to repeat sending request

4

Payment initialization is not possible

No

No additional actions needed

6

Authorization declined

Yes

Try to repeat sending request

Example of a PHP request 

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);
    }
}
$project= 1234;
$key = 123456;
  
// Retrieving information about recent parent payments
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/get/');
$response = $client->request(array('paymode' => 57));
  
//Retrieving information about recent recurrent payments
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/list/');
$response = $client->request(array('paymode' => 57, 'start' => "2014-01-30"));
  
//Initializing the recurring payment based on the parent payment
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/init/');
$response = $client->request(array('dol_id' => 242479910, 'amount_rub' => '0.5'));
  
//Changing the recurrent payment period or closing the recurring payment
$client = new DolClient($project, $key, 'https://www.onlinedengi.ru/api/dol/recurent/change/');
$response = $client->request(array('dol_id' => 242479910, 'close' => 1));