Deposit (host-2-host)¶

According to the rules of Mastercard and Visa payment systems, the PCI DSS certificate (of the appropriate level) is mandatory, as the customer enters the card details on the merchant’s website.

Initial request¶

The request contains certain fields:¶

Field	Description
`type`	transaction type (payment);
`merchant`	unique merchant ID;
`order`	transaction number in the merchant system;
`amount`	transaction amount in the currency, separator character is a point “.”;
`currency`	transaction currency, may take UAH, USD, EUR, KZT, BRL and AZN;
`card_num`	bank card number;
`card_exp_month`	bank card expiration month;
`card_exp_year`	bank card expiration year;
`card_cvv`	cvv of the bank card;
`process_url`	URL for sending the transaction summary status
`item_name`	goods name (an optional field);
`first_name`	card holder name (Only latin chars are available);
`last_name`	card holder surname (Only latin chars are available);
`user_id`	client identifier in the merchant's system (the field is not required);
`payment_url`	url address of the site in whose favor the payment is made;
`country`	customer’s country in the ISO 3166-1 alpha-2 format;
`email`	customer's e-mail;
`phone`	customer's phone number;
`address`	customer's address;
`city`	customer's city;
`post_code`	customer's post code;
`region`	customer's region;
`sign`	digital signature with the merchant’s key. Available fields are: “type”, “merchant”, “order”, “amount”, “currency”, “card_num”, “card_exp_month”, “card_exp_year”, “card_cvv” are used. It is hashed using the SHA256 method. (for more details read the “Digital signature in requests” section);
`browser`	an array in which data about the customer’s browser is transmitted, namely: `accept_header` `color_depth` `ip` `language` `screen_height` `screen_width` `time_different` `window_width` `window_height`.

Important

The query strings must contain only Latin letters and numbers.

POST /api/host2host

https://<provided url>
/api/host2host

Example of the PHP request:

$url = "https:///api/host2host";
$merchant = "M1VJDHSI6DYXS";
$signature = "XXXXXXXXXXXXXXXXXX";
$order_id = "0001";
$data = [
    "type" => "payment",
    "merchant" => $merchant,
    "order" => $order_id,
    "amount" => "10.99",
    "currency" => "UAH",
    "card_num" => "5300111122223333",
    "card_exp_month" => "01",
    "card_exp_year" => "25",
    "card_cvv" => "111",
    "process_url" => "https://test.com/api/callback_url",
    "item_name" => "Samsung TV",
    "first_name" => "IVAN",
    "last_name" => "IVANOV",
    "user_id" => "492235",
    "payment_url" => "https://test.com",
    "country" => "UA",
    "email": "test@gmail.com",
    "phone": "+35988222763",
    "address": "Avenue Marius Renard 21",
    "city": "Anderlecht",
    "post_code": "1070",
    "region": "stuttgart",
    "browser" => [
        "accept_header" => "...",
        "color_depth" => "...",
        "ip" => "...",
        "language" => "...",
        "screen_height" => "...",
        "screen_width" => "...",
        "time_different" => "...",
        "user_agent" => "...",
        "java_enabled" => "...",
        "window_width" => "...",
        "window_height" => "..."
    ],
];
$dataSign = array_filter(
    $data,
    fn ($key) => in_array($key, [ 'type', 'merchant', 'order', 'amount', 'currency', 'card_num', 'card_exp_month', 'card_exp_year', 'card_cvv' ]),
    ARRAY_FILTER_USE_KEY
);

/*
simplified version:
$dataSign = [ $data['type'], $data['merchant'], $data['order'], $data['amount'], $data['currency'], $data['card_num'], $data['card_exp_month'], $data['card_exp_year'], $data['card_cvv'] ];
*/

ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(':', $dataSign);
$sign = base64_encode(hash('sha256', $signString, true));
$data['sign'] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($request))
);
$result = curl_exec($ch);

If the data is successfully received (for further payment), the response contains the fields:¶

Field	Description
`status`	transaction status (3ds);
`merchant`	unique merchant ID;
`order`	transaction number in the merchant system (the same as in the request);
`uuid`	unique transaction ID, use it to search or to contact tech support (if necessary);
`co_inv_id`	unique transaction number;
`d3_acs_url`	link to the 3DS page, where the customer will be redirected;
`d3_pareq`	data for passing;
`d3_md`	data for passing.

Example of the response:

application/json

{
    "status": "3ds",
    "merchant": "M1VJDHSI6DYXS",
    "order": "0001",
    "uuid": "ABC123abc123",
    "co_inv_id": 1111111,
    "d3_acs_url": "https://3ds.bank.ua",
    "d3_pareq": "eJxVUt...tuwjAM/RX==",
    "d3_md": "1:809b...82316eb"
}

If the payment is canceled, the response contains certain fields:¶

Field	Description
`status`	transaction status (error);
`code`	error code;
`description`	description error.

Example of the response:

application/json

{
    "status": "error",
    "code": "10",
    "description": "The order is already in the system. Request a status."
}

Redirection of the Customer to the 3DS Form¶

In case of positive response, the merchant must redirect the customer to the 3DS form. Use the options from the response at the initial request for this.

Note: the return of the user to your specified TermUrl can be performed using either the GET or POST method.

3DS form

<form name="MPIform" action="{{ d3_acs_url }}" method="POST" target="_blank">
    <input type="text" name="PaReq" value="{{ d3_pareq }}" />
    <input type="text" name="MD" value="{{ d3_md }}" />
    <input type="text" name="TermUrl" value="{{ URL }}" />
    <button type="submit">Send</button>
</form>

Final request¶

Pay attention! Do not mistake d3_pares and d3_pareq:

you receive d3_pareq in response to the initial request and send it to the 3DS form;
you receive d3_pares from the 3DS form and send in the final request.

The request contains the fields:¶

Field	Description
`type`	type (3ds);
`merchant`	unique merchant ID;
`uuid`	unique transaction ID (you receive this option in the response at the initial request);
`order`	transaction number in the merchant system (the same as in the initial request);
`d3_pares`	you receive it in the response from the 3DS form;
`d3_md`	data for passing (you receive it in the response at the initial request);
`sign`	digital signature with the merchant’s key. Available fields are: “type”, “merchant”, “order”, “uuid”, “d3_md”. It is hashed using the SHA256 method. (for more details read the “Digital signature in requests” section)

POST /api/host2host

https://<provided url>
/api/host2host

Example:

$data = [
    "type" => "3ds",
    "merchant" => $merchant,
    "uuid" => "BILLLINE ID",
    "order" => "Your ID value",
    "d3_pares" => $d3_pares,
    "d3_md" => $d3_md,
];
$dataSign = array_filter(
    $data,
    fn ($key) => in_array($key, [ "type", "merchant", "order", "uuid", "d3_md" ]),
    ARRAY_FILTER_USE_KEY
);

/*
simplified version:
$dataSign = [ $data["type"], $data["merchant"], $data["order"], $data[" uuid "], $data["d3_md"] ];
*/

$dataSign = [ $data["type"], $data["merchant"], $data["order"], $data[" uuid "], $data["d3_md"] ];
ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(":", $dataSign);
$sign = base64_encode(hash("sha256", $signString, true));
$data["sign"] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Content-Length:" . strlen($request))
);
$result = curl_exec($ch);

If the query is successfully processed, the response contains the fields:¶

Field	Description
`status`	payment status (success);
`merchant`	unique merchant ID;
`uuid`	unique transaction ID, use it to search or to contact tech support (if necessary);
`order`	transaction number in the merchant system (the same as in the request).

Example of the response:

application/json

{
    "type" : "3ds",
    "merchant" : "M1VJDHSI6DYXS",
    "uuid" : "ABC123abc123",
    "order" : "0001",
    "d3_pares" : "eJzVmNmS...ovrSsTczhh==",
    "d3_md" : "1:809b...82316eb",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

In case of the payment error, the response contains the fields:¶

Field	Description
`status`	transaction status (error);
`code`	error code;
`description`	description error.

Example of the response:

application/json

{
    "status": "error",
    "code": "2",
    "description": "Incorrect request details"
}

Final status (callback)¶

The callback mechanism is used to notify the merchant that the transaction has received a final status (for example, from “Pending” to “Success”).

For more information read the Callbacks section.