Прием платежей

В этом разделе описана механика, при которой FreedomPay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.

Прием платежей с помощью банковских карт и мобильной коммерции может проводиться в тестовом режиме. Другие способы будут доступны только в боевом режиме.
Платежная страница

Инициализация платежа

Инициализация платежа
Запрос:
curl --location --request POST 'https://api.freedompay.uz/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'
Ответ:
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.freedompay.uz/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = $requestForSignature = [
	'pg_order_id' => '23',
	'pg_merchant_id'=> $pg_merchant_id,
	'pg_amount' => '25',
	'pg_description' => 'test',
	'pg_salt' => 'molbulak',
	'pg_currency' => 'KZT',
	'pg_check_url' => 'http://site.kz/check',
	'pg_result_url' => 'http://site.kz/result',
	'pg_request_method' => 'POST',
	'pg_success_url' => 'http://site.kz/success',
	'pg_failure_url' => 'http://site.kz/failure',
	'pg_success_url_method' => 'GET',
	'pg_failure_url_method' => 'GET',
	'pg_state_url' => 'http://site.kz/state',
	'pg_state_url_method' => 'GET',
	'pg_site_url' => 'http://site.kz/return',
	'pg_payment_system' => 'EPAYWEBKZT',
	'pg_lifetime' => '86400',
	'pg_user_phone' => '77777777777',
	'pg_user_contact_email' => 'mail@customer.kz',
	'pg_user_ip' => '127.0.0.1',
	'pg_postpone_payment' => '0',
	'pg_language' => 'ru',
	'pg_testing_mode' => '1',
	'pg_user_id' => '1',
	'pg_recurring_start' => '1',
	'pg_recurring_lifetime' => '156',
	'pg_receipt_positions' => [
		[
			// В случае формирования чеков в Республике Узбекистан, в параметре "name" необходимо передавать
			// дополнительные значения в определённой последовательности.
			// Детальную информацию можно найти в разделе "Особенности формирования фискальных чеков"
			'name' => 'название товара',
			'count' => '1',
			'tax_type' => '3',
			'price' => '900',
		]
	],
	'pg_user_id' => '1',
	'pg_param1' => 'дополнительные данные',
	'pg_param2' => 'дополнительные данные',
	'pg_param3' => 'дополнительные данные',
];

/**
 * Функция превращает многомерный массив в плоский
 */
function makeFlatParamsArray($arrParams, $parent_name = '')
{
	$arrFlatParams = [];
	$i = 0;
	foreach ($arrParams as $key => $val) {
		$i++;
		/**
		 * Имя делаем вида tag001subtag001
		 * Чтобы можно было потом нормально отсортировать и вложенные узлы не запутались при сортировке
		 */
		$name = $parent_name . $key . sprintf('%03d', $i);
		if (is_array($val)) {
			$arrFlatParams = array_merge($arrFlatParams, makeFlatParamsArray($val, $name));
			continue;
		}
		$arrFlatParams += array($name => (string)$val);
	}

	return $arrFlatParams;
}

// Превращаем объект запроса в плоский массив
$requestForSignature = makeFlatParamsArray($requestForSignature);

// Генерация подписи
ksort($requestForSignature); // Сортировка по ключю
array_unshift($requestForSignature, 'init_payment.php'); // Добавление в начало имени скрипта
array_push($requestForSignature, $secret_key); // Добавление в конец секретного ключа

$request['pg_sig'] = md5(implode(';', $requestForSignature)); // Полученная подпись
Есть два варианта использования метода:

  • Прямая передача данных от мерчанта в FreedomPay
  • Передача данных через браузер пользователя в FreedomPay
При прямой передаче данных от мерчанта в FreedomPay, мерчант должен посылать данные на init_payment.php.
При передаче данных через браузер пользователя в FreedomPay, мерчант должен направить пользователя с данными на payment.php.
Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.
Имена дополнительных параметров мерчанта должны быть уникальны.
После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу, где плательщик завершает платеж.
В случае успеха пользователь будет перенаправлен на страницу оплаты.
В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте freedompay.uz.

URL запроса
POST https://api.freedompay.uz/init_payment.php
Поля запроса

Параметры ответа
Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Для использования данного запроса Вам следует обратиться к своему менеджеру.
Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

FreedomPay передает информацию о номере, свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.
Check URL на стороне мерчанта должен быть общедоступным, без авторизации.
Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности платежа пропускается и считается, что магазин согласен принять платеж.
  • В случае если магазин подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.
  • В случае отказа от платежа rejected.
  • error - ошибка в интерпретации данных.

URL запроса
POST {{check_url}}

Поля запроса

Запрос на result_url магазина. Результат платежа
Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Result URL на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.

Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных

URL запроса

POST {{result_url}}

Поля запроса

Возврат покупателя на сайт мерчанта

После завершения платежа в online платежной системе, покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.


Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. мерчанта должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.

Необходимо четко понимать разницу между Result URL и Success URL.


Result URL вызывается напрямую с сервера FreedomPay, в то время как Success URL вызывается браузером пользователя, когда FreedomPay перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который FreedomPay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

URL запроса

POST {{success_url}} или {{failure_url}}

Поля запроса
Платежный фрейм

Инициализация платежа


Инициализация платежа

Запрос
curl --location --request POST 'https://api.freedompay.uz/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_payment_route=frame' \
--form 'pg_user_id=12345' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>123456789</pg_payment_id>
    <pg_redirect_url>https://api.freedompay.uz/v1/merchant/12345/card/payment?pg_payment_id=12343245dfsdfij123</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>some_random_string</pg_salt>
    <pg_sig>your_signature</pg_sig>
</response>
Есть два варианта использования метода:
  • Прямая передача данных от мерчанта в FreedomPay
  • Передача данных через браузер пользователя в FreedomPay
При прямой передаче данных от мерчанта в FreedomPay, мерчант должен посылать данные на init_payment.php.

При передаче данных через браузер пользователя в FreedomPay, мерчант должен направить пользователя с данными на payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.
После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте FreedomPay.

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = $requestForSignature = [
	'pg_order_id' => '23',
	'pg_merchant_id'=> $pg_merchant_id,
	'pg_amount' => '25',
	'pg_description' => 'test',
	'pg_salt' => 'molbulak',
	'pg_payment_route' => 'frame',
	'pg_currency' => 'KZT',
	'pg_check_url' => 'http://site.kz/check',
	'pg_result_url' => 'http://site.kz/result',
	'pg_request_method' => 'POST',
	'pg_success_url' => 'http://site.kz/success',
	'pg_failure_url' => 'http://site.kz/failure',
	'pg_success_url_method' => 'GET',
	'pg_failure_url_method' => 'GET',
	'pg_state_url' => 'http://site.kz/state',
	'pg_state_url_method' => 'GET',
	'pg_site_url' => 'http://site.kz/return',
	'pg_payment_system' => 'EPAYWEBKZT',
	'pg_lifetime' => '86400',
	'pg_user_phone' => '77777777777',
	'pg_user_contact_email' => 'mail@customer.kz',
	'pg_user_ip' => '127.0.0.1',
	'pg_postpone_payment' => '0',
	'pg_language' => 'ru',
	'pg_testing_mode' => '1',
	'pg_user_id' => '1',
	'pg_recurring_start' => '1',
	'pg_recurring_lifetime' => '156',
	'pg_receipt_positions' => [
		[
			'count' => '1',
			'name' => 'название товара',
			'tax_type' => '3',
			'price' => '900',
		]
	],
	'pg_user_id' => '1',
	'pg_param1' => 'дополнительные данные',
	'pg_param2' => 'дополнительные данные',
	'pg_param3' => 'дополнительные данные',
];

/**
 * Функция превращает многомерный массив в плоский
 */
function makeFlatParamsArray($arrParams, $parent_name = '')
{
	$arrFlatParams = [];
	$i = 0;
	foreach ($arrParams as $key => $val) {
		$i++;
		/**
		 * Имя делаем вида tag001subtag001
		 * Чтобы можно было потом нормально отсортировать и вложенные узлы не запутались при сортировке
		 */
		$name = $parent_name . $key . sprintf('%03d', $i);
		if (is_array($val)) {
			$arrFlatParams = array_merge($arrFlatParams, makeFlatParamsArray($val, $name));
			continue;
		}
		$arrFlatParams += array($name => (string)$val);
	}

	return $arrFlatParams;
}

// Превращаем объект запроса в плоский массив
$requestForSignature = makeFlatParamsArray($requestForSignature);

// Генерация подписи
ksort($requestForSignature); // Сортировка по ключю
array_unshift($requestForSignature, 'init_payment.php'); // Добавление в начало имени скрипта
array_push($requestForSignature, $secret_key); // Добавление в конец секретного ключа

$request['pg_sig'] = md5(implode(';', $requestForSignature)); // Полученная подпись
URL запроса

POST https://api.freedompay.uz/init_payment.php

Поля запроса
Параметры ответа
Запрос на check_url магазина. Проверка возможности совершить платеж

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Для использования данного запроса Вам следует обратиться к своему менеджеру
Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

Check URL на стороне мерчанта должен быть общедоступным, без авторизации.

FreedomPay передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.
  • В случае если мерчант подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.
  • В случае отказа от платежа rejected.
  • error - ошибка в интерпретации данных.

URL запроса

POST {{check_url}}

Поля запроса
Запрос на result_url магазина. Результат платежа

Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Result URL на стороне мерчанта должен быть общедоступным, без авторизации.
Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.
Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.

Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.
Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных
URL запроса

POST {{result_url}}

Поля запроса
Возврат покупателя на сайт мерчанта

После завершения платежа в online платежной системе покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.
Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. Мерчант должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющихся параметров.
Необходимо четко понимать разницу между Result URL и Success URL.
Result URL вызывается напрямую с сервера FreedomPay, в то время как Success URL вызывается браузером пользователя, когда FreedomPay.uz перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который FreedomPay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

URL запроса
POST {{success_url}}
Поля запроса

Платежный виджет
Чтобы использовать данный вид создания платежа вам следует обратиться к своему менеджеру.

Чекаут (всплывающая форма оплаты) дает возможность создания платежа на странице вашего сайта с помощью токена, который вам может предоставить личный менеджер. Платеж осуществляется через всплывающее окно, которое вызывается при нажатии на кнопку покупателем

Сценарий платежа
  1. Покупатель формирует заказ на вашем сайте
  2. Покупатель нажимает на кнопку покупки товара
  3. Ваш сайт ининциализирует чекаут
  4. FreedomPay вызывает всплывающее окно, где и происходит процесс платежа
  5. В случае успешного платежа или ошибки ваш сайт получает соответствующее уведомление
Подключение чекаута
Для использования чекаута на своем сайте, мерчант должен подключить следующий скрипт:
  <script>
    (function (p, a, y, b, o, x) {
        o = p.createElement(a);
        x = p.getElementsByTagName(a)[0];
        o.async = 1;
        o.src = 'https://cdn.freedompay.uz/widget/pbwidget.js?' + 1 * new Date();
        x.parentNode.insertBefore(o, x);
    })(document, 'script');
  </script>
Далее при нажатии на кнопку оплаты вызвать метод создания платежа. Минимальная конфигурация:
 function pay(amount) {
        var data = {
            token: Ваш токен,
            payment: {
                amount: amount,
                language: 'ru', // Язык виджета
                description: 'Описание заказа',
            },
            successCallback: function (payment) {
                console.log(payment) // Данные о платеже
            },
            errorCallback: function (payment) {
                console.log(payment) // Данные о платеже
            }
        }

        var widget = new PayBox(data);
        widget.create();
    }

<button onclick="pay(100)">Оплатить</button>
Полная конфигурация:
function pay(amount) {
    var data = {
      token: "Ваш токен",
      payment: {
        order: "1",
        amount: "200",
        currency: "KZT",
        description: "Описание заказа",
        expires_at: "2020-12-12 00:00:00",
        param1: "string",
        param2: "string",
        param3: "string",
        test: 1,  // testing mode
        options: {
          callbacks: {
            result_url: "https://my-domain.com/result",
            check_url: "https://my-domain.com/check"
          },
          custom_params: {},
          user: {
            email: "user@test.com",
            phone: "77777777777",
          },
          receipt_positions: [
            {
              count: 2,
              name: "Коврик для мыши",
              tax_type: 3,
              price: 1000
            },
            {
              count: 2,
              name: "Розетка",
              tax_type: 3,
              price: 1000
            }
          ]
        }
      },
      successCallback: function (payment) {
          //...
      },
      errorCallback: function (payment) {
          //...
      }
    }

    var widget = new PayBox(data);
    widget.create();
  }
Получение статуса платежа. После оплаты покупателем, ваш сайт получает уведомление через коллбэки, которые передаются в параметрах:
successCallback: function (payment) {
      // при успешном платеже
      alert('Заказ номер ' + payment.order + ' успешно оплачен')
  },
  errorCallback: function (payment) {
      // при неуспешном платеже
      alert('Произошла ошибка при попытке оплаты заказа номер ' + payment.order)
  }
Запрос на check_url магазина. Проверка возможности совершить платеж

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Для использования данного запроса Вам следует обратиться к своему менеджеру.
Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

FreedomPay передает информацию о номере, свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности платежа пропускается и считается, что магазин согласен принять платеж.
  • В случае если магазин подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.
  • В случае отказа от платежа rejected.
  • error - ошибка в интерпретации данных.
URL запроса

POST {{check_url}}

Поля запроса
Запрос на result_url магазина. Результат платежа

Запрос на result url приходит методом POST, с заголовком Сontent-type: application/json и телом запроса
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.
{
    "id": 12345,
    "status": {
        "code": "success"
    },
    "order": 1234,
    "amount": "100.00",
    "refund_amount": "0.00",
    "currency": "KZT",
    "description": "Описание заказа",
    "payment_system": "WEBKZT",
    "expires_at": "2022-01-18T05:58:58Z",
    "created_at": "2022-01-17T11:58:58Z",
    "updated_at": "2022-01-17T11:59:07Z",
    "param1": null,
    "param2": null,
    "param3": null,
    "options": {
        "callbacks": {
            "result_url": "",
            "check_url": ""
        },
        "user": {
            "email": "widget@freedompay.uz",
            "phone": "77"
        },
        "receipt_positions": null
    },
    "salt": "EitR7ZYZvhpioeCU",
    "sig": "05e72b0137c52c1e941c627f42cb1f39"
}
Мерчант должен ответить на запрос следующим текстом:
{"status": "ok"}
Метод свободного пополнения
В случае, если вы хотите чтобы плательщик самостоятельно вводил сумму платежа, необходимо использовать данный метод.
При прохождении оплаты, плательщик сначала попадает на форму, где он вводит сумму платежа. Далее он перенаправляется на платежную страницу, где происходит оплата.

Инициализация платежа
Инициализация платежа
Запрос
curl --location --request POST 'https://api.freedompay.uz/any_amount.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=mobile_commerce'
# Пример подписи:
'any_amount.php;25;test;{{paybox_merchant_id}};23;KZT;molbulak;{{secret_key}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.freedompay.uz/any_amount?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>
При прямой передаче данных от мерчанта в FreedomPay мерчант должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте freedompay.uz.

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_salt' => 'some random string',
    'pg_order_id'=> '00102',
    'pg_description' => 'Ticket',
    'pg_result_url' => 'http://site.kz/result'
];

// $request['pg_testing_mode'] = 1; //add this parameter to request for testing payments

//if you pass any of your parameters, which you want to get back after the payment, then add them. For example:
// $request['client_name'] = 'My Name';
// $request['client_address'] = 'Earth Planet';

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'any_amount.php');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса
POST https://api.freedompay.uz/any_amount.php
Поля запроса
Параметры ответа
Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Для использования данного запроса Вам следует обратиться к своему менеджеру.
Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

FreedomPay передает информацию о номере, свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.
Check URL на стороне мерчанта должен быть общедоступным, без авторизации.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности платежа пропускается и считается, что магазин согласен принять платеж.
  • В случае если магазин подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.
  • В случае отказа от платежа rejected.
  • error - ошибка в интерпретации данных.
URL запроса

POST {{check_url}}

Поля запроса
Запрос на result_url магазина. Результат платежа
Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.
Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных
URL запроса

POST {{result_url}}

Поля запроса
После завершения платежа в online платежной системе, покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа.

Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.

Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. мерчанта должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.

Необходимо четко понимать разницу между Result URL и Success URL.

Result URL вызывается напрямую с сервера FreedomPay, в то время как Success URL вызывается браузером пользователя, когда FreedomPay перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который FreedomPay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

URL запроса
POST {{success_url}} или {{failure_url}}

Поля запроса
Сохраненной картой с вводом cvc

Для использования данного запроса обратитесь к своему менеджеру

Данный сценарий подразумевает участие пользователя в процессе оплаты. Пользователь перенаправляется в FreedomPay для ввода cvc и прохождения проверки 3ds

В случае, когда карта, по которой проходит платеж является подтвержденной, cvc у пользователя не запрашивается

Подтвержденные карты помечаются статусом approved

Инициализация платежа по карте
Оплата сохраненной картой происходит в два этапа:
  • Инициализация платежа
  • Проведение оплаты
Для инициализации платежа используется следующий запрос:

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 100,
    'pg_order_id' => 12345,
    'pg_user_id' => 1234,
    'pg_card_token' => 'ef741cfc-f85e-41a0-84e6-2ba964912182',
    'pg_description' => 'Описание платежа',
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/v1/merchant/{{paybox_merchant_id}}/card/init

Поля запроса
Параметры ответа
Проведение оплаты

Для проведения оплаты необходимо перенаправить пользователя к FreedomPay POST-запросом

Перенаправление пользователя POST-запросом:
Ответ
<html>
    <body>
        <form action="https://api.freedompay.uz/v1/merchant/{{paybox_merchant_id}}/card/pay" method="post" id="redirect-form">
            <input type="hidden" name="pg_merchant_id" value="{{paybox_merchant_id}}" />
            <input type="hidden" name="pg_payment_id" value="12345" />
            <input type="hidden" name="pg_salt" value="some random string" />
            <input type="hidden" name="pg_sig" value="{{paybox_signature}}" />
        </form>

        <script type="text/javascript">
            document.getElementById('redirect-form').submit();
        </script>
    </body>
</html>
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'pay');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/v1/merchant/{{paybox_merchant_id}}/card/pay

Поля запроса
Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Result URL на стороне мерчанта должен быть общедоступным, без авторизации.
Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась не успешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.

Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных
URL запроса

POST {{result_url}}

Поля запроса
Безакцептное списание
Для использования данного запроса обратитесь к своему менеджеру

Инициализация платежа по карте

Оплата сохраненной картой происходит в два этапа:
  • Инициализация платежа
  • Проведение оплаты
Для инициализации платежа используется следующий запрос:
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 100,
    'pg_order_id' => 12345,
    'pg_user_id' => 1234,
    'pg_card_token' => 'ef741cfc-f85e-41a0-84e6-2ba964912182',
    'pg_description' => 'Описание платежа',
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/v1/merchant/{{paybox_merchant_id}}/card/init

Поля запроса
Параметры ответа
Проведение оплаты
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'direct');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/v1/merchant/{{paybox_merchant_id}}/card/direct

Поля запроса
Параметры ответа
Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным.

Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась не успешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.
Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных
URL запроса
POST {{result_url}}

Поля запроса

Балансом мобильного
FreedomPay предлагает возможность оплачивать заказ/услугу с баланса мобильного телефона, если мобильный оператор плательщика поддерживает данную возможность. Доступные мобильные операторы:

Tele2
Altel
Beeline
Activ
Kcell

Для проведения тестовых оплат рекомендуем ознакомиться с тестовыми номерами телефонов

Инициализация платежа
Инициализация платежа
Запрос
curl --location --request POST 'https://api.freedompay.uz/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=mobile_commerce'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;KZT;molbulak;{{secret_key}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.freedompay.uz/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>
При прямой передаче данных от мерчанта в FreedomPay мерчант должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте freedompay.uz.

Генерация подписи:

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_salt' => 'some random string',
    'pg_order_id'=> '00102',
    'pg_description' => 'Ticket',
    'pg_result_url' => 'http://site.kz/result'
];

// $request['pg_testing_mode'] = 1; //add this parameter to request for testing payments

//if you pass any of your parameters, which you want to get back after the payment, then add them. For example:
// $request['client_name'] = 'My Name';
// $request['client_address'] = 'Earth Planet';

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init_payment.php');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/init_payment.php

Поля запроса
Параметры ответа
Оплата с мобильного

Платёж в большинстве случаев проходит OTP-верификацию. Т.е. для совершения платежа требуется подтверждение. Но по особым договоренностям есть возможность отключить OTP-верификацию.
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_abonent_phone' => 77077777777,
    'pg_payment_system_code' => 'ALTELKZT',
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'pay');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
Если в ответе pg_status равен need_approve FreedomPay отправит SMS сообщение на номер указанный в pg_abonent_phone с OTP кодом. Для продолжения мерчанту необходимо запросить данный код у плательщика.

URL запроса
POST https://api.freedompay.uz/mfs/pay

Поля запроса

Параметры ответа
Подтверждение платежа

Для подтверждение платежа отправляется след запрос:

Генерация подписи:

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};
$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_approval_code' => '077587',
    'pg_salt' => 'some random string',
];
//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'approve');
array_push($request, $secret_key); 
$request['pg_sig'] = md5(implode(';', $request)); // signature
unset($request[0], $request[1]);
URL запроса
POST https://api.freedompay.uz/mfs/approve

Параметры ответа
Запрос на повторную отправку SMS кода

Мерчант может еще раз запрашивать повторную отправку SMS кода.
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_abonent_phone' => 77077777777,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'resend_otp');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.uz/mfs/resend_otp

Поля запроса
Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример положительного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Для использования данного запроса Вам следует обратиться к своему менеджеру
Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

Check URL на стороне мерчанта должен быть общедоступным, без авторизации.
FreedomPay передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализции платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.
  • В случае если мерчант подтверждает готовность заказа и правильность суммы, он должен ответить в виде XML со статусом ok.
  • В случае отказа от платежа rejected.
  • error - ошибка в интерпретации данных.
URL запроса
POST {{check_url}}

Поля запроса

Запрос на result_url магазина. Результат платежа

Пример положительного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
Пример отрицательного ответа магазина
Запрос
curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>
После приема оплаты от клиента или при невозможности совершить платеж FreedomPay вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным.

Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и FreedomPay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, FreedomPay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.
Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.

Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
  • ok - платеж принят
  • rejected - отказ от платежа случае если pg_can_reject равен 1
  • error - ошибка в интерпретации данных
URL запроса
POST {{result_url}}

Поля запроса

Особенности формирования фискальных чеков в Казахстане
В случае формирования чеков в Республике Казахстан, в параметре "tax_type" при передаче значения “3” в фискальном чеке наименование типа налога будет указано как “в т.ч. НДС 12%”.

Рассчитанный размер данного типа налога указывается отдельной строкой в блоке с итоговыми расчетами по всем позициям. Название строки следующее: “в т.ч. НДС 12%”

Особенности формирования фискальных чеков в Узбекистане
В случае формирования чеков в Республике Узбекистан, в параметре "name" необходимо передавать
дополнительные значения в определённой последовательности.
В качестве разделителя используется символ "|" (pipe)
Структура поля "name" приведена ниже:

name|barcode|spic|label|unitcode|package_code|discount|other|tinORpinfl
Поля отмеченные как required должны быть заполнены, остальные поля необходимо передавать с пустым значением

Пример заполнения только обязательных полей:

Зубные Щетки||09603002002000000||27076|1508264|||