API hutko

Accept purchase (merchant payment page)

Only for PCIDSS compliant merchants.

  1. Request parameters(step 1)
  2. Parameters of response (step 1, card is enrolled in 3DSecure service)
  3. Parameters of response (step 1, card is not enrolled in 3DSecure service)
  4. Parameters of request (step 2)
  5. Parameters of response (step 2)
  6. Parameters of response in case of error
  7. Request generation

Request parameters (step 1)

Parameter Type Description Sample
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
order_desc string(1024) Order description. Generated by merchant in UTF-8 always

mandatory
 Hotel booking №1234 Antalia Resort
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
amount integer(12) Order amount in cents without a separator

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
version string(10) Protocol version.

Default value: 1.0.1
 1.0.1
server_callback_url string(2048) Merchant site URL, where host-to-host callback will be send after payment completion. See Receiving Callbacks for more details on callbacks.
http://site.com/callbackurl
lifetime integer(6) Order lifetime in seconds. After this time, the order will be given the status of expired if the client has not paid it

Default value: 600
Maximum allowed value: 69120000
 600
merchant_data string(2048) Any arbitrary set of data that a merchant wants to get back in the response to response_url or/and server_callback_url, and also in reports  
preauth string(1) Parameter supported only for Visa/MasterCard payment method
N — amount is debited from the customer’s card immediately and settled to the merchant account, in accordance with the rules of settlements.
Y — amount held on the customer card and not charged until the merchant sends a ‘capture’ request to confirm

Default value: N
 N
sender_email string(50) Customer email  
descriptor string(21) Dynamic descriptor  
lang string(2) Payment page language. Supported values:
en – Russian
uk – Ukrainian
en – English
lv – Latvian
fr – French
cs – Czech
ro – Romanian
it – Italian
sk – Slovak
pl – Polish
es – Spanish
hu – Hungarian
de – German		  
product_id string(1024) Merchant product or service ID  
verification string(1) If Y order will be automatically reversed by hutko after successful approval

Default value: N
 Y
card_number string(19) Visa/MC card number

mandatory
  
cvv2 string(4) Card CVV2/CVC2 code

mandatory
  
expiry_date integer(4) Card expiry date in format MMYY

mandatory
  
client_ip integer(15) Client IP

mandatory
  
container string Google/Apple Pay encrypted data in BASE64 encoding

optional
 ewogICJhcGlWZXJzaW9uTWlub3IiOiAwLAogICJhcGlWZXJzaW9uIjogMiw
KICAicGF5bWVudE1ldGhvZERhdGEiOiB7CiAgICAiZGVzY3JpcHRpb24iOi
AiVmlzYSDigKLigKLigKLigKIgMTExMSIsCiAgICAidG9rZW5pemF0aW9uR
GF0YSI6IHsKICAgICAgInR5cGUiOiAiUEFZTUVOVF9HQVRFV0FZIiwKICAg
ICAgInRva2VuIjogIntcInNpZ25hdHVyZVwiOlwiTUVRQ0lIZ0tDT2hldFh
5dVl4VXl4cE80NDFab2llR3A3U3duQlVXMjc2Um55S0s4dVM2UVxcdTAwM2
RcXHUwMDNkXCIsXCJwcm90b2NvbFZlcnNpb25cIjpcIkVDdjFcIixcInNpZ
25lZE1lc3NhZ2VcIjpcIntcXFwiZW5jcnlwdGVkTWVzc2FnZVxcXCI6XFxc
IkZhbW9YZEhVZUdMNzUxRnFZbVJwVFNaeTN2aC9lQ1E0ZjNHckUvUFlJV3R
SUnFXVTJZRFg4d3F3OHVXMm1KSi9Yb2VtcmN2SkdlVFJZeFV5eDgvVWVFdn
pwQ0tsVnVqbDMrNHkrTEdmbGFFUWJZeFV5eFl4VXl4WXhVeXhZeFV5eFV5Z
WxBbFRPVXFBSHpwMm5rVEZFY3AvczR2a0tEWm9QVFRjYnBNbC9xaW5qNW1s
ai8ybEZtSmcyUTEydFNCREdaYXd0SG1KeitDNmxMUmZBdDhCOU15RDFJa0V
Nd3JxOTBqMk5GY0dnQ29RbEtaR3hzSUlNcG5GV082TDZxcUsvcGxXNnlYZG
taaDIrR09CREU3eHVSWlY2RkdtZGZ4eGVLWElWTFNsQ3AxdHRlUGR2VDZZT
0R5WXhVeXhZeFV5eFl4VXl4WXhVeXgvcUY0SUJZUTNqalBjRTM3d1h5UHhy
MVhheTJPS0hFZTV4MTZURWdDcTU2QWRYL3hVcDNhVk9SWXhVeXhZeFV5eFl
4VXl4WWxzdlJvazhnb2pER053S2dcXFxcdTAwM2RcXFxcdTAwM2RcXFwiLF
xcXCJlcGhlbWVyYWxQdWJsaWNLZXlcXFwiOlxcXCJCS3BjQWtNWTE1a1BuR
zEwS1V5aGtGbE1qbFVTMFgwMVJ1Z3U1dlR5N1l4VXl4WXhVeXhZeFV5eDJ0
WjdwOTNUV1RTd1pFMDg0VkhHTHZ5aWMyT1VXdGpJNFZUelo4OFxcXFx1MDA
zZFxcXCIsXFxcInRhZ1xcXCI6XFxcImU4Zk5ldVdIUGZiZ0U2dkdzTll4VX
l4WXhVeXhZeFV5eEk2QVU1THZINTcxYzZHZ3NVSFVCa1xcXFx1MDAzZFxcX
CJ9XCJ9IgogICAgfSwKICAgICJ0eXBlIjogIkNBUkQiLAogICAgImluZm8i
OiB7CiAgICAgICJjYXJkTmV0d29yayI6ICJWSVNBIiwKICAgICAgImNhcmR
EZXRhaWxzIjogIjExMTEiCiAgICB9CiAgfQp9

Parameters of response (step 1, card is enrolled in 3DSecure service)

If card is enrolled in 3DSecure, response will be returned in the following format:

Parameter Type Description Sample
response_status string(50) if no error ocured always returned success success
acs_url string(2048) URL of cardholder issuing bank Access Control Server where he must enter 3DSecure password
https://pay.hutko.org/checkout?token=e0a5d4f331806d1e2feb80353b4c44bf6751fc8c
pareq string(20480) Parameter which must be submeted to acs_url  
md string(1024) Unique 3DSecure request ID. Generated by hutko payment gateway  

A merchant receiving this response must build an HTML form and using it submit customer to acs_url. HTML form must be of the following content:

<form name="MPIform" action='${acs_url}' method="POST">
  <input type="hidden" name="PaReq" value='${pareq}'>
  <input type="hidden" name="MD" value='${md}'>
  <input type="hidden" name="TermUrl" value='${TempUrl}'>
</form>

where ${TempUrl} – is merchant URL where customer will be redirected after 3DSecure password verification

The following parameters are returned to URLTempUrl after cardholder password verification:

Parameter Type Description
pares string(20480) Payer authentication result.
Is BASE64 string
md string(1024) Unique 3DSecure request ID.
Generated by hutko payment gateway

Parameters of response (step 1, card is not enrolled in 3DSecure service)

If card is not enrolled response is returned in format 3.2 Parameters of final response

Parameters of request (step 2)

Parameters received in 4.2 Parameters of response (step 1, card is enrolled in 3DSecure service) must be sent to hutko payment gateway in format:

Parameter Type Description Sample
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
pares string(20480) Parameter returned by issuing bank to URL TempUrl after password verification

mandatory
  
md string(1024) Unique 3DSecure request ID. Generated by hutko payment gateway

mandatory
  
version string(10) Protocol version.

Default value: 1.0
 1.0
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

Signature algorithm see Signature generation for request and response

 1773cf135bd89656131134b98637894dad42f808

Parameters of response (step 2)

Response is returned in format 3.2 Parameters of final response

Parameters of response in case of error

Response is returned in format 3.4 Parameters of response in case of error

Request generation

Purchase request with card number in step 1 always generated by merchant using host-to-host request to URL https://pay.hutko.org/api/3dsecure_step1/

Purchase request in step 2 always generated by merchant using host-to-host request to URL https://pay.hutko.org/api/3dsecure_step2/

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.

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