Автовыплаты

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

С помощью протокола автовыплат можно выполнять следующие операции:

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

Общий для всех операций порядок обмена данными

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

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

Команды на выполнение операций необходимо посылать на URL: https://dkcp.deltakey.net/ms/autopay.py

Методом POST или GET необходимо включить в запрос следующие параметры:

	num_shop - номер магазина. Присваивается системой автоматически при регистрации магазина в кабинете. Состоит из нескольких цифр.
	pass - MD5-хэш секретного ключа магазина. Задается при регистрации магазина, может содержать любые символы.
	ext_transact - Уникальный номер запроса, до 19 цифр. Генерируется скриптом магазина при каждой отправке запроса.
	password - MD5-хэш пароля пользователя, сконкатенированного с уникальным номером операции `ext_transact`. Например, если `ext_transact=2012011912458500001`, а пароль пользователя (указывается при регистрации пользователя) `myDeltaPass$`, то поле `password` будет содержать значение `6333c977b3b7ae6d2516f5f551cfb59b`, что является хешем от строки `myDeltaPass$2012011912458500001` .
	program - Константа, всегда должно быть равно `10033` .
	cmd - Выполняемая операция. См. описание конкретной операции.

В качестве ответов возвращается XML вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>...<transact>

	<ext_transact>...</ext_transact>
	<date>...</date>
	<status>...</status>
	<status_text>...</status_text>

	<result>...<result>
	<result_text>...</result_text>
	<advanced>
		[<param1>...</param1>

		...
		<paramN>...</paramN>] 
	</advanced>
	<table [name="table1"] row="..." col="...">
		[<colnames>
			<colname1>ruscolname1</colname1>

			...
			<colnameN>ruscolnameN</colnameN>
		</colnames>
		<colvalues>
			<colname1>colvalue1</colname1>

			...
			<colnameN>colvalueN</colnameN>
		</colvalues>
		...
		<colvalues>
			<colname1>colvalue1</colname1>

			...
			<colnameN>colvalueN</colnameN>
		</colvalues>]
	</table>
	...
	<table [name="tableN"] row="..." col="...">
		[<colnames>

			<colname1>ruscolname1</colname1>
			...
			<colnameN>ruscolnameN</colnameN>
		</colnames>
		<colvalues>

			<colname1>colvalue1</colname1>
			...
			<colnameN>colvalueN</colnameN>
		</colvalues>
		...
		<colvalues>

			<colname1>colvalue1</colname1>
			...
			<colnameN>colvalueN</colnameN>
		</colvalues>]
	</table>
</response>

Если поле result = 0, то операция успешно выполнена. В противном случае это поле будет содержать код ошибки, а поле result_text - текст ошибки.

Описание элементов:

	`transact` - номер транзакции сервера, созданная в результате команды, или обращение к которой выполнялось в процессе выполнения команды. Представлена длинным целым числом. Может быть равной 0 в случае, если команда не обращается к какой-либо транзакции и не создает ее (получение переменных сервера), либо задействует более одной транзакции (получение статистики операций);
	`ext_transact` - номер внешней транзакции;
	`data` - дата завершения выполнения команды сервером. Представлена в виде YYYYMMDDhhmmss (например, дата 20061127174403 может быть расшифрована как 27 ноября 2006 г. 17:44:03);
	`status` - статус выполнения команды. Представлен целым числом: 1 - в обработке, 2 - завершена. Необходимость введения данного элемента обусловлена тем фактом, что многие команды завершаются сразу (смена регистрационных данных, получение статистики), либо выполняют предварительную разноску по базе данных (к примеру, проведение платежа: посылаются данные поставщику, однако операция будет считаться окончательно завершенной в случае подтверждения поставщиком факта оплаты);
	`result` - результат выполнения команды. Представлен числом: 0 - успешное выполнение команды, любое другое число - код ошибки (см. приложение II);
	`result_text` - текстовая расшифровка результата;
	ветка `advanced` - дополнительные сведения, возвращаемые командой (к примеру, рассчитанные комиссии, статистика и прочее). Может быть пустой или содержать неограниченное количество строк
	табличная часть - в результирующей XML может содержаться одна или несколько таблиц; каждая таблица имеет следующую структуру:
	`param1, paramN` - дополнительные строковые параметры, возвращаемые командой;
	ветка `colnames` - в случае возвращения таблицы данных - полные заголовки столбцов (краткие заголовки с использованием только символов латинского алфавита могут быть получены из имен элементов). Количество элементов в ветке равно количеству столбцов;
	ветки `colvalues` - в случае возвращения таблицы данных - значения строк по столбцам. Количество этих веток равно количеству строк. Количество элементов в каждой ветке равно количеству столбцов.

Получение баланса своих счетов

Параметр cmd должен посылаться со значением getlist_keyt .

Обязательные дополнительные параметры: не требуются.

Необязательные дополнительные параметры:

keyt - Номер счета. Позволяет получить информацию только по одному счету. Возможные значения: -1 (все счета) или 15 цифр. Если данный параметр не передан, он будет считаться равным -1.

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

https://dkcp.deltakey.net/ms/autopay.py?num_shop=123&pass=6333c977b3b7ae6d2516f5f551cfb59b& ext_transact=2012011912458500001&password=96e79218965eb72c92a549dd5a330112& program=10033&cmd=getlist_keyt

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>0</transact>
	<ext_transact>1</ext_transact>
	<date>20120119193732</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>

	<result>0</result>
	<result_text>Список счетов</result_text>
	
	<table row="6" col="21" name="">
		<colnames>

			<keyt>Счет</keyt>
			<name>Название</name>
			<summ>Сумма на балансе</summ>
			<tariff>Тариф</tariff>
			<tariff_to>Тариф оплачен до</tariff_to>
			<curr_code>Валюта</curr_code>

			<curr>Валюта</curr>
			<curr_name>Название валюты</curr_name>
			<stat_code>Тип счета</stat_code>
			<stat>Тип счета</stat>
			<in_status_code>Ввод средств</in_status_code>
			<in_status>Ввод средств</in_status>

			<out_status_code>Вывод средств</out_status_code>
			<out_status>Вывод средств</out_status>
			<tariff_code>Код тарифа</tariff_code>
			<over>Овердрафт</over>
			<block>Заблокировано</block>
			<balance>Mожно израсходовать (Итоговый баланс)</balance>

			<ps>Признак системности</ps>
			<shop_itogo>Название валюты</shop_itogo>
			<hide>Виден другим пользователям</hide>
		</colnames>
		<colvalues>
			<keyt>810000000010202</keyt>
			<name></name>

			<summ>45.00</summ>
			<tariff>Базовый</tariff>
			<tariff_to>None</tariff_to>
			<curr_code>810</curr_code>
			<curr>RUR</curr>
			<curr_name>Российский рубль</curr_name>

			<stat_code>1</stat_code>
			<stat>Операционный</stat>
			<in_status_code>1</in_status_code>
			<in_status>Разрешен</in_status>
			<out_status_code>1</out_status_code>
			<out_status>Разрешен</out_status>

			<tariff_code>501</tariff_code>
			<over>0.00</over>
			<block>0.00</block>
			<balance>45.00</balance>
			<ps>1</ps>
			<shop_itogo>None</shop_itogo>

			<hide>0</hide>
		</colvalues>
		<colvalues>
			<keyt>840000000010381</keyt>
			<name>Мой долларовый счет</name>
			<summ>0.00</summ>
			<tariff>Базовый</tariff>

			<tariff_to>None</tariff_to>
			<curr_code>810</curr_code>
			<curr>RUR</curr>
			<curr_name>Российский рубль</curr_name>
			<stat_code>1</stat_code>
			<stat>Операционный</stat>

			<in_status_code>1</in_status_code>
			<in_status>Разрешен</in_status>
			<out_status_code>1</out_status_code>
			<out_status>Разрешен</out_status>
			<tariff_code>501</tariff_code>
			<over>0.00</over>

			<block>0.00</block>
			<balance>0.00</balance>
			<ps>0</ps>
			<shop_itogo>None</shop_itogo>
			<hide>0</hide>
		</colvalues>

	</table>
</response>

Получение статистики операций

Параметр cmd должен посылаться со значением getlist_finoperation .

Обязательные дополнительные параметры: не требуются.

Необязательные дополнительные параметры:

	date_start - Дата начала отбора операций. В ответе сервера будут содержаться только операции, выполненные не ранее указанной даты. Дату необходимо отправлять в формате YYYY-MM-DD или -1 для выборки всех операций с даты регистрации. Если данный параметр не передан, он будет считаться равным -1.
	date_end - Дата окончания отбора операций. В ответе сервера будут содержаться только операции, выполненные не позднее указанной даты. Дату необходимо отправлять в формате YYYY-MM-DD или -1 для выборки всех операций по текущий момент. Если данный параметр не передан, он будет считаться равным -1.
	typelocal - Включить в статистику только операции поступления средств на счет или расхода со счета. Возможные значения: -1 (все операции), 1 (приход), 2 (расход). Если данный параметр не передан, он будет считаться равным -1.
	transact_num - Поиск информации по конкретной транзакции. Возможные значения: -1 (все транзакции), или список транзакций через запятую. Если данный параметр не передан, он будет считаться равным -1.
	sum - Поиск операций по сумме. Возможные значения: -1 или знак сравнения и дробное число, точность два знака. Разделитель - точка. Знаки сравнения: = или >= или <= или > или < или != или <> или выражение 'between X and Y'. Если данный параметр не передан, он будет считаться равным -1.

<response>
	<transact>0</transact>
	<ext_transact>1</ext_transact>
	<date>20120120055733</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>
	<result>0</result>

	<result_text>Финансовая статистика</result_text>
	<advanced>
	</advanced>
	
	<table row="65" col="21" name="">
		<colnames>
			<transact>Транзакция</transact>
			<date>Дата</date>

			<typelocal>Пр./расх.</typelocal>
			<code_text>Операция</code_text>
			<sum>Сумма</sum>
			<fee>Комиссия</fee>
			<curr>Валюта</curr>
			<result>Результат</result>

			<done>Операция завершена</done>
			<comment>Комментарий</comment>
			<pay_sum_start>на начало операции</pay_sum_start>
			<pay_sum_end>на конец операции</pay_sum_end>
			<shop_sum_start>на начало операции</shop_sum_start>
			<shop_sum_end>на конец операции</shop_sum_end>

			<shop_name>Корреспондент</shop_name>
			<user_name>Отправитель</user_name>
			<shop_phone>Номер телефона</shop_phone>
			<user_phone>Номер телефона</user_phone>
			<shop_id>ID корреспондента</shop_id>
			<param>Дополнительные параметры</param>

			<param_value>Значение</param_value>
		</colnames>
		<colvalues>
			<transact>104292337</transact>
			<date>07.12.2011 21:01:23</date>
			<typelocal>Расход</typelocal>
			<code_text>Платеж оператору МегаФон Москва</code_text>

			<sum>1.00</sum>
			<fee>0.00</fee>
			<curr>RUR</curr>
			<result>OK</result>
			<done>1</done>
			<comment>БОНУС ПО АКЦИИ ПОДАРКИ ОТ КОТА БОРИСА</comment>

			<pay_sum_start>46.00</pay_sum_start>
			<pay_sum_end>45.00</pay_sum_end>
			<shop_sum_start/>
			<shop_sum_end/>
			<shop_name>ООО 'Дельта Кей'</shop_name>
			<user_name>СУПЕРПУПЕРМАГАЗИН</user_name>
			<shop_phone>None</shop_phone>

			<user_phone>+79261234567</user_phone>
			<shop_id>204000000000001</shop_id>
			<param>Номер телефона</param>
			<param_value>9261234567</param_value>
		</colvalues>
		
		<colvalues>
			<transact>104287645</transact>
			<date>07.12.2011 15:44:56</date>
			<typelocal>Приход</typelocal>
			<code_text>Перевод другому пользователю</code_text>
			<sum>300.00</sum>

			<fee>0.00</fee>
			<curr>RUR</curr>
			<result>Операция успешно завершена</result>
			<done>1</done>
			<comment>1% от Андрея</comment>
			<pay_sum_start/>

			<pay_sum_end/>
			<shop_sum_start>84.00</shop_sum_start>
			<shop_sum_end>384.00</shop_sum_end>
			<shop_name>СУПЕРПУПЕРМАГАЗИН</shop_name>
			<user_name>Иванов Иван Иванович.</user_name>
			<shop_phone>+79261234567</shop_phone>

			<user_phone>+79090000001</user_phone>
			<shop_id>110643000000362</shop_id>
			<param>None</param>
			<param_value>None</param_value>
		</colvalues>
	</table>
</response>

Перевод средств другому пользователю

Параметр cmd должен посылаться со значением pay_id .

Обязательные дополнительные параметры:

	sum - сумма перевода. Допустимые значения: дробное число, точность два знака. Разделитель - точка.
	keyt - номер счета для списания средств. Допустимые значения: 15 цифр (номер вашего счета).

Обязательно нужно передать один из следующих параметров:

	keyt_shop - номер счета получателя средств. Допустимые значения: 15 цифр (номер счета пользователя).
	id_shop - ID получателя средств. Допустимые значения: 15 цифр (ID пользователя).
	mobilenumber_shop - номер мобильного телефона получателя средств. Допустимые значения: Номер телефона в международном формате, например, +380951234567.
	email_shop - e-mail адрес получателя средств. Допустимые значения: корректный e-mail.

Необязательные дополнительные параметры:

	comment - комментарий к переводу. Допустимые значения: строка до 250 символов.
	auto_rate - при необходимости разрешить автоматическую конвертацию валют. Например, если счет сервиса в рублях, а счет получателя в долларах США, то будет автоматически выполнена конвертация валют по курсу платежной системы. Допустимые значения: 1 (разрешить конвертацию валют), 0 (запретить). Если параметр не передан, он будет считаться равным 0.
	protect - установить код протекции. Допустимые значения: 0 (установить), 1 (не устанавливать). Если параметр не передан, он будет считаться равным 0.
	protect_code - код протекции. Операция будет завершена, только когда получатель средств введет этот код в личном кабинете. Допустимые значения: Строка от 3 до 60 символов. Если параметр `protect=0`, то данный параметр можно опустить или передать пустым.
	protect_day - срок протекции (в днях). Если в течение указанного периода получатель не введет код протекции, перевод будет возвращен отправителю. Допустимые значения: от 1 до 3 цифр. Если параметр не передан, он будет считаться равным 3.
	apply_unregister - разрешить перевод на незарегистрированный в платежной системе номер телефона/e-mail. Если данная опция включена, и номер телефона или e-mail пользователя не найден в базе пользователей платежной системы, то перевод будет принят, и средства будут зачислены пользователю после регистрации с указанным номером телефона/e-mail. Допустимые значения: 1 (разрешить), 0 (запретить). Если параметр не передан, он будет считаться равным 0.

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>104692411</transact>
	<ext_transact>1</ext_transact>
	<date>20120120071741</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>
	<result>0</result>
	<result_text>Перевод успешно выполнен</result_text>
	<advanced>
		<curr_text>RUR</curr_text>
		<itogo>9.73</itogo>
		<sum>9.8</sum>
		<corr_name>Иванова Зинаида Прокопьевна</corr_name>
		<payproc_comiss>0.07</payproc_comiss>
		<payproc_persent>0.75</payproc_persent>
		<user_name>СУПЕРПУПЕРМАГАЗИН</user_name>
		<curr_code>810</curr_code>
	</advanced>
	<table row="0" col="0" name="">
		<colnames>
		</colnames>
	</table>
</response>

Проверка существования номера счета

Параметр cmd должен посылаться со значением check_keyt .

Обязательные дополнительные параметры:

keyt - номер счета для проверки. Если будет передан один из ваших счетов, то в ответе будет содержаться информация о балансе счета. Допустимые значения: 15 цифр (номер счета).

Необязательные дополнительные параметры: отсутствуют

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

https://dkcp.deltakey.net/ms/autopay.py?num_shop=123&pass=6333c977b3b7ae6d2516f5f551cfb59b& ext_transact=2012011912458500001&password=96e79218965eb72c92a549dd5a330112& program=10033&cmd=check_keyt&keyt=810000000000202

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>0</transact>
	<ext_transact>1</ext_transact>
	<date>20120120075353</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>
	<result>0</result>
	<result_text>Пользователь зарегистрирован в платежной системе</result_text>
	<advanced>
		<instat>1</instat>
		<uid>111643000010062</uid>
		<over>0.00</over>
		<keyt>810000000000202</keyt>
		<balance_itogo>45.00</balance_itogo>
		<balance>45.00</balance>
		<name>Иванова Зинаида Прокопьевна</name>
	</advanced>
	<table row="0" col="0" name="">
		<colnames>
		</colnames>
	</table>
</response>

Платеж в адрес оператора

Параметр cmd должен посылаться со значением pay_momental .

Обязательные дополнительные параметры:

	payform - Код оператора. Для оплаты сотовой связи можно передавать значение 7000, тогда оператор будет определен автоматически. Для остальных операторов коды можно посмотреть здесь
	keyt - номер счета, с которого будут списаны средства (номер счета магазина). Допустимые значения: 15 цифр (номер счета).
	sum - сумма перевода. Допустимые значения: дробное число, точность два знака. Разделитель - точка.
	date_pay - дата приема платежа. Допустимые значения: дата в формате YYYY-MM-DD hh:mm:ss.
	1, 2 ... N - один или несколько параметров платежа. Например, для сотовой связи передается один параметр (номер телефона), для денежного перевода - несколько параметров со сведениями о плательщике и получателе перевода.

Необязательные дополнительные параметры: отсутствуют

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

https://dkcp.deltakey.net/ms/autopay.py?num_shop=123&pass=6333c977b3b7ae6d2516f5f551cfb59b& ext_transact=2012011912458500001&password=96e79218965eb72c92a549dd5a330112& program=10033&cmd=pay_momental&payform=7000&keyt=810000000000202&sum=4&date_pay=2012-03-23+00:00:00&1=9261234567

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>105254431</transact>
	<ext_transact>1</ext_transact>
	<date>20120120075353</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>
	<result>0</result>
	<result_text>Заявка на оплату принята. Транзакция №105254431</result_text>
	<advanced>
		<curr_shop>RUR</curr_shop>
		<curr_pay>RUR</curr_pay>
		<sys_comiss>0.0</sys_comiss>

		<dealer_persent>0.00</dealer_persent>
		<itogo>4</itogo>
		<sys_persent>0.00</sys_persent>
		<summ_pay>4.0</summ_pay>
		<summ_shop>4</summ_shop>
		<dealer_comiss>0.00</dealer_comiss>
	</advanced>
	<table row="0" col="0" name="">
		<colnames>
		</colnames>
	</table>
</response>

Примеры реализации на PHP:
https://merchant.deltakey.net/example/pay_momental/index.php
https://merchant.deltakey.net/example/pay_momental_mobile/index.php

Дерево моментальной оплаты

Параметр cmd должен посылаться со значением get_tree_momental .

Обязательные дополнительные параметры: отсутствуют

Необязательные дополнительные параметры:

	with_field_info - Включить информацию о полях. Допустимые значения: 0 или 1
	country - Страна. Допустимые значения: -1 (все страны), 0 (страна из настроек пользователя) или от 1 до 3 цифр. Коды можно посмотреть здесь
	region - Регион. Допустимые значения: -1 (все регионы), 0 (регион из настроек пользователя) или целое число. Коды можно посмотреть здесь

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

https://dkcp.deltakey.net/ms/autopay.py?num_shop=1234&pass=6333c9775h6fligoSk16f5f551cfb59b& ext_transact=211212051257406073&program=10033&cmd=get_tree_momental&with_field_info=0& password=a76db8110441gjhkd85iykhlfvd6e7fe&country=643&region=10

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<transact>0</transact>
	<ext_transact>201212051336038950</ext_transact>
	<date>20121205133646</date>
	<status>2</status>
	<status_text>Команда выполнена</status_text>
	<result>0</result>
	<result_text>Дерево моментальной оплаты</result_text>
	<advanced>
		<country>643</country>
		<region>10</region>
	</advanced>
	 
	<table row="12" col="6" name="">
		<colnames>
			<type>Тип</type>
			<code>Код</code>
			<root>Группа</root>
			<name>Название</name>
			<website>Адрес сайта провайдера</website>
			<description>Краткое описание</description>
		</colnames>
		<colvalues>
		</colvalues>
	</table>
</response>

Примеры реализации на PHP:
https://merchant.deltakey.net/example/get_form_fields/index.php

Вернуться назад