Bank Cards (TRY)¶

According to the rules of Mastercard and Visa payment systems, having a PCI DSS certificate (of the appropriate level) is mandatory as the client enters 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, can be set to TRY;
`card_num`	card number;
`card_exp_month`	month of card expiration;
`card_exp_year`	year of card expiration;
`card_cvv`	card CVV;
`process_url`	URL for sending the transaction summary status;
`item_name`	product name (field is optional);
`first_name`	client’s first name. Maximum length is 30 characters (only Latin and Turkish letters are allowed);
`last_name`	card holder surname (Only latin chars are available);
`user_id`	client’s identifier in the merchant’s system (field is optional);
`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`	payer’s e-mail;
`tckm`	turkish identification number;
`year_of_birth`	user’s year of birth. Format: 4(fixed) 1995;
`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`	array containing browser data, including: `accept_header` `color_depth` `ip` `language` `screen_height` `screen_width` `time_different` `window_width` `window_height`.

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" => "TRY",
    "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" => "TR",
    "email" => "test@gmail.com",
    "tckm" => "97462830571",
    "year_of_birth" => "1995",
    "browser" => [],
];

Successful data reception (for further payment processing) response contains 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 declined, 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": "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.

3DS form

<form action="{{ d3_acs_url }}" method="POST">
    <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,
];

Successful request processing response contains 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"
}

If payment fails, the response contains 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)¶

To notify the merchant that the transaction has received the final status (e.g., from “Pending” to “Success”), the callback mechanism is used.

It is described in detail in the “Callbacks” section.