Глоссарий

Web-касса — это инструмент для приёма разовых и регулярных платежей пластиковыми картами UZCARD Online через интернет. Web-касса интегрируется в интернет магазины и онлайн-сервисы. Работать с web-кассой могут и юридические лица, и частные предприниматели.

Web-терминал — необходимо интегрировать с интернет магазинами или же онлайн-сервисами в которых не предусмотрена своя система биллинга.

Host-терминал — необходимо интегрировать с сайтами которые представляют собой простые HTML страницы и не имеющие своей back-end части

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

Мерчант (от англ. Merchant - купец, торговец, коммерсант) — поставщик товаров и/или услуг.

Биллинг — система учёта товаров и услуг.

Транзакция (от англ. transaction - сделка, операция) — перечисление денежных средств с банковского счёта покупателя на банковский счёт мерчанта.

Приложение — веб-сайт или мобильное приложение.

Владелец приложения — лицо, в собственности которого находится приложение.

Бизнес-партнёр — участник, ведущий совместную экономическую деятельность с владельцем приложения.

Покупатель — участник, оплачивающий товары и услуги банковской картой в приложении мерчанта.

Endpoint URL — веб-адрес биллинга.

Инвойс — счёт на оплату товаров и/или услуг.

Аккаунт — это «реквизиты» платежа, которые PaySys передаёт в биллинг мерчанта. Реквизитами платежа могут быть: id клиента, код заказа и т.д.

Начало работы

Мы подготовили инструкции по интеграции, чтобы сделать процесс подключения к PaySys, а также прием платежей, быстрым и легким.

Web-касса Удобный способ принимать платежи.	Web-терминал Легкий и быстрый способ начать принимать платежи от пользователей
Host-терминал Легкий и быстрый способ начать принимать платежи от пользователей	Платежный шлюз Инструмент для взаимодействия с PaySys API ( Скоро! )

Интеграция Web-кассы

Обзор проведения платежа

Порядок проведения платежа

№ этапа	Действие	Комментарий
1	Заявка на оплату заказа	Пользователь оформляет заявку на пополнение счета в системе Мерчанта.
2	Запрос на Web-кассу	Система Продавца формирует и отправляет запрос на Web-кассу.
3	Окно выбора платежной системы и ввода реквизитов	Отображается страница выбора Платежной Системы и ввода реквизитов.
4	Выбор платежной системы и ввода реквизитов	Пользователь выбирает Платежную систему и вводит реквизиты на странице Web-кассы.
5	Окно ввода смс кода	Пользователю отображается окно ввода смс кода.
6	Ввод смс кода	Пользователь вводит смс код (смс код, для подтверждения платежа, будет выслан на номер телефона который привязан к карте). Нажимает на кнопку “Подтвердить”.
Проведение оплаты
7	Запрос на возможность совершения оплаты	Web-касса отправляет запрос проверки возможности оплаты в систему Мерчанта.
8	Ответ возможности совершения оплаты	Система Мерчанта отвечает на запрос Web-кассы возможности проведение оплаты.
Платеж совершен
9	Окно результата платежа	Платежный Web-касс сообщает пользователю результат платежа. Пользователю будет предложено вернуться на сайт Мерчанта по ссылке.
10	Возврат на сайт по ссылке	Пользователь переходит на соответствующую страницу сайта Продавца.
11	Оповещение о результате платежа	Система PaySys отправляет оповещение о статусе платежа.

Этап 1. Подготовка к интеграции

Для начала технической интеграции необходимо передать Вашему менеджеру следующую информацию:

• Название Вашей компании
• Название Вашего сайта
• Логотип Вашего сайта ( min 500x500 )

После регистрации Вашего проекта техническая поддержка сообщит Вам следующую информацию для доступа к кабинету:

Параметр	Описание
URL	https://paysys.uz
Логин	Имя (идентификатор) учётной записи пользователя в системе PaySys
Пароль	Условное слово или набор знаков, предназначенный для подтверждения личности или полномочий.

Этап 2. Открытие Web-кассы

Запрос на получение ключа для открытия Web-кассы

Перед началом интеграции Вам необходимо подготовить инструмент для создания запросов на открытие Web-кассы. Для этого, например, можно использовать форму с кнопкой на вашем сайте, которая будет собирать базовые параметры и отправлять пользователя на Web-кассу. При нажатии на кнопку, пользователь должен быть перенаправлен POST или GET http-запросом на URL-адрес.

Для Вашего удобства все тестирование проходит в песочнице (sandbox) нашей системы.

Тестовый режим предназначен для проведения тестовых транзакций и проверки корректности работы системы.
https://paysys.uz/sandbox

Вы можете осуществить открытие Web-кассы в 3 этапа:

• собрать необходимые минимальные данные для осуществления платежа;
• рассчитать подпись (signature);
• перенаправить пользователя на https://paysys.uz/sandbox

Минимальный набор параметров для открытия Web-кассы.

Для открытия Web-кассы Вам достаточно отправлять 7 обязательных параметров: VENDOR_ID, MERCHANT_TRANS_ID, MERCHANT_TRANS_AMOUNT, MERCHANT_CURRENCY, MERCHANT_TRANS_NOTE, SIGN_TIME, SIGN_STRING.

Параметр	Формат	Обязательный	Описание	Пример
VENDOR_ID	integer	да	Идентификатор сайта в системе	1591864
MERCHANT_TRANS_ID	string (256)	да	Уникальный идентификатор заказа в системе Мерчанта.	AB772059
MERCHANT_TRANS_AMOUNT	integer	да	Сумма платежа	1000
MERCHANT_CURRENCY	string (10)	да	Валюта покупки.	sum
MERCHANT_TRANS_NOTE	string (256)	да	Текстовый комментарий к проведенной операции	transaction_note_example
MERCHANT_TRANS_DATA	string (base64)	нет	Детали платежа для Мерчанта. Возвращается Мерчанту	eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9
MERCHANT_TRANS_RETURN_URL	string	нет	Ссылка для возврата, cм. Возврат пользователя с Web-кассы	http://site.com
SIGN_TIME	integer	да	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string (md5)	да	Подпись запроса, cм. Правила формирования подписи запроса	2e483be74e568b4d7d4a7d9421f404fc

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=AB772059
MERCHANT_TRANS_AMOUNT=1000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_DATA=eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9
MERCHANT_TRANS_RETURN_URL=http://site.com
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

Расчёт подписи (параметр SIGN_STRING).

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

Для формирования подписи используется MD5 - 128-битный алгоритм хеширования.

Алгоритм формирования подписи.

Формируется строка на подпись:

От полученной строки берется MD5 хэш.

Правила формирования подписи.

• Кодировка подписываемой строки – UTF-8;

Примеры реализации запроса на языках программирования.

 <?php

// Generator of a terminal request URL as HTML button. PHP example.

const URL = 'https://paysys.uz/sandbox'; // Request target URL
const SECRET_KEY = '#Feiz!ahdahweig7?Choot#3AiL6p--ooF6e'; // Your site SECRET_KEY

// Array of input parameters
$params = array(
    'VENDOR_ID' => '1591864',
    'MERCHANT_TRANS_ID' => 'AB772059',
    'MERCHANT_TRANS_AMOUNT' => '1000',
    'MERCHANT_CURRENCY' => 'sum',
    'MERCHANT_TRANS_NOTE' => 'transaction_note_example',
    'MERCHANT_TRANS_DATA' => 'eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9',
    'SIGN_TIME' => '1480056082732',
 );
$params['SIGN_STRING'] = md5(SECRET_KEY . $params['VENDOR_ID'] . $params['MERCHANT_TRANS_ID'] . $params['MERCHANT_TRANS_AMOUNT'] . $params['MERCHANT_CURRENCY'] . $params['SIGN_TIME']); // Signature adding


// Choose one of two options below

// GET request option. It may not work in IE with more than 2kb transfered data
$url = URL .'?'. http_build_query($params);
echo "<button onclick=\"location.href='{$url}';\">Send</button>";

// POST request option
?>
<form method="post" action="<?=URL;?>">
<?php foreach ($params as $name => $value): ?>
    <input type="hidden" name="<?=$name; ?>" value="<?=$value;?>">
<?php endforeach;?>
    <button type="submit">Send</button>
</form>

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=AB772059
MERCHANT_TRANS_AMOUNT=1000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_DATA=eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9
MERCHANT_TRANS_RETURN_URL=http://site.com
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

В данном примере строка для формирования подписи:

#Feiz!ahdahweig7?Choot#3AiL6p--ooF6e1591864AB7720591000sum1480056082732

В результате MD5 хэширования этой строки - полученная подпись:

2e483be74e568b4d7d4a7d9421f404fc

Этап 3. Merchant API

PaySys передает данные в формате JSON для проведения оплаты Мерчанту услуг по протоколу HTTPS, методом POST.

Мерчанту будет открыт персональный кабинет в системе PaySys, где необходимо указать URLs по описанным ниже запросам, для взаимодействия системы PaySys с биллингом Мерчанта. Для этого перейдите в настройки, введите URL в поле "Pay", "Notify", "Cancel", "Info", "Statement" и сохраните.

3.1. Получения справочной информации по платежу (Info).

Данным запросом PaySys запрашивает справочную информацию от Мерчанта.

Параметры запроса от PaySys:

Параметр	Формат	Описание	Пример
MERCHANT_TRANS_ID	string (256)	ID заказа (для Интернет-магазинов)/лицевого счета/логина в биллинге Мерчанта	SDJ4957
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string (md5)	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . MERCHANT_TRANS_ID . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от Мерчанта:

Параметр	Формат	Описание	Пример
ERROR	int	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success
PARAMETERS	string (json)	Любая справочная информация	{"full_name":"Full Name","email":"email@mail.uz"}

Пример запроса от PaySys:

{
    "MERCHANT_TRANS_ID": "7",
    "SIGN_TIME": 1503638389658,
    "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success",
    "PARAMETERS": {
        "full_name": "Test Test",
        "balance": "1000",
        "email": "test@test.uz"
    }
}

3.2. Получение подтверждения по платежу с последующей оплатой (Pay).

Данным запросом PaySys подтверждает ранее сформированный платеж. В случае успешного ответа, PaySys осуществляет оплату автоматический.

Параметры запроса от PaySys:

Параметр	Формат	Описание	Пример
VENDOR_ID	integer	ID Мерчанта в системе PaySys	158587744
PAYMENT_ID	integer	ID платежной системы в системе PaySys	9
PAYMENT_NAME	string	Название платежной системы в системе PaySys	uzcard
AGR_TRANS_ID	integer	ID платежа в системе PaySys	83749583512
MERCHANT_TRANS_ID	string	ID заказа (для Интернет-магазинов)/лицевого счета/логина в биллинге Мерчанта	SDJ4957
MERCHANT_TRANS_AMOUNT	integer	Сумма оплаты в сумах	2000
ENVIRONMENT	string	"live" или "sandbox"	live
MERCHANT_TRANS_DATA	string	Детали платежа для Мерчанта. Возвращается Мерчанту если параметр передовался в начале: base64_encode($json_data);	eyJwYXJhbV9rZXlftX3ZhbHVlXzIifQ==
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . PAYMENT_NAME . MERCHANT_TRANS_ID . MERCHANT_TRANS_AMOUNT . ENVIRONMENT . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от Мерчанта:

Параметр	Формат	Описание	Пример
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success
VENDOR_TRANS_ID	integer	ID платежа в биллинг системе Мерчанта.	456892353

Пример запроса от PaySys:

{
    "ENVIRONMENT": "sandbox",
    "VENDOR_ID": 902345,
    "PAYMENT_ID": 9,
    "PAYMENT_NAME": "uzcard",
    "AGR_TRANS_ID": 1503639319870,
    "MERCHANT_TRANS_ID": "7",
    "MERCHANT_TRANS_AMOUNT": 1000,
    "MERCHANT_TRANS_DATA": "eyJwYXJhbV9rZXlfMSI6InBhcmFtX3ZhbHVlXzEiLCJwYXJhbV9rZXlfMiI6InBhcmFtX3ZhbHVlXzIifQ==",
    "SIGN_TIME": 1503639320833,
    "SIGN_STRING": "87efeefc53bb259c11e21ab0223ef2df"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success",
    "VENDOR_TRANS_ID": 99987262
}

3.3. Уведомление о статусе платежа (Notify).

Данным запросом система PaySys уведомляет Мерчанта об изменении статуса платежа.

Параметры запроса от PaySys:

Параметр	Формат	Описание	Пример
AGR_TRANS_ID	integer	ID платежа в системе PaySys	1503639319870
VENDOR_TRANS_ID	integer	ID платежа в биллинг системе Мерчанта.	99987262
STATUS	integer	Статус платежа: “2” – оплачено; “3” – отменено;	2
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS_ID . STATUS . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от Мерчанта:

Параметр	Формат	Описание	Пример
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success

Пример запроса от PaySys:

{
    "AGR_TRANS_ID": 1503642925905,
    "VENDOR_TRANS_ID": 1503642925906,
    "STATUS": 2,
    "SIGN_TIME": 1503642926295,
    "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success"
}

3.4. Отмена платежа (Cancel).

Данным запросом система PaySys отменяет платежа.

Параметры запроса от PaySys:

Параметр	Формат	Описание	Пример
AGR_TRANS_ID	integer	ID платежа в системе PaySys	1503639319870
VENDOR_TRANS_ID	integer	ID платежа в биллинг системе Мерчанта.	99987262
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS_ID . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от Мерчанта:

Параметр	Формат	Описание	Пример
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success

Пример запроса от PaySys:

{
    "AGR_TRANS_ID": 1503642925905,
    "VENDOR_TRANS_ID": 1503642925906,
    "SIGN_TIME": 1503642926295,
    "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success"
}

3.5. Отчет о платежах (Statement).

Данным запросом система PaySys ежемесячно осуществляет сверку платежей.

Параметры запроса от PaySys:

Параметр	Формат	Описание	Пример
FROM	integer	Текущее время в миллисекундах	1480056082732
TO	integer	Текущее время в миллисекундах	1480066082732
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . FROM . TO . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от Мерчанта:

Параметр	Формат	Описание	Пример
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success
TRANSACTIONS	string (json)	Массив платежей	[{ "ENVIRONMENT":"live", "AGR_TRANS_ID":"345264652", "VENDOR_TRANS_ID":"67879769", "MERCHANT_TRANS_ID":"7", "MERCHANT_TRANS_AMOUNT":"1000", "STATE":"2", "DATE":"1480056082732" }]

Пример запроса от PaySys:

{
    "FROM": 1503644593249,
    "TO": 1503644893249,
    "SIGN_TIME": 1503644593249,
    "SIGN_STRING": "9ebd383b64eba725ef323e18fcfe9d2f"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success",
    "TRANSACTIONS": [
	{
		"ENVIRONMENT":"live",
		"AGR_TRANS_ID":"345264652",
		"VENDOR_TRANS_ID":"67879769",
		"MERCHANT_TRANS_ID":"7",
		"MERCHANT_TRANS_AMOUNT":"1000",
		"STATE":"2",
		"DATE":"1480056082732"
	},{
		"ENVIRONMENT":"sandbox",
		"AGR_TRANS_ID":"775264652",
		"VENDOR_TRANS_ID":"52879769",
		"MERCHANT_TRANS_ID":"7",
		"MERCHANT_TRANS_AMOUNT":"2000",
		"STATE":"3",
		"DATE":"1480076082732"
	}]
}

3.6. Узнать статус платежа(необязательный) (Status).

Мерчант передает данные в формате JSON для проверки статус оплаты в системе PaySys по протоколу HTTPS, методом POST.

URL: https://paysys.uz/pay_api/payment_status

Параметры запроса от Мерчанта:

Параметр	Формат	Описание	Пример
VENDOR_ID	integer	ID Мерчанта в системе PaySys	1503639319870
AGR_TRANS_ID	integer	ID платежа в биллинг системе PaySys.	99987262
PAYMENT_ID	integer	ID платежной системы в системе PaySys	99987262
SIGN_TIME	integer	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.	2e483be74e568b4d7d4a7d9421f404fc

Параметры ответа от PaySys:

Параметр	Формат	Описание	Пример
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.	0
ERROR_NOTE	string	Описание кода.	Success

Пример запроса от PaySys:

{
    "AGR_TRANS_ID": 1503642925905,
    "VENDOR_ID": 1503642925906,
    "PAYMENT_ID": 1503642925906,
    "SIGN_TIME": 1503642926295,
    "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Пример ответа от Мерчанта:

{
    "ERROR": 0,
    "ERROR_NOTE": "Success"
}

Этап 4. Возврат пользователя с Web-кассы

После проведения платежа Вы можете вернуть Пользователя на страницу сайта. Для этого в запросе на открытие Web-кассы передаются параметры: MERCHANT_TRANS_RETURN_URL

Адрес для возврата пользователя с Web-кассы

Адрес возврата при успешной и при неуспешной оплате: https://return_url

Дополнительные возможности Web-кассы

Web-касса iFrame

iFrame - это режим работы стандартной Web-кассы, который позволяет отобразить окно Web-кассы внутри одного фрейма на Вашем Web сайте.

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=maks
MERCHANT_TRANS_AMOUNT=12000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

Пример вставки iframe кода на странице.

<!DOCTYPE html>
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<iframe src="https://[адрес Терминала]/?VENDOR_ID=..." width="400" height="600" align="center" NORESIZE>Ваш браузер не поддерживает фреймы!</iframe>
</body>
</html>

Интеграция Web-терминала

Обзор проведения платежа

Порядок проведения платежа

№ этапа	Действие	Комментарий
1	Заявка на оплату заказа	Пользователь оформляет заявку на пополнение счета в системе Мерчанта.
2	Запрос на Web-терминал	Система Продавца формирует и отправляет запрос на Web-терминал.
3	Окно выбора платежной системы и ввода реквизитов	Отображается страница выбора Платежной Системы и ввода реквизитов.
4	Выбор платежной системы и ввода реквизитов	Пользователь выбирает Платежную систему и вводит реквизиты на Web-терминальной странице.
5	Окно ввода смс кода	Пользователю отображается окно ввода смс кода.
6	Ввод смс кода	Пользователь вводит смс код (смс код, для подтверждения платежа, будет выслан на номер телефона который привязан к карте). Нажимает на кнопку “Подтвердить”.
Платеж совершен
7	Окно результата платежа	Платежный Web-терминал сообщает пользователю результат платежа. Пользователю будет предложено вернуться на сайт Мерчанта по ссылке.
8	Возврат на сайт по ссылке	Пользователь переходит на соответствующую страницу сайта Продавца.

Этап 1. Подготовка к интеграции

Для начала технической интеграции необходимо передать Вашему менеджеру следующую информацию:

• Название Вашей компании
• Название Вашего сайта
• Логотип Вашего сайта ( 500x500 )

После регистрации Вашего проекта техническая поддержка сообщит Вам следующую информацию для доступа к кабинету:

Параметр	Описание
URL	https://paysys.uz
Логин	Имя (идентификатор) учётной записи пользователя в системе PaySys
Пароль	Условное слово или набор знаков, предназначенный для подтверждения личности или полномочий.

Этап 2. Открытие платежного Web-терминала

Запрос на открытие Web-терминала

Перед началом интеграции Вам необходимо подготовить инструмент для создания запросов на открытие Web-терминала. Для этого, например, можно использовать форму с кнопкой на вашем сайте, которая будет собирать базовые параметры и отправлять пользователя на платежный Web-терминал. При нажатии на кнопку, пользователь должен быть перенаправлен POST или GET http-запросом на URL-адрес.

Для Вашего удобства все тестирование проходит в песочнице (sandbox) нашей системы.

Тестовый режим предназначен для проведения тестовых транзакций и проверки корректности работы системы.
https://paysys.uz/sandbox

Вы можете осуществить открытие Web-терминала в 3 этапа:

• собрать необходимые минимальные данные для осуществления платежа;
• рассчитать подпись (signature);
• перенаправить пользователя на https://paysys.uz/sandbox

Минимальный набор параметров для открытия Web-терминала.

Для открытия Web-терминала Вам достаточно отправлять 7 обязательных параметров: VENDOR_ID, MERCHANT_TRANS_ID, MERCHANT_TRANS_AMOUNT, MERCHANT_CURRENCY, MERCHANT_TRANS_NOTE, SIGN_TIME, SIGN_STRING.

Параметр	Формат	Обязательный	Описание	Пример
VENDOR_ID	integer	да	Идентификатор сайта в системе	1591864
MERCHANT_TRANS_ID	string (256)	да	Уникальный идентификатор заказа в системе Мерчанта.	AB772059
MERCHANT_TRANS_AMOUNT	integer	да	Сумма платежа	1000
MERCHANT_CURRENCY	string (10)	да	Валюта покупки.	sum
MERCHANT_TRANS_NOTE	string	да	Текстовый комментарий к проведенной операции	transaction_note_example
MERCHANT_TRANS_DATA	string (base64)	нет	Детали платежа для Мерчанта. Возвращается Мерчанту	eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9
MERCHANT_TRANS_RETURN_URL	string	нет	Ссылка для возврата, cм. Возврат пользователя с Web-терминала	http://site.com
SIGN_TIME	integer	да	Текущее время в миллисекундах	1480056082732
SIGN_STRING	string (md5)	да	Подпись запроса, cм. Правила формирования подписи запроса	2e483be74e568b4d7d4a7d9421f404fc

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

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=AB772059
MERCHANT_TRANS_AMOUNT=1000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_RETURN_URL=http://site.com
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

Расчёт подписи (параметр SIGN_STRING).

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

Для формирования подписи используется MD5 - 128-битный алгоритм хеширования.

Алгоритм формирования подписи.

Формируется строка на подпись:

От полученной строки берется MD5 хэш.

Правила формирования подписи.

• Кодировка подписываемой строки – UTF-8;

Примеры реализации запроса на языках программирования.

 <?php

// Generator of a terminal request URL as HTML button. PHP example.

const URL = 'https://paysys.uz/sandbox'; // Request target URL
const SECRET_KEY = '#Feiz!ahdahweig7?Choot#3AiL6p--ooF6e'; // Your site SECRET_KEY

// Array of input parameters
$params = array(
    'VENDOR_ID' => '1591864',
    'MERCHANT_TRANS_ID' => 'AB772059',
    'MERCHANT_TRANS_AMOUNT' => '1000',
    'MERCHANT_CURRENCY' => 'sum',
    'MERCHANT_TRANS_NOTE' => 'transaction_note_example',
    'SIGN_TIME' => '1480056082732',
 );
$params['SIGN_STRING'] = md5(SECRET_KEY . $params['VENDOR_ID'] . $params['MERCHANT_TRANS_ID'] . $params['MERCHANT_TRANS_AMOUNT'] . $params['MERCHANT_CURRENCY'] . $params['SIGN_TIME']); // Signature adding


// Choose one of two options below

// GET request option. It may not work in IE with more than 2kb transfered data
$url = URL .'?'. http_build_query($params);
echo "<button onclick=\"location.href='{$url}';\">Send</button>";

// POST request option
?>
<form method="post" action="<?=URL;?>">
<?php foreach ($params as $name => $value): ?>
    <input type="hidden" name="<?=$name; ?>" value="<?=$value;?>">
<?php endforeach;?>
    <button type="submit">Send</button>
</form>

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=AB772059
MERCHANT_TRANS_AMOUNT=1000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_RETURN_URL=http://site.com
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

В данном примере строка для формирования подписи:

#Feiz!ahdahweig7?Choot#3AiL6p--ooF6e1591864AB7720591000sum1480056082732

В результате MD5 хэширования этой строки - полученная подпись:

2e483be74e568b4d7d4a7d9421f404fc

Этап 3. Возврат пользователя с Web-терминала

После проведения платежа Вы можете вернуть Пользователя на страницу сайта. Для этого в запросе на открытие Web-терминала передаются параметры: MERCHANT_TRANS_RETURN_URL

Адрес для возврата пользователя с Web-терминала

Адрес возврата при успешной и при неуспешной оплате: https://return_url

Дополнительные возможности Web-терминала

Web-терминал iFrame

iFrame - это режим работы стандартного Web-терминала, который позволяет отобразить окно Web-терминала внутри одного фрейма на Вашем Web сайте.

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=maks
MERCHANT_TRANS_AMOUNT=12000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

Пример вставки iframe кода на странице.

<!DOCTYPE html>
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<iframe src="https://[адрес Терминала]/?VENDOR_ID=..." width="400" height="600" align="center" NORESIZE>Ваш браузер не поддерживает фреймы!</iframe>
</body>
</html>

Интеграция Host-терминала

Обзор проведения платежа

Порядок проведения платежа

№ этапа	Действие	Комментарий
1	Заявка на оплату заказа	Пользователь оформляет заявку на пополнение счета в системе Мерчанта.
2	Запрос на Host-терминал	Система Продавца формирует и отправляет запрос на Host-терминал.
3	Окно выбора платежной системы и ввода реквизитов	Отображается страница выбора Платежной Системы и ввода реквизитов.
4	Выбор платежной системы и ввода реквизитов	Пользователь выбирает Платежную систему и вводит реквизиты на Host-терминальной странице.
5	Окно ввода смс кода	Пользователю отображается окно ввода смс кода.
6	Ввод смс кода	Пользователь вводит смс код (смс код, для подтверждения платежа, будет выслан на номер телефона который привязан к карте). Нажимает на кнопку “Подтвердить”.
Платеж совершен
7	Окно результата платежа	Платежный Host-терминал сообщает пользователю результат платежа. Пользователю будет предложено вернуться на сайт Мерчанта по ссылке.
8	Возврат на сайт по ссылке	Пользователь переходит на соответствующую страницу сайта Продавца.

Этап 1. Подготовка к интеграции

Для начала технической интеграции необходимо передать Вашему менеджеру следующую информацию:

• Название Вашей компании
• Название Вашего сайта
• Логотип Вашего сайта ( 500x500 )

После регистрации Вашего проекта техническая поддержка сообщит Вам следующую информацию для доступа к кабинету:

Параметр	Описание
URL	https://paysys.uz
Логин	Имя (идентификатор) учётной записи пользователя в системе PaySys
Пароль	Условное слово или набор знаков, предназначенный для подтверждения личности или полномочий.

Этап 2. Открытие платежного Host-терминала

Запрос на открытие Host-терминала

Перед началом интеграции Вам необходимо подготовить инструмент для создания запросов на открытие Host-терминала. Для этого, например, можно использовать форму с кнопкой на вашем сайте, которая будет собирать базовые параметры и отправлять пользователя на платежный Host-терминал. При нажатии на кнопку, пользователь должен быть перенаправлен POST или GET http-запросом на URL-адрес.

Для Вашего удобства все тестирование проходит в песочнице (sandbox) нашей системы.

Тестовый режим предназначен для проведения тестовых транзакций и проверки корректности работы системы.
https://paysys.uz/sandbox

Вы можете осуществить открытие Host-терминала в 3 этапа:

• собрать необходимые минимальные данные для осуществления платежа;
• перенаправить пользователя на https://paysys.uz/sandbox

Минимальный набор параметров для открытия Host-терминала.

Для открытия Host-терминала Вам достаточно отправлять 5 обязательных параметров: VENDOR_ID, MERCHANT_TRANS_ID, MERCHANT_TRANS_AMOUNT, MERCHANT_CURRENCY, MERCHANT_TRANS_NOTE.

Параметр	Формат	Обязательный	Описание	Пример
VENDOR_ID	integer	да	Идентификатор сайта в системе	1591864
MERCHANT_TRANS_ID	string (256)	да	Уникальный идентификатор заказа в системе Мерчанта.	AB772059
MERCHANT_TRANS_AMOUNT	integer	да	Сумма платежа	1000
MERCHANT_CURRENCY	string (10)	да	Валюта покупки.	sum
MERCHANT_TRANS_NOTE	string	да	Текстовый комментарий к проведенной операции	transaction_note_example
MERCHANT_TRANS_DATA	string (base64)	нет	Детали платежа для Мерчанта. Возвращается Мерчанту	eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9
MERCHANT_TRANS_RETURN_URL	string	нет	Ссылка для возврата, cм. Возврат пользователя с Host-терминала	http://site.com

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

Примеры реализации запроса на языках программирования.

 <?php

// Generator of a terminal request URL as HTML button. PHP example.

const URL = 'https://paysys.uz/sandbox'; // Request target URL

// Array of input parameters
$params = array(
    'VENDOR_ID' => '1591864',
    'MERCHANT_TRANS_ID' => 'AB772059',
    'MERCHANT_TRANS_AMOUNT' => '1000',
    'MERCHANT_CURRENCY' => 'sum',
    'MERCHANT_TRANS_NOTE' => 'transaction_note_example',
 );

// Choose one of two options below

// GET request option. It may not work in IE with more than 2kb transfered data
$url = URL .'?'. http_build_query($params);
echo "<button onclick=\"location.href='{$url}';\">Send</button>";

// POST request option
?>
<form method="post" action="<?=URL;?>">
<?php foreach ($params as $name => $value): ?>
    <input type="hidden" name="<?=$name; ?>" value="<?=$value;?>">
<?php endforeach;?>
    <button type="submit">Send</button>
</form>

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=AB772059
MERCHANT_TRANS_AMOUNT=1000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example

Этап 3. Возврат пользователя с Host-терминала

После проведения платежа Вы можете вернуть Пользователя на страницу сайта. Для этого в запросе на открытие Host-терминала передаются параметры: MERCHANT_TRANS_RETURN_URL

Адрес для возврата пользователя с Host-терминала

Адрес возврата при успешной и при неуспешной оплате: https://return_url

Дополнительные возможности Host-терминала

Host-терминал iFrame

iFrame - это режим работы стандартного Host-терминала, который позволяет отобразить окно Host-терминала внутри одного фрейма на Вашем Web сайте.

Пример запроса

VENDOR_ID=1591864
MERCHANT_TRANS_ID=maks
MERCHANT_TRANS_AMOUNT=12000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example

Пример вставки iframe кода на странице.

<!DOCTYPE html>
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<iframe src="https://[адрес Терминала]/?VENDOR_ID=..." width="400" height="600" align="center" NORESIZE>Ваш браузер не поддерживает фреймы!</iframe>
</body>
</html>

Интеграция Платежного Шлюза

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

Прием платежей по банковским картам

Платежный шлюз PaySys позволяет осуществлять оплату с банковских карт пользователей.

Этап 1. Подготовка к интеграции

Для начала технической интеграции необходимо передать Вашему менеджеру следующую информацию:

• Название Вашей компании
• Название Вашего сайта
• Логотип Вашего сайта ( min 500x500 )

После регистрации Вашего проекта техническая поддержка сообщит Вам следующую информацию для доступа к кабинету:

Параметр	Описание
URL	https://paysys.uz
Логин	Имя (идентификатор) учётной записи пользователя в системе PaySys
Пароль	Условное слово или набор знаков, предназначенный для подтверждения личности или полномочий.

Этап 2. Отправка запроса на Платежный шлюз

На сайте Мерчанта Пользователь выбирает оплату по банковской карте и заполняет данные карты. Система Мерчанта собирает эти данные, формирует и отправляет HTTP POST запрос на Платежный шлюз. Запрос передается в JSON формате.

2.1. Получения информации о Мерчанта.

URL: https://paysys.uz/payment_gateway_api/get_vendor

Параметры запроса от Мерчанта:

Параметр	Формат	Описание
VENDOR_ID	integer	ID Мерчанта в системе PaySys
SIGN_TIME	integer	Текущее время в миллисекундах
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . VENDOR_ID . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.

Параметры ответа от PaySys:

Параметр	Формат	Описание
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.
ERROR_NOTE	string	Описание кода.
VENDOR	Object	Информации о Мерчанта.

Пример запроса от Мерчанта:

{
    "VENDOR_ID": 346272,
    "SIGN_TIME": 1503638389658,
    "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Пример ответа от PaySys:

{
    "ERROR":"0",
    "ERROR_NOTE":"success",
    "VENDOR":{
        "id":"346272",
        "name":"SiteName",
        "url":"https://site.uz/",
        "logo":"https://paysys.uz/img/site.png",
        "description":"",
        "status":"1", //1 - Активный, 0 - Заблокированный
        "transaction_note":"Оплата услуг на сайте Site.uz"
    }
}

2.2. Оформления платежа.

URL: https://paysys.uz/payment_gateway_api/preparation_payment

Параметры запроса от Мерчанта:

Параметр	Формат	Обязательный	Описание
VENDOR_ID	integer	да	Идентификатор сайта в системе
MERCHANT_TRANS_ID	string (256)	да	Уникальный идентификатор заказа в системе Мерчанта.
MERCHANT_TRANS_AMOUNT	integer	да	Сумма платежа
MERCHANT_CARD_NUMBER	string (16)	да	Номер карты плательщика.
MERCHANT_CARD_EXPIRE	string (4)	да	Дата окончания действия карты.
MERCHANT_CURRENCY	string (10)	да	Валюта покупки.
MERCHANT_TRANS_NOTE	string (256)	да	Текстовый комментарий к проведенной операции
MERCHANT_TRANS_DATA	string (base64)	нет	Детали платежа для Мерчанта. Возвращается Мерчанту
SIGN_TIME	integer	да	Текущее время в миллисекундах
SIGN_STRING	string (md5)	да	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . VENDOR_ID . MERCHANT_TRANS_ID . MERCHANT_TRANS_AMOUNT . MERCHANT_CARD_NUMBER . MERCHANT_CARD_EXPIRE . MERCHANT_CURRENCY . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.

Параметры ответа от PaySys:

Параметр	Формат	Описание
AGR_TRANS_ID	integer	ID платежа в системе PaySys
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.
ERROR_NOTE	string	Описание кода.

Пример запроса от Мерчанта:

{
    "VENDOR_ID": 346272,
    "MERCHANT_TRANS_ID": "AB4573",
    "MERCHANT_TRANS_AMOUNT": 5000,
    "MERCHANT_CARD_NUMBER": "8600000000000000",
    "MERCHANT_CARD_EXPIRE": "0220",
    "MERCHANT_CURRENCY": "sum",
    "MERCHANT_TRANS_NOTE": "Оплата за .....",
    "SIGN_TIME": 1503638389658,
    "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Пример ответа от PaySys:

{
    "AGR_TRANS_ID":15894357,
    "ERROR":"0",
    "ERROR_NOTE":"success",
}

2.3. Подтверждение платежа.

URL: https://paysys.uz/payment_gateway_api/confirm_payment

Параметры запроса от Мерчанта:

Параметр	Формат	Описание
AGR_TRANS_ID	integer	ID Мерчанта в системе PaySys
VERIFICATION_CODE	string	смс код присланный для подтверждения платежа(время жизни кода 180 секунд).
SIGN_TIME	integer	Текущее время в миллисекундах
SIGN_STRING	string	Проверочная строка, подтверждающая подлинность отправляемого запроса. ХЭШ MD5 из следующих параметров: md5( SECRET_KEY . AGR_TRANS_ID . VERIFICATION_CODE . SIGN_TIME ) SECRET_KEY – уникальная строка, выдаваемая Мерчанту при подключении.

Параметры ответа от PaySys:

Параметр	Формат	Описание
ERROR	integer	Код статуса. 0 – успешно. В случае ошибки возвращается код ошибки.
ERROR_NOTE	string	Описание кода.

Пример запроса от Мерчанта:

{
    "AGR_TRANS_ID": 346272,
    "VERIFICATION_CODE": 456231,
    "SIGN_TIME": 1503638389658,
    "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Пример ответа от PaySys:

{
    "ERROR":"0",
    "ERROR_NOTE":"success"
}

Песочница

Этап 1. Проведение тестового платежа по банковским картам через (Web-кассы / Web-терминал)

Успешная оплата по карте без 3DS

Отправляем тестовый запрос на (Web-кассы / Web-терминал).

https://paysys.uz/sandbox

VENDOR_ID=1591864
MERCHANT_TRANS_ID=maks
MERCHANT_TRANS_AMOUNT=12000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_RETURN_URL=http://filecloud.uz
SIGN_TIME=1480056082732
SIGN_STRING=2e483be74e568b4d7d4a7d9421f404fc

Отправляем тестовый запрос на Host-терминал.

https://paysys.uz/sandbox

VENDOR_ID=1591864
MERCHANT_TRANS_ID=maks
MERCHANT_TRANS_AMOUNT=12000
MERCHANT_CURRENCY=sum
MERCHANT_TRANS_NOTE=transaction_note_example
MERCHANT_TRANS_RETURN_URL=http://filecloud.uz

Отображается окно выбора платежного средства и ввода реквизитов карты.

Вводим номер тестовой карты и нажимаем кнопку “Продолжить”.

Номер карты              4444 4444 4444 4444
Срок действия карты      44/44

Отображается окно ввода смс кода.

Вводим тестовый смс код и нажимаем кнопку “Продтвердить”.

СМС код     444444

Откроется окно статуса платежа.

Этап 2. Перевод в боевой режим

Для перевода Web-кассы, Web-терминала или Host-терминала в боевой режим необходимо:

1. Получить подтверждение технической поддержки об успешном прохождении тестовых платежей;
2. Изменить адрес запросов на https://paysys.uz/pay
3. Провести пробные платежи на боевом Web-кассе, Web-терминале или Host-терминале;
4. Получить подтверждение технической поддержки об успешном прохождении боевых платежей.

Ошибки

Если Вы не смогли устранить ошибку самостоятельно, Вам необходимо обратиться в службу технической поддержки PaySys по адресу: support@paysys.uz.

Коды ошибок возвращаемые системой PaySys

error	error_note	Описание
0	Success	Успешный запрос
< 0	Описание ошибки	Ошибка

Коды ошибок возвращаемые системой Мерчанта

error	error_note	Описание
0	Success	Успешный запрос
-1	SIGN CHECK FAILED!	Ошибка проверки подписи
-2	Incorrect parameter amount	Неверная сумма оплаты
-3	Action not found	Запрашиваемое действие не найдено
-4	Already paid	Транзакция ранее была подтверждена (при попытке подтвердить или отменить ранее подтвержденную транзакцию)
-5	User does not exist	Не найден пользователь/заказ (проверка параметра merchant_trans_id)
-6	Transaction does not exist	Не найдена транзакция (проверка параметра merchant_prepare_id)
-7	Failed to update user	Ошибка при изменении данных пользователя (изменение баланса счета и т.п.)
-8	Error in request from PaySys	Ошибка в запросе от PaySys (переданы не все параметры и т.п.)
-9	Transaction cancelled	Транзакция ранее была отменена (При попытке подтвердить или отменить ранее отмененную транзакцию)
-10	The vendor is not found	Поставщик не найден в системе