API hutko

Capture pre-purchase

  1. The correct operations sequence
  2. Request parameters
  3. Response parameters
  4. Parameters of response in case of error
  5. Request generation

The correct sequence of steps for the capture operation

The capture operation is designed to charge the amount previously hold on the card with request for pre-authorization with the parameter preauth = Y .

This operation is also called a two-stage payment scheme. The first stage is a purchase operation with preliminary hold of the amount. The second stage is the capture of a blocked amount.

The capture can be performed both in full or in partial amount.

Notice!

  • The pre-authorization and capture operations are available only by the card payment method. The remaining payment methods do not support these operations and the full amount will be automatically charged according to the one-stage scheme:
  • If the capture operation has not yet been completed, then hutko commission is not charged on refund operation. In fact, an instant cancellation of the blocked amount takes place and no financial movements occur;
  • If the capture operation has not yet been completed, then only reversal of the full holding amount is available;
  • If a partial capture operation is performed, the rest of the amount will automatically be returned to the payer’s card and reverse operation is no longer necessary.
    For example, if the pre-authorization amount is 1000 and the client needs to return 200, then you need to capture in the amount of 800. You do not need to reverse the amount of 200 , otherwise the amount 200 will be returned twice;
  • Only one full / partial capture is available for pre-authorization operation;
  • For one captured purchase operation, several consecutive partial reverses are available;

Request parameters

Parameter Type Description Example
order_id string(1024) Order ID which is generated by merchant.

mandatory
 ID1234
merchant_id integer(12) Merchant unique ID. Generated by hutko during merchant registration.

mandatory
 1
signature string(40) Order signature. Required to verify merchant request consistency and authenticity. Signature generation algorithm please see at Signature generation for request and response

mandatory
1773cf135bd89656131134b98637894dad42f808
version string(10) Protocol version.

Default value: 1.0
 1.0
amount integer(12) Capture amount

mandatory
 1020 (EUR)
means 10 euros and 20 cents
currency string(3) Order currency. Supported values:
EUR — Euro
USD — US Dollar
GBP — Pound sterling
UAH — Ukrainian Hryvnia

mandatory
 USD

Response parameters

Parameter Type Description Example
order_id string(1024) Order ID which is generated by merchant. ID1234
merchant_id integer(12) Merchant unique ID. Generated by hutko during merchant registration. 1
capture_status string(50) Capture processing status. Can contain next values:
hold — capture is declined by hutko payment gateway or by bank or by external payment system
captured — capture completed successfully		 approved
response_status string(50) Request processing status. If parameters sent by merchant did not pass validation then failure, else success  
signature string(40) Order signature. Required to verify merchant request consistency and authenticity. Signature generation algorithm please see at Signature generation for request and response
1773cf135bd89656131134b98637894dad42f808
response_code integer(4) Response decline code 1008
response_description string(1024) Response decline reason Parameter `amount` is mandatory

Parameters of response in case of error

See Parameters of response in case of error

Request generation

Capture request always generated by merchant using host-to-host request to URL https://pay.hutko.org/api/capture/order_id

Host-to-host API supports the following text formats:

Response is always returned in request context in the same content-type. So if request is sent in JSON, response will be sent in JSON format too.

Example host-to-host JSON

Content Type: application/json

Request

{
   "request":{
      "order_id":"test7926651365",
      "currency":"USD",
      "amount":"1",
      "merchant_id":"1",
      "signature":"b1ed592ff76ddca287503b11c1aad70bb1c67f37"
   }
}

Normal response

{
   "response":{
      "order_id":"test309906285",
      "response_status":"success",
      "response_code":"",
      "capture_status":"captured",
      "response_description":"",
      "merchant_id":"1"
   }
}

Response in case of error

{
   "response":{
      "response_status":"failure",
      "error_message":"Order Not Found",
      "error_code":"1018"
   }
}

Example host-to-host XML

Content Type: application/xml

Request

<?xml version="1.0" encoding="UTF-8"?>
<reqest>
   <order_id>test7926651365</order_id>
   <currency>USD</currency>
   <amount>1</amount>
   <merchant_id>1</merchant_id>
   <signature>b1ed592ff76ddca287503b11c1aad70bb1c67f37</signature>
</request>

Normal response

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <order_id>test6622534987</order_id>
   <response_status>success</response_status>
   <response_code />
   <capture_status>captured</capture_status>
   <response_description />
   <merchant_id>1</merchant_id>
</response>

Response in case of error

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <response_status>failure</response_status>
   <error_message>Order Not Found</error_message>
   <error_code>1018</error_code>
</response>

Example host-to-host HTML form

Content Type: application/x-www-form-urlencoded

Request

order_id=test6622534987&currency=USD&amount=1&merchant_id=1
&signature=6ccbfeb82894b5c51855e032da1e7a3bee65f3a3

Normal response

order_id=test7101250216&response_status=success&response_code=
&capture_status=captured&response_description=&merchant_id=1

Response in case of error

response_status=failure&error_message=Order+Not+Found&error_code=1018

Хочу приймати платежі з Hutko!