Описание протокола DKCP-User

По стандарту ExDK реализовано несколько протоколов Системы, представляющие из себя спецификации данного стандарта. Ниже описаны отличия и дополнения спецификаций DKCP-user и DKCP-point.

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

Назначение протокола, область применения
Дополнения протокола DKCP-User к спецификации ExDK
Общая информация
Персонификация и безопасность
Формат запросов
Формат ответов

Назначение протокола, область применения

Программное обеспечение "Delta Key Classic", "Система Мониторинга и Статистики", а также Web-кабинет нашей платежной системы реализованы на основе протокола DKCP-User. Функциональные возможности указанного программного обеспечения раскрывают возможности протокола: любая операция, доступная зарегистрированному пользователю платежной системы, может быть реализована сторонним разработчиком при условии использования протокола DKCP-User.

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

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

	Ввод / Вывод: заказ вывода на банк, настройка инкассации, инкассация, работа с пластиковыми картами и др.;
	Платежи и переводы: моментальная оплата, перевод пользователю, перевод по своим счетам, оплата выставленных счетов и др.;
	Моментальная оплата: платеж в адрес операторов таких групп, как "Финансовые сервисы", "Сотовая связь", "Интернет, IP-телефония", "Коммерческое ТВ", "Коммунальные службы", "Благотворительность", "Платные сервисы", "Прочее...";
	Управление Uni Transfer: получение баланса счета, курсы валют, передать юниты, получить юниты, регистрация в сервисе, смена платежного пароля и др.;
	Статистика: финансовая статистика, журнал операций, субдилерская статистика, ошибочные платежи, отказанные платежи, журнал инкассации, вознаграждение разработчикам ПО и др.;
	Управление электронными чеками: создание электронных чеков, активация электронных чеков, проверка электронных чеков, аннулирование электронных чеков, получение списка выписанных электронных чеков и др.;
	Платежные требования: выставление счета на оплату, контроль статуса, карточка поступлений, карточка платежей, оплата "До востребования" и др.;
	Настройки мерчанта: Регистрация электронного магазина, получение списка магазинов, редактирование настроек и др.;
	Автовыплаты: создание персоны с правами на автовыплату, настройка автовыплаты и др.;
	Массовые платежи: создание платежа, список задач в обработке и др.;
	Безопасность: проверка корреспондента, настройка антифишинга, оплата в 1 клик, настройка доступа по IP, одноразовые ключи, волшебное слово, смена логина, смена пароля, смена платежного пароля, смена UIN Uni Transfer, настройки доступа к ПО, создание новой персоны, распределение прав, перевыпуск сертификата, использование IDENT, настройка инкассации и др.

Сервисы системы, не включенные в данный список, также могут быть реализованы на основе протокола DKCP-User.

Дополнения протокола DKCP-User к спецификации ExDK

Спецификация DKCP-User определяет следующие дополнения стандарта ExDK:

1. Добавлен обязательный параметр, добавляемый при отправке запроса Агентом на Сервер. Данный параметр имеет наименование program, а в качестве значения передается код программы, из которой выполняется запрос. Код выдается при регистрации программы. Зарегистрировать программу может пользователь, дополнительно зарегистрированный в качестве разработчика.

2. В целях авторизации к SSL-соединению добавляется сертификат пользователя, высылаемый Агенту на почтовый адрес при регистрации в системе в качестве пользователя.

Общая информация

Стандарт ExDK определяет взаимодействие Агентов с платежной системой Дельта Кей путем передачи запросов на командный сервер.

Стандарт предусматривает передачу данных от Агента методами POST или GET и получение результирующей XML в определенном данным стандартом формате.

Инициализация взаимодействия всегда исходит от Агента.

Персонификация и безопасность

Обмен данными происходит по закрытому SSL-соединению с использованием сертификата Агента, выданного Агенту Сервером в момент регистрации.

Логин и пароль Агента передаются с каждой командой. При этом пароль передается не в открытом виде, а захешированным по алгоритму md5. Хешируемая строка представляет собой конкатенацию самого пароля, а также номера внешней транзакции (транзакции, передаваемой пользователем, не путать с транзакцией, присваиваемой системой). Таким образом, при уникальности внешней транзакции обеспечивается защита пароля от перехвата, так как обратной операции дехеширования не существует, а строка хеша является уникальной для каждой операции пользователя. Следует отметить, что уникальность внешней транзакции для финансовых операций является строго обязательной; при попытке произвести финансовую операцию с применением использованного ранее номера будет выдана ошибка 7012 - Некорректный номер внешней транзакции. (Коды всех ошибок см. в приложениях).

Для того, чтобы иметь возможность выполнять команды к серверу (например, для программного обращения из скриптов на языке PHP с использованием расширения CURL), необходимо иметь файл ключа и файл сертификата, которые могут быть получены из файла .pfx или .p12, присылаемого пользователю на почту при регистрации в системе. Для конвертации можно воспользоваться утилитой openssl из одноименного пакета:

$ openssl pkcs12 -in 112233.p12 -out 112233.cer -clcerts

Таким образом, получен файл .cer, который используется при запросе:

<?php
	curl_setopt($ch, CURLOPT_SSLKEY, $wmKey);
	curl_setopt($ch, CURLOPT_SSLKEYPASSWD , $wmPass);
	curl_setopt($ch, CURLOPT_SSLCERT, $wmCert);
?>

Формат запросов

Обмен данными происходит при помощи протокола HTTPS. Сервер предоставляет клиенту исполняемый сценарий, доступный для клиента через сеть Интернет. Клиент запрашивает сценарий HTTPS методом GET или POST с передачей текста команды и ее параметров в виде строки запроса.

Формат команды представлен следующим образом:

https://<server_name>/<script_name>?cmd=<cmd>&ext_transact=<ext_transact>
&login=<login>&password=<password>&program=<program>
[&<param_name1>=<param_value1>]...[&<param_nameN>=<param_valueN>]

где:

	`<server_name>` - имя сервера, зависит от того, какие из серверов системы поддерживают пользовательский сертификат;
	`<script_name>` - название скрипта на сервере;
	`<cmd>` - название команды;
	`<ext_transact>` - номер внешней транзакции;
	`<login>` - логин отправителя команды;
	`<password>` - пароль отправителя команды, склеенный (сконкатенированный) с номером внешней транзакции, захешированный по алгоритму md5;
	`<program>` - код программы, из которой инициализирована операция;
	`<param_name1>`, `<param_nameN>` - названия параметров;
	`<param_value1>`, `<param_valueN>` - значения параметров.

К примеру, смена логина может быть выполнена следующей командой:

https://deltakey.net/dkcp/security.py?cmd=change_login&ext_transact=1254&login=ms&password=867c4bc5f2010a95f9971b91ddaa8f47
&program=1250&new_login=test

Здесь новым логином текущего пользователя становится .

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

Спецификация протокола может определять и другие обязательные параметры. Дополнительные параметры определяются посылаемой командой.

Формат ответов

В качестве ответов возвращается 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>

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

	`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` - в случае возвращения таблицы данных - значения строк по столбцам. Количество этих веток равно количеству строк. Количество элементов в каждой ветке равно количеству столбцов.

Для корректной расшифровки ответов необходим Internet Explorer не ниже версии 6.

Примеры реализации см. в разделе Описание стандарта ExDK

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

Партнерам

Платежным системам

Обменным пунктам валют

Кредитным организациям

Агентам по персонификации

МФО и КПКГ

Логотипы, баннеры и кнопки