2017-07-29 03:29:15

Card Hold

Card hold — is an operation of blocking a certain amount of money at the time of the credit card payment transaction.

To enable hold procedure the Project should during the integration choose the way to recieve funds: through hold or direct.

Note that using hold along with direct payments is not allowed.

For card hold procedure the Project is to provide the following data to the System technical specialist in advance. 

  1. Hold period — time period when the funds are available for payment.

  2. Action to be performed with the funds after the expiration of the hold period indicated in the previous passage. There are 2 actions available for the Project:

    • Complete — hold settlement (payment confirmation). In this case the funds are transferred to the Project.

    • Reversal — hold canceling. The funds are returned to the payer.

  3. Hold notification — you can choose whether notification about the hold should or should not be sent to the Project.

  4. URL-address for hold notifications (by default notifications are sent to the Project main URL).

1. Invoicing in case of card hold

The procedure is the same as in case of General invoicing procedure

2. Notifications to the Project in case of card hold

After creating an invoice on the System side, the System notifies the Project.

Notification about the card hold is similar to the general notification, but some extra parameters are added.

Parameter Description Format Mandatory


Hold expiration date and time

YYYY-MM-DD hh:mm:ss



Action to be performed by default after the hold expiration
Available values:

  1. complete — hold settlement (payment confirmation)

  2. reversal — hold canceling. The funds are returned to the payer



Every notification request from the System should be answered by the Project with UTF-8 encoded XML containing the following parameter:

Parameter Value Description




The Project confirmed that transaction funds are put on hold.


Equals to the REVERSAL action (the funds are returned to the payer).

If the response is not received, the System will keep trying to notify the Project again in 30sec, 5m, 5m, 5m, 5m, 20m, 20m... until the hold expires (default expiration period is used).

3. Hold API

The Project sends a UTF-8 encoded request using the POST method to the System handler located at the page

The Project can perform the following actions with the funds put on hold (transactions with the "Frozen" status):

  1. Settlement (Complete) — upon the Project request (see parameters in the table below) or automatically (the action to be performed on the hold expiration is the funds transfer from the payer's card.

  2. Hold canceling (Reversal) — upon the Project request (see parameters in the table below) or automatically (the action to be performed on the hold expiration is the hold canceling and the funds return.

Request parameters for card hold confirmation 

Parameter Description Format Mandatory


Project ID in the System 

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




Request signature.

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

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




Payment ID in the System




Expected action
Possible values:

  • complete — settlement (payment confirmation)

  • reversal — hold canceling



After processing the data provided by the Project the System sends a response in JSON format containing the following nodes: 

Parameter Description Format


Request status

1 – successful request
0 – failed request


Operation code



Operation description



Hold status codes and comments

Code Comment Final status?
400 Bad request

The status is final. Check request parameters

404 Not found The status is final. Check request parameters

Payment does not have hold status.

Complete/Reversal actions are impossible

The status is not final.

Check the pre-authorization payment status ("22, 25 - Hold" are wanted) and repeat the request

501 Payment is already done The status is final.
No additional actions needed
506 Payments is already cancelled
508 Confirmation request is successfully received

The status is not final. If repeated, recommended frequency – one in an hour.

It is not the payment status!

To ensure the payment is successful or cancelled – check the payment status

509 Canceling request is successfully received

NOTE! If the hold is not accepted by the Projects, upon the hold expirations the funds will be either transferred or returned to the payer depending on the default settings of the Project.

Hold canceling request example


Response example (success) 

"comment":"Pre-authorization canceling request is successfully sent"}]

Response example (failure) 

"comment":"Temporary server failure, try repeating your request later"}]

Example of a PHP query 

$project = 1234; 
$key = '123456'; 
$client = new DolClient($project, $key, ''); 
$response = $client->request(array('dol_id' => 239338949, 'action' => 'reversal')); 
echo "<br>  Operation status: ". $response -> status. "<br>  Description code: ". $response -> code. "<br>  Code comment: ".$response -> comment. "<br>"; 
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; } 
{ $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_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); 
if ($curl_errno> 0) 
{ throw new Exception($curl_error, $curl_errno); } 
if ($http_code != 200) 
{ throw new Exception($response, $http_code); } 
var_dump($response); returnjson_decode($response);