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

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

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

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

Инициализация платежа
Запрос:
curl --location --request POST 'https://api.freedompay.kz/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{signature}}'
# Пример подписи:
'init_payment.php;25;test;{{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.kz/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',
        // Параметр user_id должен быть уникальным для каждого пользователя! 
        // В случае повторяющихся значений, пользователи с одинаковым user_id смогут увидеть карты друг друга. 
        // Это может привести к утечке данных и нарушению конфиденциальности! 
        // Данная настройка осуществляется на стороне мерчанта!
	'pg_recurring_start' => '1',
	'pg_recurring_lifetime' => '156',
	'pg_receipt_positions' => [
		[
			// В случае формирования чеков в Республике Узбекистан, в параметре "name" необходимо передавать
			// дополнительные значения в определённой последовательности.
			// Детальную информацию можно найти в разделе "Особенности формирования фискальных чеков"
			'name' => 'название товара',
			'count' => '1',
			'tax_type' => '3',
			'price' => '900',
		]
	],
	'pg_user_id' => '1',
        // Параметр user_id должен быть уникальным для каждого пользователя! 
        // В случае повторяющихся значений, пользователи с одинаковым user_id смогут увидеть карты друг друга. 
        // Это может привести к утечке данных и нарушению конфиденциальности! 
        // Данная настройка осуществляется на стороне мерчанта!
	'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.kz.

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

НазваниеОписаниеТип
pg_order_id

required

Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Максимальная длина 50 символов
Пример: 00102
string
pg_merchant_id

required

Идентификатор мерчанта в FreedomPay Выдается при подключении. integer
pg_amount

required

Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description

required

Описание товара или услуги. Отображается покупателю в процессе платежа.

Пример: Ticket

string
pg_salt

required

Случайная строка.
Пример: some random string
string
pg_sig

required

Подпись запросаstring
pg_currencyВалюта, в которой указана сумма.
KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string Справочник валют
pg_check_urlURL для проверки возможности платежа.
Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек магазина. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится.
string
pg_result_urlURL для сообщения о результате платежа.
Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек магазина. Является обязательным, если не задан в настройках магазина. Если параметр установлен равным пустой строке, то FreedomPay не сообщает магазину о результате платежа.
string
pg_request_methodGET, POST или XML – метод вызова скриптов магазина Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_success_urlurl, на который отправляется пользователь в случае успешного платежа (только для online систем).
Является обязательным, если не задан в настройках магазина.
string
pg_failure_urlurl, на который отправляется пользователь в случае неуспешного платежа (только для online систем).
Является обязательным, если не задан в настройках магазина.
string
pg_success_url_methodGET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Пример: GET
string
pg_failure_url_methodGET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Пример: GET
string
pg_state_urlURL скрипта на сайте магазина, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_methodGET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST. AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1. AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт магазина. Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается магазину.
Пример: GET
string
pg_site_urlURL сайта магазина для показа покупателю ссылки, по которой он может вернуться на сайт магазина после создания счета.
Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_payment_systemИдентификатор платежной системы.
Этот параметр передается только если выбор платежной системы совершается на сайте мерчанта. Если параметр не указан, то выбор ПС совершается на сайте freedompay.kz.
Пример: EPAYWEBKZT
string
pg_lifetimeDefault: "86400". Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа FreedomPay откажет платежной системе в проведении.
Этот параметр контролируется FreedomPay, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя.
Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_emailКонтактный адрес электронной почты пользователя.
Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ipIP-адрес клиента.
Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_paymentСоздание платежа с отложенной оплатой если в этом параметре передано «1».
В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.
Пример: 0
integer
pg_languageЯзык платежных страниц на сайте FreedomPay и (если возможно) платежных систем. "en", "ru".
Пример: ru
string
pg_testing_modeСоздание платежа в тестовом режиме.
Пример: 1
integer
pg_user_idID пользователя в системе мерчанта.
Пример: No65GFR755789T, 25642588
string
pg_recurring_startФлаг, принимает значение 0 или 1.
Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetimeВремя на продолжении которого мерчант рассчитывает использовать профиль рекуррентных платежей.
Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_receipt_positions[0][count]Количество товара.
Пример: 2
integer
pg_receipt_positions[0][name]Наименование товара.
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type]Тип налога.

Возможные значения:

0 - Без налога,

1 - НДС 0%,

2 - НДС 12%,

3 - НДС 12/112,

4 - НДС 18%,

5 - НДС 18/118,

6 - НДС 10%,

7 - НДС 10/110,

8 - НДС 20%,

9 - НДС 20/120

integer
pg_receipt_positions[0][price]Цена за 1 ед. товара.

Пример: 1000

number
pg_param1Дополнительный параметр 1.

Пример: Дополнительная информация

string
pg_param2Дополнительный параметр 2.

Пример: Дополнительная информация

string
pg_param3Дополнительный параметр 3.

Пример: Дополнительная информация

string
pg_auto_clearingЕсли 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг.
Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.

Пример: 1

integer
pg_payment_methodЗначение - Метод платежа. wallet - Электронные деньги. internetbank, Интернет-банкинг, other - Терминалы, bankcard - Банковские карты, cash - Точки приема платежей, mobile_commerce - Мобильная коммерция.

Пример: mobile_commerce

string
pg_timeout_after_paymentОпределяет время закрытия страницы с платежом в секундах.

Пример: 10

integer
pg_generate_qrВ случае, если вы хотите получать QR код со ссылкой на платежную форму FreedomPay в формате base64, в параметре pg_generate_qr необходимо отправить «1»boolean
pg_3ds_challengeОпределяет необходимость прохождения Challenge Flow (1 - обязательно провести Challenge Requested, 0 или пусто - метод определяется эмитентом) банк-эмитент может игнорировать данный параметр и провести платеж по своему Challenge Flowinteger
pg_commission_discountВ случае, если вы хотите использовать скидку на комиссию, то необходимо отправить 1. Скидка работает только на комиссию сверху. Для использования метода обратитесь к персональному менеджеруboolean
pg_commission_discount_fixДля использования фиксированной суммы скидкиnumber
pg_commission_discount_percentageДля использования процентной скидкиnumber
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов.

Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операций
string
pg_loyalty_idИдентификатор в системе лояльностиstring
pg_loyalty_amountСумма начисляемых единиц в системе лояльностиnumber
pg_freedom_idИдентификатор пользователя в экосистеме Freedomstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса: Статус: ok, Описание: Запрос прошел успешно,Статус: error, Описание: Запрос прошел с ошибкойstring
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay cлужит ключом для всей дальнейшей работы с транзакциейinteger
pg_redirect_urlURL для перенаправления пользователя. Может быть как на сайте freedompay.kz, так и на сайте платежной системыstring
pg_redirect_url_typeТип страницы, на которую происходит перенаправление. Возможные значения: need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров, payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте freedompay.kz, так и на сайте мерчанта. В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакцияstring
pg_redirect_qrURL для перенаправления пользователя в виде QR. Передается в формате base64string
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Запрос на 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}}

Поля запроса

НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.

Пример: 10

number
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_ps_amountСумма счета (в валюте pg_ps_currency), выставленного в платежной системе.

Пример: 5

number
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.

Пример: 5

number
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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}}

Поля запроса

НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета в валюте pg_currency.

Пример: 500

string
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_net_amountСумма счета (в валюте pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа.

Пример: 482.5

string
pg_ps_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример:500

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа. Пример: Покупка в интернет магазине Site.kzstring
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой. Пример: 1integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_idОпциональный параметр. ID карты для оплаты сохраненной картой (Deprecated).

Пример: 1234

string
pg_card_tokenОпциональный параметр.Токен карты для оплаты сохраненной картой.

Пример: ef741cfc-f85e-41a0-84e6-2ba964912182

string
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: 5483-18XX-XXXX-0293

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_discount_percentИнформация о проценте скидки, отправляется если скидка присутствует.

Пример: 1.0

string
pg_discount_amountИнформация о сумме скидки, отправляется если скидка присутствует.

Пример: 5

string
pg_payment_methodМетод платежа

Значение:Метод платежа:
wallet — Электронные деньги,
internetbank — Интернет-банкинг
other — Терминалы
bankcard — Банковские карты
cash — Точка приема платежей
mobile_commerce — Мобильная коммерция

Пример: bankcard

string
pg_card_expДата истечения срока карты.

Пример: 03/23

string
pg_card_ownerИмя держателя карты.

Пример: Ivan Ivanov

string
pg_card_brandКод бренда карты.

Пример: VI

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

После завершения платежа в 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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов
Пример: 123456789
string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay. Пример: 12345integer
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка. Пример: some random stringstring
pg_sigПодпись запросаstring
pg_error_codeКод ошибки. В случае ошибки параметр будет отправляться на pg_failure_url.Пример: 1000string
pg_error_descriptionОписание ошибки. В случае ошибки параметр будет отправляться на pg_failure_url. Пример: Внутреняя ошибка сервисаstring
Платежный фрейм

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


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

Запрос
curl --location --request POST 'https://api.freedompay.kz/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.kz/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',
        // Параметр user_id должен быть уникальным для каждого пользователя! 
        // В случае повторяющихся значений, пользователи с одинаковым user_id смогут увидеть карты друг друга. 
        // Это может привести к утечке данных и нарушению конфиденциальности! 
        // Данная настройка осуществляется на стороне мерчанта!
	'pg_recurring_start' => '1',
	'pg_recurring_lifetime' => '156',
	'pg_receipt_positions' => [
		[
			'count' => '1',
			'name' => 'название товара',
			'tax_type' => '3',
			'price' => '900',
		]
	],
	'pg_user_id' => '1',
        // Параметр user_id должен быть уникальным для каждого пользователя! 
        // В случае повторяющихся значений, пользователи с одинаковым user_id смогут увидеть карты друг друга. 
        // Это может привести к утечке данных и нарушению конфиденциальности! 
        // Данная настройка осуществляется на стороне мерчанта!
	'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.kz/init_payment.php

Поля запроса
НазваниеОписаниеТип
pg_order_id

required

Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Максимальная длина 50 символов

Пример: 00102

string
pg_merchant_id

required

Идентификатор мерчанта в FreedomPay. Выдается при подключении. integer
pg_amount

required

Сумма платежа в валюте pg_currency.

Пример: 10

number
pg_description

required

Описание товара или услуги. Отображается покупателю в процессе платежа.

Пример:Ticket

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
pg_payment_route

required

Для инициализации frame.

Пример: frame

string
pg_currencyВалюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют.

Пример: KZT

string Справочник валют
pg_check_urlURL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится.string
pg_result_urlURL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек магазина. Является обязательным, если не задан в настройках магазина. Если параметр установлен равным пустой строке, то FreedomPay не сообщает магазину о результате платежа.string
pg_request_methodGET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.

Пример: POST

string
pg_failure_urlurl, на который отправляется пользователь в случае неуспешного платежа (только для online систем). Является обязательным, если не задан в настройках магазина.string
pg_failure_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz.

Пример: GET

string
pg_state_urlURL скрипта на сайте мерчанта, куда перенаправляется покупатель для ожидания ответа от платежной системы.

Пример: http://site.kz/state

string
pg_state_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1. AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта. Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается мерчанту.

Пример: GET

string
pg_site_urlURL сайта магазина для показа покупателю ссылки, по которой он может вернуться на сайт магазина после создания счета. Применяется для offline ПС (наличные).

Пример: http://site.kz/return

string
pg_lifetimeDefault: "86400" Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа FreedomPay откажет платежной системе в проведении. Этот параметр контролируется FreedomPay’ом, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.

Пример: 86400

integer
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.

Пример: 77777777777

string
pg_user_contact_emailКонтактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.

Пример:mail@customer.kz

string
pg_user_ipIP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.

Пример: 127.0.0.1

string
pg_postpone_paymentСоздание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.

Пример: 0

integer
pg_languageЯзык платежных страниц на сайте FreedomPayа и (если возможно) платежных систем. "en", "ru".

Пример: ru

string
pg_testing_modeСоздание платежа в тестовом режиме.Пример: 1integer
pg_user_id

required

ID пользователя в системе мерчанта.

Пример: No65GFR755789T, 25642588

string
pg_recurring_startФлаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекурентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.

Пример: 1

integer
pg_recurring_lifetimeВремя на продолжении которого магазин рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться своему менеджеру.

Пример: 156

integer
pg_param1Дополнительный параметр 1.

Пример: Дополнительная информация

string
pg_param2Дополнительный параметр 2.

Пример: Дополнительная информация

string
pg_param3Дополнительный параметр 3.

Пример: Дополнительная информация

string
pg_auto_clearingЕсли 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.

Пример: 1

integer
pg_generate_qrВ случае, если вы хотите получать QR код со ссылкой на платежную форму FreedomPay в формате base64, в параметре pg_generate_qr необходимо отправить «1»boolean
pg_commission_discountВ случае, если вы хотите использовать скидку на комиссию, то необходимо отправить 1. Скидка работает только на комиссию сверху. Для использования метода обратитесь к персональному менеджеруboolean
pg_commission_discount_fixДля использования фиксированной суммы скидкиnumber
pg_commission_discount_percentageДля использования процентной скидкиnumber
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов.

Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операций
string
pg_loyalty_idИдентификатор в системе лояльностиstring
pg_loyalty_amountСумма начисляемых единиц в системе лояльностиnumber
pg_freedom_idИдентификатор пользователя в экосистеме Freedomstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса:
Статус: Описание:
ok — Запрос прошел успешно,
error — Запрос прошел с ошибкой
string
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_redirect_urlURL для перенаправления пользователя. Может быть как на сайте freedompay.kz, так и на сайте платежной системыstring
pg_redirect_url_typeТип страницы, на которую происходит перенаправление. Возможные значения: need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров, payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте freedompay.kz, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_redirect_qrURL для перенаправления пользователя в виде QR. Передается в формате base64 string
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Запрос на 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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.

Пример: 10

number
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_ps_amountСумма счета (в валюте pg_ps_currency), выставленного в платежной системе.

Пример: 5

number
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.

Пример: 5

number
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции.

Пример: 500

string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_net_amountСумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа.

Пример: 482.5

string
pg_ps_amountСумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа. Пример: Покупка в интернет магазине Site.kzstring
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_dateДата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой.

Пример: 1

integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает,был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_idОпциональный параметр. ID карты для оплаты сохраненной картой (Deprecated).

Пример: 1234

string
pg_card_tokenОпциональный параметр. Токен карты для оплаты сохраненной картой.

Пример: ef741cfc-f85e-41a0-84e6-2ba964912182

string
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: 5483-18XX-XXXX-0293

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_payment_methodМетод платежа

Значение:Метод платежа:
wallet — Электронные деньги,
internetbank — Интернет-банкинг
other — Терминалы
bankcard — Банковские карты
cash — Точка приема платежей
mobile_commerce — Мобильная коммерция

Пример: bankcard

string
pg_card_expДата истечения срока карты.

Пример: 03/23

string
pg_card_ownerИмя держателя карты.

Пример: Ivan Ivanov

string
pg_card_brandКод бренда карты.

Пример: VI

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

После завершения платежа в 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.kz перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который FreedomPay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

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

НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_error_codeКод ошибки. В случае ошибки параметр будет отправляться на pg_failure_url.

Пример: 1000

string
pg_error_descriptionОписание ошибки. В случае ошибки параметр будет отправляться на pg_failure_url.

Пример: Внутреняя ошибка сервиса

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

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

Сценарий платежа
  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.kz/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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.

Пример: 10

number
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_ps_amountСумма счета (в валюте pg_ps_currency), выставленного в платежной системе.

Пример: 5

number
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.

Пример: 5

number
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
Запрос на 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.kz",
            "phone": "77"
        },
        "receipt_positions": null
    },
    "salt": "EitR7ZYZvhpioeCU",
    "sig": "05e72b0137c52c1e941c627f42cb1f39"
}
Мерчант должен ответить на запрос следующим текстом:
{"status": "ok"}
Метод свободного пополнения
В случае, если вы хотите чтобы плательщик самостоятельно вводил сумму платежа, необходимо использовать данный метод.
При прохождении оплаты, плательщик сначала попадает на форму, где он вводит сумму платежа. Далее он перенаправляется на платежную страницу, где происходит оплата.

Инициализация платежа
Инициализация платежа
Запрос
curl --location --request POST 'https://api.freedompay.kz/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.kz/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.kz.

Генерация подписи:
$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.kz/any_amount.php
Поля запроса
НазваниеОписаниеТип
pg_order_id

required

Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля. Если мерчант не передал это поле, то оно становится обязательным для заполнения плательщиком.
Максимальная длина 50 символов

Пример: 00102

string
pg_merchant_id

required

Идентификатор мерчанта в FreedomPay. Выдается при подключении. integer
pg_description

required

Описание товара или услуги. Отображается покупателю в процессе платежа.

Пример: Ticket

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
pg_currencyВалюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют.

Пример: KZT

string Справочник валют
pg_check_urlURL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится.string
pg_result_urlURL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то FreedomPay не сообщает мерчанту о результате платежа.string
pg_request_methodGET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта. Пример: POSTstring
pg_success_urlurl, на который отправляется пользователь в случае успешного платежа (только для online систем)string
pg_failure_urlurl, на который отправляется пользователь в случае неуспешного платежа (только для online систем)string
pg_success_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.

Пример: GET

string
pg_failure_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.

Пример: GET

string
pg_site_urlURL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).

Пример: http://site.kz/return

string
pg_lifetimeDefault: "86400". Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа FreedomPay откажет платежной системе в проведении. Этот параметр контролируется FreedomPay, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.

Пример: 86400

integer
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта. Если мерчант не передал это поле, то оно становится обязательным для заполнения плательщиком.

Пример: 77777777777

string
pg_user_contact_emailКонтактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции. Если мерчант не передал это поле, то оно становится обязательным для заполнения плательщиком.

Пример: mail@customer.kz

string
pg_user_ipIP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.

Пример: 127.0.0.1

string
pg_languageЯзык платежных страниц на сайте FreedomPay и (если возможно) платежных систем. "en", "ru".

Пример: ru

string
pg_testing_modeСоздание платежа в тестовом режиме.

Пример: 1

integer
pg_user_idID пользователя в системе мерчанта.

Пример: No65GFR755789T, 25642588

string
pg_param1Дополнительный параметр 1.

Пример: Дополнительная информация

string
pg_param2Дополнительный параметр 2.

Пример: Дополнительная информация

string
pg_param3Дополнительный параметр 3.

Пример: Дополнительная информация

string
pg_payment_methodЗначение - Метод платежа mobile_commerce - Мобильная коммерция.

Пример: mobile_commerce

string
pg_amount_interval_fromНижний порог суммы платежа. Если параметр не передан, то нижнего порога нетinteger
pg_amount_interval_toВысший порог суммы платежа. Если параметр не передан, то высшего порога нетinteger
pg_generate_qrВ случае, если вы хотите получать QR код со ссылкой на платежную форму FreedomPay в формате base64, в параметре pg_generate_qr необходимо отправить «1»boolean
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов.

Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операций
string
pg_loyalty_idИдентификатор в системе лояльностиstring
pg_loyalty_amountСумма начисляемых единиц в системе лояльностиnumber
pg_freedom_idИдентификатор пользователя в экосистеме Freedomstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса. Статус:ok Описание: Запрос прошел успешно, Статус: error, Описание: Запрос прошел с ошибкойstring
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_redirect_urlURL для перенаправления пользователя. Может быть как на сайте freedompay.kz, так и на сайте платежной системыstring
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения: need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров, payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте freedompay.kz, так и на сайте мерчанта. В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакцияstring
pg_redirect_qrURL для перенаправления пользователя в виде QR. Передается в формате base64 string
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Запрос на 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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.

Пример: 10

number
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_ps_amountСумма счета (в валюте pg_ps_currency), выставленного в платежной системе.

Пример: 5

number
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.

Пример: 5

number
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета в валюте pg_currency.

Пример: 500

string
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_net_amountСумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа

Пример: 482.5

string
pg_ps_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа.

Пример: Покупка в интернет магазине Site.kz

string
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_dateДата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой.

Пример: 1

integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_idОпциональный параметр. ID карты для оплаты сохраненной картой (Deprecated).

Пример: 1234

string
pg_card_tokenОпциональный параметр. Токен карты для оплаты сохраненной картой.

Пример: ef741cfc-f85e-41a0-84e6-2ba964912182

string
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: 5483-18XX-XXXX-0293

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_discount_percentИнформация о проценте скидки, отправляется если скидка присутствует.

Пример: 1.0

string
pg_discount_amountИнформация о сумме скидки, отправляется если скидка присутствует.

Пример: 5

string
pg_payment_methodМетод платежа

Значение:Метод платежа:
wallet — Электронные деньги,
internetbank — Интернет-банкинг
other — Терминалы
bankcard — Банковские карты
cash — Точка приема платежей
mobile_commerce — Мобильная коммерция

Пример: bankcard

string
pg_card_expДата истечения срока карты.

Пример: 03/23

string
pg_card_ownerИмя держателя карты.

Пример: Ivan Ivanov

string
pg_card_brandКод бренда карты.

Пример: VI

string
После завершения платежа в 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}}

Поля запроса
НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_error_codeКод ошибки. В случае ошибки параметр будет отправляться на pg_failure_url.

Пример: 1000

string
pg_error_descriptionОписание ошибки. В случае ошибки параметр будет отправляться на pg_failure_url.

Пример: Внутреняя ошибка сервиса

string
Сохраненной картой с вводом 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.kz/v1/merchant/{{paybox_merchant_id}}/card/init

Поля запроса
НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_amount

required

Сумма платежа.

Пример: 100

number
pg_order_id

required

ID заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 12345

string
pg_user_id

required

ID пользователя в системе мерчанта.

Пример: No65GFR755789T, 25642588

string
pg_card_id

required if no pg_card_token

ID карты. (Deprecated).

Пример: 56

integer
pg_card_token

required if no pg_card_id

Токен карты.

Пример: ef741cfc-f85e-41a0-84e6 2ba964912182

integer
pg_description

required

Описание заказа.

Пример: Описание платежа

string
pg_salt

required

Случайная строка, состоящая из произвольных цифр и латинских букв.

Пример: some random

string
pg_sig

required

Подпись запросаstring
pg_receipt_positions[0][count]Количество товара.

Пример: 2

integer
pg_receipt_positions[0][name]Наименование товара.

Пример: Коврик для мыши

string
pg_receipt_positions[0][tax_type]Тип налога.

Возможные значения:

0 - Без налога,

1 - НДС 0%,

2 - НДС 12%,

3 - НДС 12/112,

4 - НДС 18%,

5 - НДС 18/118,

6 - НДС 10%,

7 - НДС 10/110,

8 - НДС 20%,

9 - НДС 20/120

integer
pg_receipt_positions[0][price]Цена за 1 ед. товара.

Пример: 1000

number
pg_user_emailEmail покупателя.

Пример:mail@customer.kz

string string
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя.

Пример: 77777777777

string
pg_user_ipIP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.

Пример: 127.0.0.1

string
pg_result_urlURL для сообщения о результате платежа. Обязательно, если не установлено в настройках магазина.string
pg_success_urlURL, на который отправляется пользователь в случае успешной оплаты. Обязательно, если не установлено в настройках магазина.string
pg_failure_urlURL, на который отправляется пользователь в случае не успешного платежа. Обязательно, если не установлено в настройках магазина.string
pg_param1Дополнительная информацияstring
pg_param2Дополнительная информацияstring
pg_param3Дополнительная информацияstring
pg_loyalty_idИдентификатор в системе лояльностиstring
pg_loyalty_amountСумма начисляемых единиц в системе лояльностиnumber
pg_freedom_idИдентификатор пользователя в экосистеме Freedomstring
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов. Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операцийstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса: Статус: ok, Описание:Запрос прошел успешно, Статус:error, Описание:Запрос прошел с ошибкойstring
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_merchant_idИдентификатор мерчанта в системе FreedomPayinteger
pg_order_idИдентификатор заказа в системе мерчанта
Максимальная длина 50 символов
integer
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Проведение оплаты

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

Перенаправление пользователя POST-запросом:
Ответ
<html>
    <body>
        <form action="https://api.freedompay.kz/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.kz/v1/merchant/{{paybox_merchant_id}}/card/pay

Поля запроса
НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_payment_id

required

Внутренний идентификатор платежа в системе FreedomPay.

Пример: 123456

integer
pg_salt

required

Случайная строка, состоящая из произвольных цифр и латинских букв.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции.

Пример: 500

string
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_net_amountСумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа.

Пример: 482.5

string
pg_ps_amountСумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа. Пример: Покупка в интернет магазине Site.kzstring
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_dateДата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой.

Пример: 1

integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: ef741cfc-f85e-41a0-84e6-2ba964912182

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_discount_percent Информация о проценте скидки, отправляется если скидка присутствует.

Пример: 1.0

string
pg_discount_amountИнформация о сумме скидки, отправляется если скидка присутствует.

Пример: 5

string
pg_payment_methodМетод платежаЗначение: — Метод платежа: wallet — Электронные деньги,internetbank — Интернет-банкингother — Терминалыbankcard — Банковские картыcash — Точка приема платежейmobile_commerce — Мобильная коммерция

Пример: bankcard

string
pg_card_expДата истечения срока карты.

Пример: 03/23

string
pg_card_ownerИмя держателя карты.

Пример: Ivan Ivanov

string
pg_card_brandКод бренда карты.

Пример: VI

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

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

Оплата сохраненной картой происходит в два этапа:
  • Инициализация платежа
  • Проведение оплаты
Для инициализации платежа используется следующий запрос:
Генерация подписи:
$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.kz/v1/merchant/{{paybox_merchant_id}}/card/init

Поля запроса
НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_amount

required

Сумма платежа.Минимум 0.01

Пример: 100

number
pg_currencyВалюта платежа

Пример: KZT

string
pg_order_id

required

ID заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 12345

string
pg_user_id

required

ID пользователя в системе мерчанта.

Пример: No65GFR755789T, 25642588

string
pg_card_id

required if no pg_card_token

ID карты. (Deprecated).

Пример: 56

integer
pg_card_token

required if no pg_card_id

Токен карты.

Пример: ef741cfc-f85e-41a0-84e6-2ba964912182

integer
pg_description

required

Описание заказа. Пример: Описание платежаstring
pg_salt

required

Случайная строка, состоящая из произвольных цифр и латинских букв.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
pg_receipt_positions[0][count]Количество товара.

Пример: 2

integer
pg_receipt_positions[0][name]Наименование товара.

Пример: Коврик для мыши

string
pg_receipt_positions[0][tax_type]Тип налога.

Возможные значения:

0 - Без налога,

1 - НДС 0%,

2 - НДС 12%,

3 - НДС 12/112,

4 - НДС 18%,

5 - НДС 18/118,

6 - НДС 10%,

7 - НДС 10/110,

8 - НДС 20%,

9 - НДС 20/120

integer
pg_receipt_positions[0][price] Цена за 1 ед. товара.

Пример: 1000

number
pg_user_emailEmail покупателя.

Пример: mail@customer.kz

string
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя.

Пример: 77777777777

string
pg_user_ipIP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.

Пример: 127.0.0.1

string
pg_result_urlURL для сообщения о результате платежа. Обязательно, если не установлено в настройках магазина.string
pg_success_urlURL, на который отправляется пользователь в случае успешной оплаты. Обязательно, если не установлено в настройках магазина.string
pg_failure_urlURL, на который отправляется пользователь в случае не успешного платежа. Обязательно, если не установлено в настройках магазина.string
pg_param1Дополнительная информацияstring
pg_param2Дополнительная информацияstring
pg_param3Дополнительная информацияstring
pg_loyalty_idИдентификатор в системе лояльностиstring
pg_loyalty_amountСумма начисляемых единиц в системе лояльностиnumber
pg_freedom_idИдентификатор пользователя в экосистеме Freedomstring
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов. Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операцийstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса: Статус: ok, Описание:Запрос прошел успешно, Статус: error, Описание: Запрос прошел с ошибкойstring
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_merchant_idИдентификатор мерчанта в системе FreedomPayinteger
pg_order_idИдентификатор заказа в системе мерчанта
Максимальная длина 50 символов
integer
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Проведение оплаты
Генерация подписи:
$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.kz/v1/merchant/{{paybox_merchant_id}}/card/direct

Поля запроса
НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_payment_id

required

Внутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_salt

required

Случайная строка, состоящая из произвольных цифр и латинских букв.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса:
Статус: — Описание:
ok — Запрос прошел успешно
error — Запрос прошел с ошибкой
string
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_transaction_statusСтатус платежа:
Статус: — Описание:
partial — Новый платеж
**pending — Ожидание плательщика или платежной системы,
ok — Платеж успешно завершен,
failed — Платеж в ошибке,
incomplete — Истекло время жизни платежа
string
pg_payment_methodМетод платежа.

Пример: bankcard

string
pg_create_dateДата и время создания платежной транзакцииdatetime
pg_can_reject0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php.integer
pg_capturedEnum:0 1. Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг или дождаться когда FreedomPay сделает это сам.integer
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.string
pg_card_idID карты (Deprecated)integer
pg_card_tokenТокен картыstring
pg_card_hashХеш маскированной PAN картыstring
pg_amountСумма заказаnumber
pg_currencyВалюта заказаstring
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
** При получении статуса "pending", нужно произвести запрос на получение статуса по методу "get_status3"
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции.

Пример: 500

string
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_net_amountСумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа.

Пример: 482.5

string
pg_ps_amountСумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.

Пример: 500

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа. Пример: Покупка в интернет магазине Site.kzstring
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_dateДата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой. Пример: 1integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: 5483-18XX-XXXX-0293

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_payment_methodМетод платежа

Значение:Метод платежа:
wallet — Электронные деньги,
internetbank — Интернет-банкинг
other — Терминалы
bankcard — Банковские карты
cash — Точка приема платежей
mobile_commerce — Мобильная коммерция

Пример: bankcard

string
pg_card_expДата истечения срока карты.

Пример: 03/23

string
pg_card_ownerИмя держателя карты.

Пример: Ivan Ivanov

string
pg_card_brandКод бренда карты.

Пример: VI

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

Tele2
Altel
Beeline
Activ
Kcell

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

Инициализация платежа
Инициализация платежа
Запрос
curl --location --request POST 'https://api.freedompay.kz/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.kz/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.kz.

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

Генерация подписи:
$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.kz/init_payment.php

Поля запроса
НазваниеОписаниеТип
pg_order_id

required

Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Максимальная длина 50 символов

Пример: 00102

string
pg_merchant_id

required

Идентификатор мерчанта в FreedomPay. Выдается при подключении. integer
pg_amount

required

Сумма платежа в валюте pg_currency. Минимум 0.01

Пример: 10

number
pg_description

required

Описание товара или услуги. Отображается покупателю в процессе платежа.

Пример: Ticket

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
pg_currencyВалюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют.

Пример: KZT

string Справочник валют
pg_check_urlURL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится.string
pg_result_urlURL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то FreedomPay не сообщает мерчанту о результате платежа.string
pg_request_methodGET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.

Пример: POST

string
pg_success_urlurl, на который отправляется пользователь в случае успешного платежа (только для online систем)string
pg_failure_urlurl, на который отправляется пользователь в случае неуспешного платежа (только для online систем)string
pg_success_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта. Пример: GETstring
pg_failure_url_methodGET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте freedompay.kz, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.

Пример: GET

string
pg_site_urlURL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).

Пример: http://site.kz/return

string
pg_lifetimeDefault: "86400". Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа FreedomPay откажет платежной системе в проведении. Этот параметр контролируется FreedomPay, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.

Пример: 86400

integer
pg_user_phoneТелефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.

Пример: 77777777777

string
pg_user_contact_emailКонтактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.

Пример: mail@customer.kz

string
pg_user_ipIP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа. Пример: 127.0.0.1string
pg_languageЯзык платежных страниц на сайте FreedomPay и (если возможно) платежных систем. "en", "ru", "kk", "de", "ky", "uz".

Пример: ru

string
pg_testing_modeСоздание платежа в тестовом режиме. Пример: 1integer
pg_user_idID пользователя в системе мерчанта.

Пример: No65GFR755789T, 25642588

string
pg_param1Дополнительный параметр 1.

Пример: Дополнительная информация

string
pg_param2 Дополнительный параметр 2.

Пример: Дополнительная информация

string
pg_param3Дополнительный параметр 3.

Пример: Дополнительная информация

string
pg_payment_methodЗначение - Метод платежа mobile_commerce - Мобильная коммерция. Пример: mobile_commercestring
pg_generate_qrВ случае, если вы хотите получать QR код со ссылкой на платежную форму FreedomPay в формате base64, в параметре pg_generate_qr необходимо отправить «1»boolean
pg_commission_discountВ случае, если вы хотите использовать скидку на комиссию, то необходимо отправить 1. Скидка работает только на комиссию сверху. Для использования метода обратитесь к персональному менеджеруboolean
pg_commission_discount_fix Для использования фиксированной суммы скидкиnumber
pg_commission_discount_percentageДля использования процентной скидкиnumber
pg_idempotency_keyКлюч идемпотентности. Используется для защиты от создания дубликатов запросов.

Уникальное значение в рамках мерчанта, нельзя использовать одинаковый ключ для разных типов операций
string
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса: Статус:—Описание:
ok — Запрос прошел успешно,
error — Запрос прошел с ошибкой
string
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
pg_redirect_urlURL для перенаправления пользователя. Может быть как на сайте freedompay.kz, так и на сайте платежной системыstring
pg_redirect_url_typeТип страницы, на которую происходит перенаправление. Возможные значения: need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров, payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте freedompay.kz, так и на сайте мерчанта. В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакцияstring
pg_redirect_qrURL для перенаправления пользователя в виде QR. Передается в формате base64string
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
Оплата с мобильного

Платёж в большинстве случаев проходит 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.kz/mfs/pay

Поля запроса

НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_payment_id

required

Внутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_abonent_phone

required

Телефон покупателя с баланса которого снимутся деньги.

Пример: 77077777777

string
pg_payment_system_codeУникальный код мобильного оператора.
Enum:"TELE2KZT" "ALTELKZT" "BEELINEKZT" "KCELLKZT" "ACTIVKZT".

Пример: ALTELKZT

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса:
Статус:—Описание:
ok — Списание прошло успешно,
need_approve — Необходимо подтверждение,
error — Ошибка списания
string
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
Подтверждение платежа

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

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

Генерация подписи:
$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.kz/mfs/approve

НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор мерчанта в системе FreedomPaystring
pg_payment_id

required

Внутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_approval_code

required

Одноразовый OTP код отправленный SMS сообщением на номер плательщика.

Пример:077587

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
Параметры ответа
НазваниеОписаниеТип
pg_statusПоказывает результат выполнения запроса:
Статус:—Описание:
ok — Списание прошло успешно,
process — Необходимо подтверждение,
error — Ошибка списания
string
pg_payment_idУникальный идентификатор платежной транзакции в FreedomPay. Служит ключом для всей дальнейшей работы с транзакциейinteger
Запрос на повторную отправку 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.kz/mfs/resend_otp

Поля запроса
НазваниеОписаниеТип
pg_merchant_id

required

Идентификатор магазина в системе FreedomPay.integer
pg_payment_id

required

Идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_abonent_phone

required

Телефон покупателя с баланса которого снимутся деньги.

Пример: 77077777777

string
pg_salt

required

Случайная строка.

Пример: some random string

string
pg_sig

required

Подпись запросаstring
Запрос на 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}}

Поля запроса

НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_amountСумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.

Пример: 10

number
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_ps_amountСумма счета (в валюте pg_ps_currency), выставленного в платежной системе.

Пример: 5

number
pg_ps_full_amountПолная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.

Пример: 5

number
Параметры мерчантаВсе поля, переданные с веб-сайта мерчант, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
Запрос на 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_reference=111111111111' \
--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_reference=111111111111' \
--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}}

Поля запроса

НазваниеОписаниеТип
pg_order_idИдентификатор заказа в системе мерчанта.
Максимальная длина 50 символов

Пример: 123456789

string
pg_payment_idВнутренний идентификатор платежа в системе FreedomPay.

Пример: 12345

integer
pg_currencyВалюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.

Пример: KZT

string
pg_ps_currencyВалюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа.

Пример: KZT

string
pg_descriptionОписание платежа.

Пример: Покупка в интернет магазине Site.kz

string
pg_resultРезультат платежа. 2 – Не завершен. 1 – успех, 0 – неудача.

Пример: 1

integer
pg_payment_datelДата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.

Пример: 2019-01-01 12:00:00

datetime
pg_can_reject1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.

Пример: 1

integer
pg_user_phoneТелефон покупателя (указанный при инициализации платежа).

Пример: 7077777777777

string
pg_user_contact_emailEmail покупателя (указанный при инициализации платежа).

Пример: mail@customer.kz

string
pg_testing_modeТестовый режим. 1 - тестовый, 0 - боевой.

Пример: 1

integer
pg_capturedПередается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда FreedomPay сделает это сам.

Пример: 0

integer
pg_card_panМаскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.

Пример: 5483-18XX-XXXX-0293

string
Параметры мерчантаВсе поля, переданные с веб-сайта мерчант, не имеющие префикса pg_ string
pg_saltСлучайная строка.

Пример: some random string

string
pg_sigПодпись запросаstring
pg_payment_methodМетод платежа

Значение:Метод платежа:
wallet — Электронные деньги,
internetbank — Интернет-банкинг
other — Терминалы
bankcard — Банковские карты
cash — Точка приема платежей
mobile_commerce — Мобильная коммерция

Пример: bankcard

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


Название поля (тут указано название массива)
1 уровень
Название поля (относится к массиву)
2 уровень
Название поля
3 уровень
Что значит
pg_receipt-—
receipt_formatФормат чека
для кз всегда kz_1_0
customer
phoneномер покупателя, обязателен если нет email
emailномер покупателя, обязателен если нет номера
positions
priceСтоимость товара
nameНаименование товара
quantityКоличество товара
vat_codeТип налога. vat_12 vat_10 vat_0, число это процент 12% 10% 0%
Пример запроса:
"pg_order_id": "24012401",
    "pg_merchant_id": "777777",
    "pg_amount": "2000",
    "pg_description": "ofd",
    "pg_salt": "some random string",
    "pg_sig": "6a9c25b26b9754f16b2baa7b2975cfb6",
    "pg_result_url": "https://webhook.site/77777",
    "pg_testing_mode": "0",
    "pg_user_id": "1234",
    "pg_receipt": {
        "receipt_format": "kz_1_0",
        "customer": {
            "phone": "87077777777"
        },
        "positions": [
            {
                "price": "1000",
                "name": "Товар №1",
                "quantity": "1",
                "vat_code": "vat_12"
            },
            {
                "price": "500",
                "name": "Товар №2",
                "quantity": "1",
                "vat_code": "vat_12"
            },
            {
                "price": "500",
                "name": "Товар №3",
                "quantity": "1",
                "vat_code": "vat_12"
            }
        ]
    }
}
Особенности формирования фискальных чеков в Узбекистане
В случае формирования чеков в Республике Узбекистан, в параметре "name" необходимо передавать
дополнительные значения в определённой последовательности.
В качестве разделителя используется символ "|" (pipe)
Структура поля "name" приведена ниже:

name|barcode|spic|label|unitcode|package_code|discount|other|tinORpinfl
Название поля Описание
name

required

название товара
barcodeштрихкод
spic

required

код ИКПУ
labelкод маркировки товара
unitcode

required

код единицы измерения товара
package_code

required

код упаковки товара
discountскидка
otherпрочая скидка
tin or pinflидентификационный номер юридического или физического лица
Поля отмеченные как required должны быть заполнены, остальные поля необходимо передавать с пустым значением

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

Зубные Щетки||09603002002000000||27076|1508264|||
Тестовые карты

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

В тестовом режиме можно использовать только тестовые платежные методы, а в рабочем режиме, наоборот, оплата тестовыми платежными методами невозможна.

После перехода мерчанта в рабочий режим можно создавать отдельные транзакции в тестовом режиме, передавая параметр pg_testing_mode в запросах на создание платежа и на получение списка платежных методов. Значение pg_testing_mode=1 включает тестовый режим для одной конкретной транзакции. Для проведения тестовых транзакций в боевом режиме необходимо обратится менеджеру для уточнения деталей.

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

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

В качестве имени карте нужно указывать от 2 слов в английской раскладке.

Пароль для 3-D Secure проверки: 12345678
Список тестовых карт:
Карты на успех
МПСНомер картыCVVСрок действияРезультат по карте
VISA44004444000044401232030/12Успех
VISA47160472619419811232030/12Успех
VISA41111111111111111232030/12Успех
MasterCard55555555555555991232030/12Успех
VISA49397709561549891232030/12Успех
Карты на успех с имитацией прохождения 3ds
МПСНомер картыCVVСрок действияРезультат по карте
VISA44004444000044441232030/12Успех
VISA49163074163343101232030/12Успех
MasterCard53676542761021261232030/12Успех
Карты на ошибку:
МПСНомер картыCVVСрок действияКод ответаРезультат по карте
VISA44004444000044411232030/1299999Неизвестная ошибка платежной системы
MasterCard53352159453677031232030/1299999Неизвестная ошибка платежной системы
VISA44444444444466661232030/1299999Неизвестная ошибка платежной системы
VISA44004444000044421232030/12100066Превышен лимит на карте списания. Обратитесь в банк выпустивший карту
VISA49161098308322461232030/12100066Превышен лимит на карте списания. Обратитесь в банк выпустивший карту
VISA45639601220019991232030/12100066Превышен лимит на карте списания. Обратитесь в банк выпустивший карту
VISA44004444000044431232030/1210009Недостаточно средств. Просим пополнить счет или произвести оплату с другой карты.
MasterCard55483986817001481232030/1210009Недостаточно средств. Просим пополнить счет или произвести оплату с другой карты.
VISA44004444000044451232030/1211008Срок действия кода подтверждения истек. Повторите операцию
MasterCard54751029358536131232030/1211036Карта операции списания заблокирована на 30 дней. Воспользуйтесь другой картой.
MasterCard55555555555555571232030/1211024 Отказано по причине нарушения безопасности данных карты списания. Обратитесь в банк выпустивший карту
VISA44444444444444221232030/1210001Ошибка списания с карты на стороне банка-эмитента. Повторите попытку позже
VISA44444444111111111232030/1210022Сумма превышает допустимый лимит по карте списания. Обратитесь в банк выпустивший карту
VISA44444444999999991232030/1210018 Время жизни операции списания истекло. Повторите операцию
VISA44004444000044461232030/129014Ошибка возврата
Тестовые карты для Выплат:
Номер картыКод ошибкиОтвет
4671593866478252Успешная выплата
532534947290131110000Ошибка оплаты. Сервис недоступен. Повторите попытку позже.
455604608504174010001Ошибка оплаты. Обратитесь в банк выпустивший карту
55439747028760458888Недостаточно средств! Пополните выплатной баланс
5507841999732294Process переходящий в успех
4532676596620704Process переходящий в ошибку - Ошибка оплаты. Обратитесь в банк выпустивший карту