Mobile Commerce (KZT)¶

Initial Request¶

Headers:¶

Field	Description
`X-Merchant`	unique merchant identifier;
`X-Sign`	digital signature using the merchant key. All fields in the request body are used. Hashed as HMAC with SHA256;

Request fields:¶

Field	Description
`order`	transaction number in the merchant system;
`amount`	transaction amount in currency, decimal separator “.”;
`currency`	transaction currency, can be KZT;
`user_id`	customer identifier in the merchant system;
`payment_url`	URL of the website receiving the payment;
`email`	payer’s email;
`phone`	payer’s phone number, digits only, without the “+” sign.

Important

Request strings must contain only Latin letters and numbers.

POST /api/v2/mobile/host2host/create

https://<provided_url>
/api/v2/mobile/host2host/create

PHP Request Example:

$url = "https://{provided_url}/api/v2/mobile/host2host/create";
$merchant = "M1VJDHSI6DYXS";
$secret_key = "XXXXXXXXXXX";
$order_id = "12456789";
$data = [
    "order" => $order_id,
    "amount" => "10.99",
    "currency" => "KZT",
    "user_id" => "492235",
    "payment_url" => "https://test.com/test",
    "email" => "test@gmail.com",
    "phone" => "77771209123"
];

$request = json_encode($data, JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
$hashHex = hash_hmac('sha256', $request, $secret_key);
$signature = base64_encode($hashHex);
$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',
    'X-Merchant: ' . $merchant,
    'X-Sign: ' . $signature)
);
$result = curl_exec($ch);

Successful response fields (for further payment processing):¶

Field	Description
`status`	request status (pin); Important: this is the request status, not the transaction status. It shows that the data has been correctly received by the server but does not reflect the actual transaction result;
`pinUrl`	URL to send the confirmation code;
`transactionId`	unique transaction number;
`merchantUuid`	unique merchant identifier;
`uuid`	unique transaction identifier (use for tracking or support);
`order`	transaction number in the merchant system (same as request);
`description`	transaction description.

Example Response:

application/json

{
    "status": "pin",
    "pinUrl": "https://{provided_url}/api/v2/mobile/host2host/FUHKN7RRPWFB3/confirm",
    "transactionId": 44938834,
    "merchantUuid": "M1VJDHSI6DYXS",
    "uuid": "FUHKN7RRPWFB3",
    "order": "12456789",
    "description": "success"
}

Error response fields:¶

Field	Description
`status`	request status (error);
`pinUrl`	URL for confirmation code;
`transactionId`	unique transaction number;
`merchantUuid`	unique merchant identifier;
`uuid`	unique transaction identifier (use for tracking or support);
`order`	transaction number in the merchant system (same as request);
`description`	transaction description.

Example Response:

application/json

{
    "status": "error",
    "pinUrl": "",
    "transactionId": 0,
    "merchantUuid": "",
    "uuid": "",
    "order": "",
    "description": "The order already exists"
}

Sending the Confirmation Code¶

After a positive response, the merchant must send the confirmation code. Use pinUrl from the initial response and the code received on the phone.

Headers:¶

Field	Description
`X-Merchant`	unique merchant identifier;
`X-Sign`	digital signature using the merchant key. All fields in the request body are used. Hashed as HMAC with SHA256.

Final request fields:¶

Field	Description
`pin`	confirmation code received on the phone.

POST /api/v2/mobile/host2host/{uuid}/confirm

https://<provided_url>
/api/v2/mobile/host2host/{uuid}/confirm

Example:

X-Merchant: BCSPXMGIDSKUB
X-Sign: XXXXXXXXXXXXXXXXXX

$url = "https://{provided_url}/api/v2/mobile/host2host/{uuid}/confirm";
$merchant = "M1VJDHSI6DYXS";
$secret_key = "XXXXXXXXXX";
$data = [
    "pin" => "123456"
];

$request = json_encode($data, JSON_UNESCAPED_UNICODE);
$hashHex = hash_hmac('sha256', $request
$signature = base64_encode($hashHex);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST
curl_setopt($ch, CURLOPT_POSTFIELDS, $

Successful response fields:¶

Field	Description
`status`	payment status (confirm);
`description`	payment description.

Example Response:

application/json

{
    "status": "confirm",
    "description": "Success"
}

Error response fields:¶

Field	Description
`status`	payment status (error);
`description`	error description.

Example Response:

application/json

{
    "status": "error",
    "description": "error"
}

Important

Status confirm is not the final payment status. Wait for the callback.

Final Status (Callback)¶

Merchants are notified of the final transaction status (e.g., from Pending to Success) via callbacks.

Detailed description in the “Callbacks” section: