Главная » XML-GATE » Описание протокола

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

Изменил последним Антон Абрамов 2017/08/31 17:18

Лист изменений

ДатаОписание измененийАвтор
2013.04.22Добавлено описание тэга real_pay при добавлении платежа, применяется только для KZ системыВольф А. А.
2013.05.04Добавлено описание основного алгоритма проведения платежаВольф А. А.
2015.12.11Изменен запрос отмены платежа c act=get на act=cancel, обратная совместимость сохраненаВольф А. А.

Формат on-line запросов

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

Запрос отправляется по URL-адресу, полученному от платежной системы Quickpay.
Запросы к серверу отправляются с помощью метода GET.
Для шифрования соединения применяется протокол https и клиентский сертификат.

ВНИМАНИЕ!
К параметрам применяется url-кодирование.

Существует три типа запросов к серверу провайдера услуг:

  • поиск абонента по номеру лицевого счета (в текущем документе описывается только сотовые телефоны);
  • проведение платежа;
  • проверка статуса платежа.

Тип запроса определяется значением параметра act.

Алгоритм проведения платежа

Процесс проведения проходит в 3 этапа:

  1. Проверка реквизитов платежа
  2. Добавление платежа
  3. Проверка статуса платежа

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

Запрос проверки реквизитов простого платежа

Пример шаблона для запроса проверки реквизитов простого платежа (verify):

http://SERVER:PORT/index.php?act=verify&srv=SERVICE&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service><account><value>PHONE</value></account></operation></root>

ПараметрЗначениеОписание
actverifyТип запроса
srvчисло, intНомер сервиса
xmlxml-документXML документ запроса
SERVER:PORTадрес и порт сервераСмотрите в личном кабинете в настройках api-точки

Таблица 1: Параметры HTTP запроса (verify)

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, skey )>
   <!ELEMENT operation ( service, account, total )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT time ( #PCDATA )>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT skey ( #PCDATA )>
   <!ELEMENT service ( #PCDATA )>
   <!ELEMENT account ( value )>
   <!ELEMENT value ( #PCDATA )>
]>
ПолеТипОписание
timestring, по указанному форматувремя приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)
pointintНомер точки через которую будут проводиться платежи
skeystringКлюч на сервер (для валидации запроса на сервер)
serviceintНомер сервиса (как в параметре srv)
account Тэг для передачи реквизитов абонента
valuestringНомер телефона, номер лицевого счета и т.д.

Таблица 2: Параметры XML-документа в HTTP-запросе (verify)

АтрибутТипОписание
idlongУникальный идентификатор платежа

Таблица 3: Атрибуты тэга operation XML-документа в HTTP-запросе (verify)


Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, akey, newmenu? )>
   <!ELEMENT operation ( err, add, ctype, komm, msg? )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT time ( #PCDATA )>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT akey ( #PCDATA )>
   <!ELEMENT newmenu EMPTY>
   <!ELEMENT err ( #PCDATA )>
   <!ELEMENT msg ( #PCDATA )>
]>
ПолеТипОписание
timestring, по указанному форматувремя приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)
pointintномер точки через которую будут проводиться платежи
akeystringключ на аппарат (для валидации ответа от сервера)
newmenu тег для терминалов информирующий об обновлении меню (игнорировать)
errintрезультат валидации (0 — успех, 1 — ошибка)
msgstringпри успешной валидации (err = 0) тег может содержать информацию об абоненте(ФИО либо другие данные если они известны)

Таблица 4: Параметры XML-документа ответа от сервера (verify)

АтрибутТипОписание
idlongУникальный идентификатор платежа

Таблица 5: Атрибуты тэга operation XML-документа ответа от сервера (verify)

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

<root>
   <header>
       <time>2011-03-17 15:06:11</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>0</err>
   </operation>
</root>

Запрос добавления платежа в систему

Пример шаблона для запроса добавления платежа в систему (add), сумма принятого платежа равна сумме зачисления на счет:

http://SERVER:PORT/index.php?act=add&srv=SERVICE&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service><account><value>PHONE</value></account><total>SUM</total></operation></root>

Пример шаблона для запроса добавления платежа в систему (add), сумма принятого платежа не равна сумме зачисления на счет:

http://SERVER:PORT/index.php?act=add&srv=SERVICE&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service><account><value>PHONE</value></account><total>SUM</total><real_pay>SUM2</real_pay></operation></root>

Параметр

Значение

Описание

act

add

Тип запроса

srv


Номер сервиса

xml

xml-документ

XML документ запроса

Таблица 6: Параметры HTTP запроса (add)

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, skey )>
   <!ELEMENT operation ( service, account, total, real_pay? )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT time ( #PCDATA )>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT skey ( #PCDATA )>
   <!ELEMENT service ( #PCDATA )>
   <!ELEMENT account ( value )>
   <!ELEMENT value ( #PCDATA )>
   <!ELEMENT total ( #PCDATA )>
   <!ELEMENT real_pay ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

Номер точки через которую будут проводиться платежи

skey

string

Ключ на сервер (для валидации запроса на сервер)

service

int

Номер сервиса (как в параметре srv)

account


Тэг для передачи реквизитов абонента

value

string

Номер телефона, номер лицевого счета и т.д.

total

double

сумма внесенная плательщиком

real_pay

double

сумма к зачислению на счет (только для KZ)

Таблица 7: Параметры XML-документа в HTTP-запросе (add)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа

Таблица 8: Атрибуты тега operation XML-документа в HTTP-запросе (add)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, akey, newmenu? )>
   <!ELEMENT operation ( err, add, ctype, komm )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT time ( #PCDATA )>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT akey ( #PCDATA )>
   <!ELEMENT newmenu EMPTY>
   <!ELEMENT err ( #PCDATA )>
   <!ELEMENT add ( #PCDATA )>
   <!ELEMENT ctype ( #PCDATA )>
   <!ELEMENT komm ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


тег для терминалов информирующий об обновлении меню (игнорировать)

err

int

ошибка во время приема (0 — успех, 1 — ошибка)

add

double

сумма платежа

ctype,komm


игнорировать

Таблица 9: Параметры XML-документа ответа от сервера (add)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа

Таблица 10: Атрибуты тега operation XML-документа ответа от сервера (add)


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

<root>
   <header>
       <time>2011-03-17 15:06:11</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>0</err>
       <add>500.00</add>
       <ctype>1</ctype>
       <komm>0.00</komm>
   </operation>
</root>

Запрос добавления платежа в US системе

Пример шаблона для запроса добавления платежа в систему:

http://URL:PORT/index.php/?act=pay&srv=ID_SERVICE&xml=<root><header><time>TIME_ADD</time><point>ID_POINT</point><skey>SKEY</skey></header><operation id="ID" mode="TEST_OR_LIVE"><service>ID_SERVICE</service><account><persacc>IDENTIFIER</persacc><text>TEXT_FOR_SMS_SERVICE</text></account><real_pay>SUM_OF_PAY</real_pay><total>SUM</total></operation></root>

Параметр

Значение

Описание

act

pay

Тип запроса

srv


Номер сервиса

xml

xml-документ

XML документ запроса

Таблица 1: Параметры HTTP запроса (pay)

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root (header, operation) >

  <!ELEMENT header (time, point, skey)>
  <!ELEMENT operation (service, account, real_pay, total)>
  <!ELEMENT account (persacc, text?)>
  <!ATTLIST operation
     id ID #REQUIRED
     mode (test|live) "live"
   >

  <!ELEMENT time ( #PCDATA )>
  <!ELEMENT point ( #PCDATA )>
  <!ELEMENT skey ( #PCDATA )>
  <!ELEMENT service ( #PCDATA )>
  <!ELEMENT persacc( #PCDATA )>
  <!ELEMENT real_pay ( #PCDATA )>
  <!ELEMENT total ( #PCDATA )>
  <!ELEMENT text ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время добавления платежа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

номер точки с которой производится платеж

skey

string

ключ на сервер (для валидации запроса на сервер)

service

int

номер сервиса (идентичен с параметром srv)

account


тэг для передачи реквизитов абонента

persacc

string

идентификатор (номер телефона, номер лицевого счета и т.д.)

real_pay

double

сумма к зачислению на счет (Пример: 56.00)

total

double

сумма к зачислению на счет ( тоже что и «real_pay»Пример: 56.00)

text

string

тег используется для сервисов отправки смс сообщений,в нем передается текст сообщения, все вхождения спец символов в сообщение заменяются в соответствии с описанием:
'&' (амперсанд) преобразуется в '&amp;'

'"' (двойная кавычка) преобразуется в '&quot;'

"'" (одиночная кавычка) преобразуется в '&#039;'

'<' (знак "меньше чем") преобразуется в '&lt;'

'>' (знак "больше чем") преобразуется в '&gt;'

, максимальная длина сообщения составляет 160 символов латинского алфавита(в случае превышения максимальной длины сообщение обрезается, при использовании некорректных символов платеж завершиться с ошибкой), теги «real_pay» и «total» при добавлении платежа по смс сервису не учитываются.

Таблица 2: Параметры XML-документа в HTTP-запросе (pay)

Атрибут

Тип

Описание

id

long

уникальный идентификатор платежа

mode

string

режим обработки запросов('test' — тестовый режим обработки платежей, 'live' — боевой режим обработки платежей. При отсутствии тега или значения все платежи проводятся в боевом режиме)

Таблица 3: Атрибуты тега operation XML-документа в HTTP-запросе (pay)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root (header, operation)>

  <!ELEMENT header (time, point, akey, newmenu?)>
  <!ELEMENT operation (err, add?, ctype?, komm?, balance?)>
  <!ATTLIST operation id ID #REQUIRED>
  <!ELEMENT time ( #PCDATA )>
  <!ELEMENT point ( #PCDATA )>
  <!ELEMENT akey ( #PCDATA )>
  <!ELEMENT newmenu EMPTY>
  <!ELEMENT err ( #PCDATA )>
  <!ELEMENT add ( #PCDATA )>
  <!ELEMENT ctype ( #PCDATA )>
  <!ELEMENT komm ( #PCDATA )>
  <!ELEMENT balance ( #PCDATA )>
]>


Поле

Тип

Описание

time

string, по указанному формату

время приема платежа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

номер точки с которой производится платеж

akey

string

ключ на аппарат (для валидации ответа от сервера)

err

int

код ошибки приема платежа (0 — успех, 1 — ошибка)

add

double

сумма платежа

balance

double

баланс дилера(тег информирует о недостатке средств на счете дилера для проведения платежа, при появлении тега необходимо пополнить счет для дальнейшего приема платежей)

newmenu


игнорировать

komm


игнорировать

ctype


игнорировать

Таблица 4: Параметры XML-документа ответа от сервера (pay)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа

Таблица 5: Атрибуты тега operation XML-документа ответа от сервера (pay)

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

<root>
   <header>
       <time>2014-02-19 12:58:09</time>
       <point>ID_POINT</point>
       <akey>AKEY</akey>
       <newsetting/>
   </header>
   <operation id="ID_OPERATION">
       <err>0</err>
       <add>20.00</add>
       <ctype>2</ctype>
       <komm>2.00</komm>
   </operation>
</root>

<root>
   <header>
       <time>2014-02-25 10:37:53</time>
       <point>ID_POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
       <newsetting/>
   </header>
   <operation id="ID_OPERATION">
       <err mmenu="1" delay="2">1</err>
       <msg>Аппарат находится на сервисном обслуживании #FA92</msg>
       <balance>2.625</balance>
   </operation>
</root>

Запрос проверки статуса платежа в системе

Пример шаблона для запроса статуса платежа в системе (status):

http://SERVER:PORT/index.php?act=status&srv=SERVICE&xml=<root><header><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service></operation></root>

Параметр

Значение

Описание

act

status

Тип запроса

srv


Номер сервиса

xml

xml-документ

XML документ запроса

Таблица 11: Параметры HTTP-запроса (status)

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( point, skey )>
   <!ELEMENT operation ( service )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT skey ( #PCDATA )>
   <!ELEMENT service EMPTY>
]>

Поле

Тип

Описание

point

int

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

skey

string

ключ на аппарат (для валидации ответа от сервера)

service

int

Номер сервиса (как в параметре srv)

Таблица 12: Параметры XML-документа в HTTP-запросе(status)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа

Таблица 13: Атрибуты тега operation XML-документа в HTTP-запросе (status)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( point, akey, newmenu? )>
   <!ELEMENT operation ( err, time_proc?, msg, additional )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT akey ( #PCDATA )>
   <!ELEMENT newmenu EMPTY>
   <!ELEMENT err ( #PCDATA )>
   <!ELEMENT time_proc ( #PCDATA )>
   <!ELEMENT msg ( #PCDATA )>
   <!ELEMENT additional ( #PCDATA )>
]>

Поле

Тип

Описание

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

err

int

код ошибки

time_proc

string

время проведения платежа системой (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

msg

string

описание ошибки

additional

int

расширенный код ошибки

Таблица 14: Параметры XML-документа ответа от сервера (status)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа

Таблица 15: Атрибуты тега operation XML-документа ответа от сервера (status)

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

<root>
   <header>
       <time>2011-03-17 15:01:30</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>0</err>
       <msg></msg>
       <additional></additional>
   </operation>
</root>

Запрос проверки статуса платежа в US системе

Пример шаблона для запроса проверки статуса платежа:

http://SERVER:PORT/index.php?act=status&srv=SERVICE&xml=<root><header><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service></operation></root>

Параметр

Значение

Описание

act

status

тип запроса

srv

идентификатор

идентификатор сервиса в системе Quickpay

xml

xml-документ

XML документ запроса

Таблица 1: Параметры HTTP-запроса (status)

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >

  <!ELEMENT header ( point, skey )>
  <!ELEMENT operation ( service )>
  <!ATTLIST operation id ID #REQUIRED>
  <!ELEMENT point ( #PCDATA )>
  <!ELEMENT skey ( #PCDATA )>
  <!ELEMENT service EMPTY>
]>

Поле

Тип

Описание

point

int

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

skey

string

ключ на аппарат (для валидации ответа от сервера)

service

int

номер сервиса (как в параметре srv)

Таблица 2: Параметры XML-документа в HTTP-запросе(status)

Атрибут

Тип

Описание

id

long

уникальный идентификатор платежа

Таблица 3: Атрибуты тега operation XML-документа в HTTP-запросе (status)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( point, akey, newmenu? )>
<!ELEMENT operation ( err, msg, additional, online_inform?, time_proc?)>
<!ELEMENT online_inform ( param? ) >
<!ATTLIST operation id ID #REQUIRED>
<!ATTLIST online_inform wait CDATA #REQUIRED>
<!ATTLIST param
 name CDATA #REQUIRED
 value CDATA #REQUIRED
>

<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT newmenu EMPTY>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT time_proc ( #PCDATA )>
<!ELEMENT msg ( #PCDATA )>
<!ELEMENT additional ( #PCDATA )>
]>

Поле

Тип

Описание

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

err

int

код ошибки

time_proc

string

время проведения платежа системой (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

msg

string

описание ошибки

additional

int

расширенный код ошибки

online_inform


информационный параметр для терминала

param


содержит информацию о пин коде

Таблица 4: Параметры XML-документа ответа от сервера (status)

Атрибут

Тип

Описание

id

long

уникальный идентификатор платежа

Таблица 5: Атрибуты тега operation XML-документа ответа от сервера (status)

Атрибут

Тип

Описание

wait

int

информирует терминал о необходимости ожидания обработки платежа для получения пин кода

Таблица 6: Атрибуты тега online_inform XML-документа ответа от сервера (status)

Атрибут

Тип

Описание

name

string

название параметра(в запросе статуса используется только «PIN»)

value

string

значение параметра (зависит от состояния платежа, может содержать пин код при успешной обработке платежа или текст с ошибкой при ошибки проведения платежа)

Таблица 7: Атрибуты тега param XML-документа ответа от сервера (status)

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

<root>
   <header>
       <time>2014-04-14 03:29:05</time>
       <point>ID_POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
       <newsetting/>
       </header>
       <operation id="ID_OPERATION">
           <err>0</err>
           <online_inform wait="1"></online_inform>
           <msg></msg>
       </operation>
</root>
<root>
   <header>
       <time>2014-04-14 00:37:23</time>
       <point>ID_POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
       <newsetting/>
   </header>
   <operation id="ID_OPERATION">
       <err>101</err>
       <time_proc>2014-04-14 00:37:15</time_proc>
       <online_inform wait="0">
           <param name="PIN" value="111111-222222-333333"/>
       </online_inform>
       <msg></msg>
       <additional>0</additional>
   </operation>
</root>

Описание кодов ошибок при запросе статуса платежа

Коды ошибок при запросе статуса платежа:

Код ошибки

Текст ошибки

Фатальность

102

ошибка при проведении платежа

1

101

платеж успешно проведен

1

0

повторить запрос позже, платеж обрабатывается

0

-60

платеж не найден

1

Расширенные коды ошибок при запросе статуса платежа:

Код ошибки

Текст ошибки

Фатальность

0

платеж успешно проведен

1

1

повторить запрос позже, платеж обрабатывается

0

-7

такой id уже существует

1

-8

неверная сумма

1

-9

неверная точка

1

-10

нет обязательного параметра

1

-11

платеж не принят

1

-22

плательщик не зарегистрирован

1

-23

идентификатор не верен

1

-24

операция отклонена по техническим причинам

1

-45

сервис временно заблокирован

1

-61

дата неверна

1

-64

внутренняя ошибка

1

-96

неверный ответ

1

-97

неверный формат запроса

1

-98

неизвестный запрос

1

-99

ошибка парсинга

1

-100

нет соединения с сервером поставщика услуг

1

-101

аппарат не зарегистрирован

1

-501

платеж остановлен в ручном режиме

1

-504

платеж отменен

1

-10001

недостаточно средств на счете у поставщика

1

-10002

превышена максимальная сумма проведения данного аппарата

1

-10003

недостаточно средств QuickPay

0

-10103

превышен лимит суммы по номеру телефона

1

-10104

идентификатор в чёрном списке

1

-9999

неизвестная ошибка

1

Запрос текущего баланса в системе

Пример шаблона для запроса текущего баланса в системе:

http://SERVER:PORT/index.php?srv=balance&act=get&xml=<root><header><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>balance</service></operation></root>

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, skey )>
   <!ELEMENT operation ( service )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT skey ( #PCDATA )>
   <!ELEMENT service ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

Номер точки через которую будут проводиться платежи

skey

string

Ключ на сервер (для валидации запроса на сервер)

service

string

Номер сервиса (как в параметре srv)

Таблица 16: Параметры XML-документа в HTTP-запросе (balance)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор операции, для запроса баланса может быть пустым

Таблица 17: Атрибуты тэга operation XML-документа в HTTP-запросе (balance)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( point, akey, newmenu? )>
   <!ELEMENT operation (err, name, balance, reserve, overdraft )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT akey ( #PCDATA )>
   <!ELEMENT newmenu EMPTY>
   <!ELEMENT err ( #PCDATA )>
   <!ELEMENT name ( #PCDATA )>
   <!ELEMENT balance ( #PCDATA )>
   <!ELEMENT reserve ( #PCDATA )>
   <!ELEMENT overdraft ( #PCDATA )>
]>


Поле

Тип

Описание

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

err

int

код ошибки

name

string

имя дилера

balance

double

баланс дилера - резерв

reserve

double

сумма платежей в очереди на проведение

overdraft

double

сумма офердрафта

Таблица 18: Параметры XML-документа ответа от сервера (balance)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа, копия данных из запроса

Таблица 19: Атрибуты тега operation XML-документа ответа от сервера (balance)


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

<root>
   <header>
       <time>2011-03-17 15:01:30</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>0</err>
       <name>NAME</name>
       <balance>100.06</balance>
       <reserve>0</reserve>
       <overdraft>0</overdraft>
   </operation>
</root>

Запрос для получения отчета за день

Пример шаблона для запроса получения отчета за день:

http://SERVER:PORT/act=get&srv=mreport&xml=<root><header><time>2013-05-30</time><point>POINT</point><skey>SKEY</skey></header><operation id='ID'><service>mreport</service><date> <period>PERIOD</period><begin>2013-06-02</begin><end>2013-07-20</end></date><service_id>SERVICE ID<service_id><report_type>1</report_type> <timezone>TIMEZONE</timezone></operation> </root>

Параметр

Значение

Описание

act

get

тип запроса

srv

mreport

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 20: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, date, report_type, service_id?,timezone? )>
<!ELEMENT date ( period?, begin, end )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
<!ELEMENT service_id ( #PCDATA )>
<!ELEMENT report_type ( #PCDATA )>
<!ELEMENT begin ( #PCDATA )>
<!ELEMENT end ( #PCDATA )>
<!ELEMENT period ( #PCDATA )>
<!ELEMENT timezone ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

report_type

int

тип запрашиваемого отчета, в данном случае равен «1».

service_id

int

идентификатор сервиса на стороне Quickpay(при отсутствии тега или отсутствии значения в нем поиск производится по всем сервисам)

begin

string, по указанному формату

время с которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

end

string, по указанному формату

время до которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

period

int

период за который будет формироваться отчет в часах (если указан период то теги begin и end не учитываются)

timezone

int

флаг обработки запроса по времени дилера( 0 — обработка идет по времени сервера, 1 — обработка идет по времени дилера)

Таблица 21: Параметры XML-документа в HTTP-запросе (mreport)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 22: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, diler, payments, msg )>
<!ELEMENT payments ( total, completed, queue, error )>
<!ELEMENT total ( count, totalsum, realsum )>
<!ELEMENT completed ( count, totalsum, realsum )>
<!ELEMENT queue ( count, totalsum, realsum )>
<!ELEMENT error ( count, totalsum, realsum )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT diler ( #PCDATA )>
<!ELEMENT count ( #PCDATA )>
<!ELEMENT totalsum ( #PCDATA )>
<!ELEMENT realsum ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

diler

string

название дилера

count

int

количество платежей

totalsum

int

сумма реально внесенная клиентом по всем платежам

realsum

int

зачисленная сумма за вычетом комиссии по всем платежам

Таблица 23: Параметры XML-документа ответа от сервера

Примечание: тег <payments> содержит информацию о проведенных платежах (тег <completed>), платежах в очереди (тег <queue>),

платежах с ошибкой (тег <error>) и суммарную информацию о всех платежах (тег <total>).

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 24: Атрибуты тега operation XML-документа ответа от сервера

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

<root>
<header>
 <time>2013-08-07 14:17:45</time>
 <point>point</point>
 <akey>akey</akey>
 <newmenu/>
 <newsetting/>
</header>
<operation id="">
 <err>0</err>
 <diler>Иванов ИП</diler>
 <payments>
  <total>
   <count>11</count>
   <totalsum>2490</totalsum>
   <realsum>2343</realsum>
  </total>
  <completed>
   <count>0</count>
   <totalsum>0</totalsum>
   <realsum>0</realsum>
  </completed>
  <queue>
   <count>11</count>
   <totalsum>2490</totalsum>
   <realsum>2343</realsum>
  </queue>
  <error>
   <count>0</count>
   <totalsum>0</totalsum>
   <realsum>0</realsum>
  </error>
 </payments>
</operation>
</root>

Запрос для получения подробного отчёта за день

Пример шаблона для запроса получения подробного отчета за день:

http://SERVER:PORT/act=get&srv=mreport&xml=<root><header><time>2013-05-30</time><point>POINT</point><skey>SKEY</skey></header><operation id='2'><service>mreport</service><date><period>PERIOD</period><begin>2013-06-02</begin><end>2013-07-20</end></date><report_type>2</report_type><service_id>SERVICE ID</service_id><sort>1</sort><timezone>TIMEZONE</timezone></operation></root>

Параметр

Значение

Описание

act

get

тип запроса

srv

mreport

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 25: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, date, report_type, sort?, service_id?, timezone? )>
<!ELEMENT date ( period?,begin, end )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
<!ELEMENT report_type ( #PCDATA )>
<!ELEMENT service_id ( #PCDATA )>
<!ELEMENT sort ( #PCDATA )>
<!ELEMENT begin ( #PCDATA )>
<!ELEMENT end ( #PCDATA )>
<!ELEMENT period ( #PCDATA )>
<!ELEMENT timezone ( #PCDATA )>
]>


Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

report_type

int

тип запрашиваемого отчета, в данном случае равен «2».

sort

int (0, 1, 2)

варианты сортировки информации о платежах в ответе: 0 (по умолчанию) — по времени проведения платежа, 1 - по времени поступления платежа в систему, 2 - местное время проведения платежа

service_id

int

идентификатор сервиса на стороне Quickpay(при отсутствии тега или отсутствии значения в нем поиск производится по всем сервисам)

begin

string, по указанному формату

время с которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

end

string, по указанному формату

время до которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

period

int

период за который будет формироваться отчет в часах (если указан период то теги begin и end не учитываются)

timezone

int

флаг обработки запроса по времени дилера( 0 — обработка идет по времени сервера, 1 — обработка идет по времени дилера)

Таблица 26: Параметры XML-документа в HTTP-запросе (mreport)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 27: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, diler, payments, report, msg? )>
<!ELEMENT payments ( total, completed, queue, error )>
<!ELEMENT total ( count, totalsum, realsum )>
<!ELEMENT completed ( count, totalsum, realsum )>
<!ELEMENT queue ( count, totalsum, realsum )>
<!ELEMENT error ( count, totalsum, realsum )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT diler ( #PCDATA )>
<!ELEMENT count ( #PCDATA )>
<!ELEMENT totalsum ( #PCDATA )>
<!ELEMENT realsum ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

diler

string

название дилера

count

int

количество платежей

totalsum

int

сумма реально внесенная клиентом по всем платежам

realsum

int

зачисленная сумма за вычетом комиссии по всем платежам

report

string, по указанному формату

реестр платежей (Формат: номер операции(идентификатор в БД Quickpay); услуга(название или id, если ПУ предоставляет несколько сервисов на оплату); номер счета; сумма транзакции (от Quickpay); сумма переданная на счет абоненту; время приема транзакции (от Quickpay); время проведения транзакции (на стороне Quickpay); время проведения транзакции (на стороне ПУ);статус платежа в системе Quickpay(2-ошибка, 1-проведен, равный и меньше 0 в очереди);код ошибки(передается если статус платежа равен двум при другом статусе передается пустая строка); )

Таблица 28: Параметры XML-документа ответа от сервера

Примечание: тег <payments> содержит информацию о проведенных платежах (тег <completed>), платежах в очереди (тег <queue>),

платежах с ошибкой (тег <error>) и суммарную информацию о всех платежах (тег <total>).

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 29: Атрибуты тега operation XML-документа ответа от сервера

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

<root>
<header>
 <time>2013-08-07 14:17:45</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
 <newsetting/>
</header>
<operation id="">
 <err>0</err>
 <diler>Иванов ИП</diler>
 <payments>
  <total>
   <count>11</count>
   <totalsum>2490</totalsum>
   <realsum>2343</realsum>
  </total>
  <completed>
   <count>0</count>
   <totalsum>0</totalsum>
   <realsum>0</realsum>
  </completed>
  <queue>
   <count>11</count>
   <totalsum>2490</totalsum>
   <realsum>2343</realsum>
  </queue>
  <error>
   <count>0</count>
   <totalsum>0</totalsum>
   <realsum>0</realsum>
  </error>
 </payments>
 <report>35863326;15;7028720978;200;180;2012-07-02 11:40:23;2012-07-02 11:42:26;2012-07-02 13:40:16;1;;35863381;3;7051669836;200;180;2012-07-02 11:41:21;2012-07-02 11:42:27;2012-07-02 13:41:16;1;;35322062;18;7004827744;200;180;2012-06-21 18:31:30;2012-07-02 11:42:31;2012-06-21 20:28:56;2;-23;35429014;15;7784221198;200;180;2012-06-23 19:19:00;2012-07-02 11:44:01;2012-06-23 21:18:47;2;-23;35455215;3;7057187719;200;180;2012-06-24 12:52:51;2012-07-02 11:44:01;2012-06-24 14:52:29;2;-23;35863722;15;7757795661;220;200;2012-07-02 11:47:02;2012-07-02 11:48:13;2012-07-02 13:43:34;1;;35863723;3;7776635543;500;480;2012-07-02 11:47:04;2012-07-02 11:48:13;2012-07-02 13:44:18;1;;35866531;3;7054004642;120;100;2012-07-02 12:39:37;2012-07-02 12:41:55;2012-07-02 14:37:09;1;;35867006;3;7057106553;200;180;2012-07-02 12:48:39;2012-07-02 12:51:01;2012-07-02 14:48:34;1;;35867584;15;7786292943;200;180;2012-07-02 13:00:42;2012-07-02 13:03:01;2012-07-02 15:00:38;1;;35869664;15;7751283659;500;480;2012-07-02 13:39:20;2012-07-02 13:40:18;2012-07-02 15:39:16;1;;35869763;15;7028717113;120;100;2012-07-02 13:41:07;2012-07-02 13:42:23;2012-07-02 15:41:00;1;;35870413;150;7072839968;200;180;2012-07-02 13:54:15;2012-07-02 13:56:40;2012-07-02 15:54:09;1;;35738262;2017;002360028;4800;4800;2012-06-29 18:35:16;2012-07-02 15:10:19;2012-06-29 20:35:18;1;;35877298;14;7018822210;220;200;2012-07-02 15:56:25;2012-07-02 15:58:40;2012-07-02 17:54:56;1;;35877285;15;7028143564;220;200;2012-07-02 15:56:18;2012-07-02 15:58:40;2012-07-02 17:55:26;1;;
 </report>
</operation>
</root>

Запрос для поиска платежа

Пример шаблона для запроса поиска платежа:

http://SERV:PORT/index.php?act=get&srv=mreport&xml=<root><header><time>2013-05-30</time><point>POINT</point><skey>SKEY</skey></header><operation id='2'><service>mreport</service><id_payment>ID</id_payment><phone>NUMBER</phone><date><period>PERIOD</period></date><report_type>0</report_type><timezone>TIMEZONE</timezone></operation> </root>

Параметр

Значение

Описание

act

get

тип запроса

srv

mreport

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 30: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, id_payment, phone, date, report_type, timezone?)>
<!ELEMENT date ( period, begin, end )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
<!ELEMENT report_type ( #PCDATA )>
<!ELEMENT id_payment ( #PCDATA )>
<!ELEMENT phone ( #PCDATA )>
<!ELEMENT period ( #PCDATA )>
<!ELEMENT timezone ( #PCDATA )>
]>


Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

report_type

int

тип запрашиваемого отчета, в данном случае равен «0».

id_payment

int

ID платежа в системе Quickpay(при указанном ID поиск осуществляется только по нему)

phone

int

номер или часть номера абонента

period

int

период в часах, поиск осуществляется от текущего времени минус период (используется совместно с номером абонента, если указан период то теги begin и end не учитываются)

begin

string, по указанному формату

время с которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

end

string, по указанному формату

время до которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

timezone

int

флаг обработки запроса по времени дилера( 0 — обработка идет по времени сервера, 1 — обработка идет по времени дилера)

Таблица 31: Параметры XML-документа в HTTP-запросе (mreport)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 32: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера предоставляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, diler, report, msg? )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT diler ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

diler

string

название дилера

report

string, по указанному формату

реестр платежей (Формат: номер операции(идентификатор в БД Quickpay); услуга(название или id, если ПУ предоставляет несколько сервисов на оплату); номер счета; сумма транзакции (от Quickpay); сумма переданная на счет абоненту; время приема транзакции (от Quickpay); время проведения транзакции (на стороне Quickpay); время проведения транзакции (на стороне ПУ);статус платежа в системе Quickpay(2-ошибка, 1-проведен, равный и меньше 0 в очереди); код ошибки в системе Quickpay(передается если статус платежа равен двум при другом статусе передается пустая строка); )

Таблица 33: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 34: Атрибуты тега operation XML-документа ответа от сервера

Пример ответа:
<root>
<header>
 <time>2013-08-08 10:23:49</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
 <newsetting/>
</header>
 <operation id="">
 <err>0</err>
 <diler>Иванов ,ИП</diler>
 <report>35863326;15;7028720978;200;180;2012-07-02 11:40:23;2012-07-02 11:42:26;2012-07-02 13:40:16;1;;35863381;3;7051669836;200;180;2012-07-02 11:41:21;2012-07-02 11:42:27;2012-07-02 13:41:16;1;;
 </report>
</operation>
</root>

Запрос ставки вознаграждения и комиссий с клиента по всем или конкретному сервису

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

SERVER:PORT/index.php?act=get&srv=reward&xml=<root><header><time></time><point>POINT</point><skey>SKEY</skey></header>

<operation id="3"><service>reward</service><select_service>ID_SERVICE</select_service></operation></root>

Параметр

Значение

Описание

act

get

тип запроса

srv

reward

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 35: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, select_service)>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
<!ELEMENT select_service ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

select_service

string

идентификатор сервиса — для запроса ставки вознаграждения по одному сервису; «all» - для запроса ставки вознаграждения по всем сервисам

Таблица 36: Параметры XML-документа в HTTP-запросе (reward)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 37: Атрибуты тэга operation XML-документа в HTTP-запросе (reward)

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, services, msg? )>
<!ELEMENT services ( service? )>
<!ELEMENT service ( id, type, value )>
<!ATTLIST operation id ID #REQUIRED>
<!ATTLIST services count CDATA #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT id ( #PCDATA )>
<!ELEMENT type ( #PCDATA )>
<!ELEMENT value ( #PCDATA )>
<!ELEMENT comission_type ( #PCDATA )>
<!ELEMENT comission_value ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

id

int

идентификатор сервиса на стороне Quickpay

type

int(0,1,2)

тип вознаграждения по сервису(0 — фиксированная сумма, 1 — включенный процент, 2 — прямой процент)

value

double

значение вознаграждения по сервису

comission_type

int(0,1,2,3,10)

тип комиссии с клиента по сервису(0 — фиксированная сумма, 1 — включенный процент, 2 — прямой процент, 3 - интервальная с округлением, 10 - интервальная)

comission_value

string

значение комиссии с клиента по сервису. В сдучае если комиссия интервальная, то выдаётся строка вида "0-999:0:5;" где: "0-999" - интервал, "0" - тип комиссии, "5" - значение комиссии. Интервалы разделены точкой с запятой.

msg

string

коментарий

Таблица 38: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 39: Атрибуты тега operation XML-документа ответа от сервера

Атрибут

Тип

Описание

count

int

количество сервисов

Таблица 40: Атрибуты тега services XML-документа ответа от сервера

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

<root>
<header>
 <time>2013-08-12 10:42:02</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
 <newsetting/>
</header>
<operation id="">
 <err>0</err>
 <services count="1">
  <service>
   <id>3</id>
   <type>2</type>
   <value>0.1</value>
   <comission_type>0</comission_type>
   <comission_value>30</comission_value>
  </service>
 </services>
 <msg>OK</msg>
</operation>
</root>

Запрос курса обмена валюты по определенному сервису

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

http://SERVER:PORT/index.php?act=exchange&srv=SERVICE&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service></operation></root>

Параметр xml представляет собой XML-документ, соответствующий шаблону:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service EMPTY>
]>

Параметр

Значение

Описание

act

exchange

тип запроса

srv

число, int

номер сервиса

xml

xml-документ

xml документ запроса

Таблица 41: Параметры HTTP запроса

Поле

Тип

Описание

skey

string

ключ на сервер (для валидации запроса на сервер)

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2013-03-03 09:36:26)

point

int

номер точки

service

int

номер сервиса (как в параметре srv)

Таблица 42: Параметры XML-документа в HTTP-запросе

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 43: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu? )>
<!ELEMENT operation ( err, currency?, exchange?, msg )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT newmenu EMPTY>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT currency ( #PCDATA )>
<!ELEMENT exchange ( #PCDATA )>
<!ELEMENT msg ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

номер точки

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


тег для терминалов информирующий об обновлении меню (игнорировать)

err

int

ошибка во время приема (0 — успех, 1 — ошибка)

currency

string

идентификаторы валют в стандарте ISO 4217 (Пример: обмен валют для сервера осуществляется из KZT в RUB, то в теге будет содержаться: KZTRUB. При отсутствии настроек валюты для сервера тег остается пустым.)

exchange

double

курс обмена валюты для сервиса (Пример: в теге "currency" содержится KZTRUB, то EXCHANGE(KZT) = 1(RUB). При пустом теге "currency", EXCHANGE = 1)

msg

string

коментарий

Таблица 44: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 45: Атрибуты тега operation XML-документа ответа от сервера

Пример успешного ответа:
<root>
<header>
 <time>2013-03-17 15:06:11</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
</header>
<operation id="1">
 <err>0</err>
  <currency>KZTRUB</currency>
  <exchange>5.2298400000001</exchange>
  <msg>OK</msg>
</operation>
</root>

Пример ответа с ошибкой:

<root>
<header>
 <time>2013-03-17 15:06:11</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
</header>
<operation id="1">
 <err>1</err>
 <msg>Текс ошибки</msg>
</operation>
</root>

Запрос реестра платежей за определенный период

Пример шаблона для запроса реестра платежей:

http://SERVER:PORT/index.php?act=GET&srv=REPORT&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>REPORT</service><date>DATE</date><sort>SORT</sort></operation></root>

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, date, sort? )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service EMPTY>
<!ELEMENT date ( #PCDATA )>
<!ELEMENT sort EMPTY>
]>

Параметр

Значение

Описание

act

get

тип запроса

srv

report

сервис запроса реестра

xml

xml-документ

xml документ запроса

Таблица 46: Параметры HTTP запроса

Поле

Тип

Описание

skey

string

ключ на сервер (для валидации запроса на сервер)

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2013-03-03 09:36:26)

point

int

номер точки

service

string

сервис запроса реестра (как в параметре srv)

date

string, по указанному формату

время с которого будет формироваться реестр (Формат: YYYY-mm-dd, Пример: 2013-05-06)

sort

int, (0, 1, 2)

варианты сортировки запроса: 0 (по умолчанию) — по времени проведения платежа, 1 - по времени поступления платежа в систему, 2 - местное время проведения платежа

Таблица 47: Параметры XML-документа в HTTP-запросе

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 48: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >
<!ELEMENT header ( time, point, akey, newmenu? )>
<!ELEMENT operation ( err, report?, msg? )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT newmenu EMPTY>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT report ( #PCDATA )>
<!ELEMENT msg ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

номер точки

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


тег для терминалов информирующий об обновлении меню (игнорировать)

err

Int

ошибка во время приема (0 — успех, 1 — ошибка)

report

string, по указанному формату

реестр платежей (Формат: номер операции(идентификатор в БД Quickpay); услуга(название или id, если ПУ предоставляет несколько сервисов на оплату); номер счета; сумма транзакции (от Quickpay); сумма переданная на счет абоненту; время приема транзакции (от Quickpay); время проведения транзакции (на стороне Quickpay); время проведения транзакции (на стороне ПУ));

msg

string

коментарий

Таблица 49: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 50: Атрибуты тега operation XML-документа ответа от сервера

Пример успешного ответа:

<root>
   <header>
       <time>2013-03-17 15:06:11</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>0</err>
       <report>51464965;110;05032451;12;12;2013-05-22 06:28:53;2013-05-22 07:59:38;
                51464966;110;05032451;15;15;2013-05-22 07:28:53;2013-05-22 08:59:38;
       </report>
   </operation>
</root>

Пример ответа с ошибкой:

<root>
   <header>
       <time>2013-03-17 15:06:11</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>1</err>
       <msg>Ошибка</msg>
   </operation>
</root>

Запрос для получения конфигурационного файла

Пример шаблона для запроса получения подробного отчета за день:

http://SERV:PORT/index.php?act=get&srv=config&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id='2'><service>config</service></operation> </root>

Параметр

Значение

Описание

act

get

тип запроса

srv

config

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 51: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

Таблица 52: Параметры XML-документа в HTTP-запросе (config)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 53: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, config?, msg? )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT msg ( #PCDATA )>
<!ELEMENT config ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

msg

string

описание ошибки(может отсутствовать)

config

string

xml документ с конфигурациями сервисов

Таблица 54: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 55: Атрибуты тега operation XML-документа ответа от сервера

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

<root>
<header>
 <time>TIME</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/>
 <newsetting/>
</header>
 <operation id="">
 <err>0</err>
 <msg>OK</msg>
 <config>
<root><flash><valid_numbers></valid_numbers><input_fields></input_fields></flash><st><ignore><verify></verify></ignore></st></root>
 </config>
</operation>
</root>

Запрос для получения отчета за период в разрезе сервисов

Пример шаблона для получения отчета за период в разрезе сервисов:

http://SERV:PORT/index.php?act=get&srv=mreport&xml=<root><header><time>2013-05-30</time><point>POINT</point><skey>SKEY</skey></header><operation id='2'> <service>mreport</service> <date><period>PERIOD</period><begin>BEGIN</begin><end>END</end></date><report_type>0</report_type><timezone>TIMEZONE</timezone></operation> </root>

Параметр

Значение

Описание

act

get

тип запроса

srv

mreport

тип сервиса

xml

xml-документ

XML документ запроса

Таблица 60: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service, date, report_type, timezone? )>
<!ELEMENT date ( period, begin, end)>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
<!ELEMENT report_type ( #PCDATA )>
<!ELEMENT period ( #PCDATA )>
<!ELEMENT begin ( #PCDATA )>
<!ELEMENT end ( #PCDATA )>
<!ELEMENT timezone ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

report_type

int

тип запрашиваемого отчета, в данном случае равен «3».

begin

string, по указанному формату

время с которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

end

string, по указанному формату

время до которого будет формироваться отчет (Формат: YYYY-mm-dd, Пример: 2013-05-06)

period

int

период в часах, поиск осуществляется от текущего времени минус период (если указан период то теги begin и end не учитываются)

timezone

int

флаг обработки запроса по времени дилера( 0 — обработка идет по времени сервера, 1 — обработка идет по времени дилера)

Таблица 61: Параметры XML-документа в HTTP-запросе (mreport)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 62: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, diler, services )>
<!ELEMENT services ( service )>
<!ELEMENT service ( id, name, count_payments, total_sum, real_pay_sum )>
<!ATTLIST operation id ID #REQUIRED>
<!ATTLIST services count CDATA #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT diler ( #PCDATA )>
<!ELEMENT name ( #PCDATA )>
<!ELEMENT id ( #PCDATA )>
<!ELEMENT count_payments ( #PCDATA )>
<!ELEMENT total_sum ( #PCDATA )>
<!ELEMENT real_pay_sum ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

diler

string

название дилера

name

string

название сервиса

id

int

идентификатор сервиса на стороне Quickpay

count_payments

int

количество платежей по сервису

total_sum

double

сумма реально внесенная клиентами по сервису

real_pay_sum

double

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

Таблица 63: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица 64: Атрибуты тега operation XML-документа ответа от сервера

Атрибут

Тип

Описание

count

long

количество тегов service в теле тега services

Таблица 65: Атрибуты тега services XML-документа ответа от сервера

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

<root>
<header>
 <time>TIME</time>
 <point>POINT</point>
 <akey>AKEY</akey>
 <newmenu/><newsetting/>
</header>
<operation id="">
 <err>0</err>
 <diler>DILER</diler>
 <services count="1">
  <service>
   <id>ID</id>
   <name>NAME</name>
   <count_payments>COUNT_PAYMENT</count_payments>
   <total_sum>TOTAL_SUM</total_sum>
   <real_pay_sum>REAL_PAY_SUM</real_pay_sum>
  </service>
 </services>
</operation>
</root>

Запрос для получения информации по доступным сервисам

Запрос для получения информации по доступным сервисам дилера возвращает полный список сервисов по которым возможна оплата на данный момент. Так же в ответе присутствует минимальный набор информации по сервису.

Пример шаблона для запроса получения информации по доступным для дилера сервисам:

http://SERV:PORT/index.php?act=get&srv=products&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>products</service></operation></root>

Параметр

Значение

Описание

act

get

тип запроса

srv

products

тип сервиса

xml

xml-документ

XML документ запроса

Таблица: Параметры HTTP запроса

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, skey )>
<!ELEMENT operation ( service )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT skey ( #PCDATA )>
<!ELEMENT service ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

skey

string

ключ на сервер (для валидации запроса на сервер)

service

string

тип сервиса (как в параметре srv)

Таблица: Параметры XML-документа в HTTP-запросе (products)

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
<!ELEMENT root ( header, operation ) >

<!ELEMENT header ( time, point, akey, newmenu?, newsetting? )>
<!ELEMENT operation ( err, msg?, services? )>
<!ELEMENT services ( service? )>
<!ELEMENT service ( id, name, mask, chars, nominals, minpay, maxpay, max_comission, transaction_type )>
<!ATTLIST operation id ID #REQUIRED>
<!ELEMENT time ( #PCDATA )>
<!ELEMENT point ( #PCDATA )>
<!ELEMENT akey ( #PCDATA )>
<!ELEMENT err ( #PCDATA )>
<!ELEMENT msg ( #PCDATA )>
<!ELEMENT id ( #PCDATA )>
<!ELEMENT name ( #PCDATA )>
<!ELEMENT mask ( #PCDATA )>
<!ELEMENT chars ( #PCDATA )>
<!ELEMENT nominals ( #PCDATA )>
<!ELEMENT minpay ( #PCDATA )>
<!ELEMENT maxpay ( #PCDATA )>
<!ELEMENT max_comission ( #PCDATA )>
<!ELEMENT transaction_type ( #PCDATA )>
]>


Поле

Тип

Описание

time

string, по указанному формату

время ответа (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

newsetting


игнорировать

err

int

код ошибки

msg

string

описание ошибки(может отсутствовать)

id

string

идентификатор сервиса в системе QuickPay

name

string

название сервиса

mask

string

маска идентификатора сервиса

chars

string

количество символов в идентификаторе сервиса

nominals

string

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

minpay

string

минимальный платеж по сервису

maxpay

string

максимальный платеж по сервису

max_comission

string

максимальная комиссия по сервису

transaction_type

string

тип оплаты сервиса

Таблица: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

уникальный идентификатор запроса

Таблица: Атрибуты тега operation XML-документа ответа от сервера

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

<root>
   <header>
       <time>2014-05-27 11:28:57</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newsetting/>
   </header>
   <operation id="">
       <err>0</err>
       <msg>OK</msg>
       <services>
           <service>
               <id>1</id>
               <name>ATT GoPhone</name>
               <mask>XXX-XXX-XXXX</mask>
               <chars>10</chars>
               <nominals/>
               <minpay>15</minpay>
               <maxpay>450</maxpay>
               <max_comission/>
               <transaction_type>TopUp</transaction_type>
           </service>
       </services>
   </operation>
</root>

Запрос отмены платежа

Пример шаблона для запроса отмены платежа:

http://SERVER:PORT/index.php?act=cancel&srv=cancel&xml=<root><header><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>cancel</service></operation></root>

Параметр xml представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( time, point, skey )>
   <!ELEMENT operation ( service )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT skey ( #PCDATA )>
   <!ELEMENT service ( #PCDATA )>
]>

Поле

Тип

Описание

time

string, по указанному формату

Время приема (Формат: YYYY-mm-dd HH:MM:SS, Пример: 2011-03-03 09:36:26)

point

int

Номер точки через которую будут проводиться платежи

skey

string

Ключ на сервер (для валидации запроса на сервер)

service

string

cancel

Таблица 1: Параметры XML-документа в HTTP-запросе (cancel)

Атрибут

Тип

Описание

id

long

Уникальный идентификатор операции

Таблица 2: Атрибуты тэга operation XML-документа в HTTP-запросе

Ответ от сервера представляет собой XML-документ, соответствующий шаблону:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root [
   <!ELEMENT root ( header, operation ) >
   <!ELEMENT header ( point, akey, newmenu? )>
   <!ELEMENT operation ( err, msg )>
   <!ATTLIST operation id ID #REQUIRED>
   <!ELEMENT point ( #PCDATA )>
   <!ELEMENT akey ( #PCDATA )>
   <!ELEMENT newmenu EMPTY>
   <!ELEMENT err ( #PCDATA )>
   <!ELEMENT msg ( #PCDATA )>
]>

Поле

Тип

Описание

point

int

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

akey

string

ключ на аппарат (для валидации ответа от сервера)

newmenu


игнорировать

err

int

код ошибки

msg

string

комментарий

Таблица 3: Параметры XML-документа ответа от сервера

Атрибут

Тип

Описание

id

long

Уникальный идентификатор платежа, копия данных из запроса

Таблица 19: Атрибуты тега operation XML-документа ответа от сервера


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

<root>
   <header>
       <time>2011-03-17 15:01:30</time>
       <point>POINT</point>
       <akey>AKEY</akey>
       <newmenu/>
   </header>
   <operation id="1">
       <err>-600</err>
       <msg>Ok</msg>
   </operation>
</root>

Описание кодов ошибок при запросе отмены платежа

Код ошибки

Описание ошибки

Фатальность

-600

Платеж успешно отменен

1

-601

Невозможно отменить платеж

1

-602

Ошибка отмены платежа со стороны поставщика услуг, для уточнения возможности отмены платежа свяжитесь с менеджером компании QuickPay.

1

-603

Истек период отмены платежа

1

-24

Техническая ошибка

1

-7

Неверный идентификатор платежа

1

1

Повторите запрос позднее

0

Запрос меню

Запрос меню работает при сформированном меню для точки.

Пример шаблона для запроса:

http://SERVER:PORT/index.php?act=menu&srv=0&xml=<root><header><time>2013-05-29 0:9:9</time><point>65</point><skey>xxx</skey></header><operation><service>0</service></operation></root>

Ответ:

<root>
<header><time>2013-05-29 00:09:40</time><point>65</point><akey>yyy</akey><newsetting/></header>
<err>0</err>
<operation id="" id_dealer="3" id_state="1" salestax="0;;0-999998:2:6" salestax_type="10">
<i name="SIMPLE MOBILE (prepaid)" name_lang2="SIMPLE MOBILE (prepago)" name_lang1="SIMPLE MOBILE (prepaid)"  sid="1001" src="picts/simple_mobile.swf" src_small="picts/simple_mobile_small.swf"
stid="universal.swf"  
title="SIMPLE MOBILE Refill" title_lang1="SIMPLE MOBILE Refill" title_lang2="SIMPLE MOBILE Refill"  disable="0"  
htext="Choose your product" htext_lang1="Choose your product" htext_lang2="Elija su producto"  
comm="0;;0-9:0:0.5;9-19:0:1;19-29:0:1.5;29-39:0:2;39-49:0:2.5;49-59:0:3;59-69:0:3;69-79:0:3.5;79-89:0:4;89-99:0:4.5;99-149:0:5;149-249:0:6;249-499:0:8;499-999998:0:9"
ctype="10" maxpay="60" minpay="10" con="No CASH change provided in Quickpay Machine" con_lang2="Máquina QuickPay no da CAMBIO" con_lang1="No CASH change provided in Quickpay Machine" ></i>
<i name="Prepaid Wireless" name_lang2="Prepaid Wireless" name_lang1="Prepaid Wireless"  sid="1021" src="" src_small=""
stid=""  
title="Prepaid Wireless" title_lang1="Prepaid Wireless" title_lang2="Prepaid Wireless"  disable="0"  htext="Prepaid Wireless" htext_lang1="Prepaid Wireless" htext_lang2="Prepaid Wireless"
comm="0;;0-999998:2:0"
ctype="10" maxpay="100" minpay="0"  is_new="1"></i>
</operation>
</root>

Формат меню

i - пункт или подменю
Атрибуты:
comm - комиссия
trans_pay - плата за транзакцию с плательщика

Отладочные ошибки протокола

Данные ошибки возвращает сервер если запрос не соответствует протоколу или содержит ошибки в данных.

Код ошибки

Описание

Действия для устранения

FA90

Не настроен сервис

Не корректный идентификатор сервиса, уточнить идентификатор у ответственного.

FA91

Не известный сервис

Не корректный тип запроса, проверить параметр «act».

FA92

Ошибка на уровне проверок при приеме данных

Проверить все параметры запроса и XML-документа убедиться в корректности данных.

Проверить настройки для дилера в админ зоне(доступность сервиса для дилера, доступность проведения сервиса по серверу).

FA93

Ошибка в заголовке XML-запроса (проверьте данные внутри тега «header»)

Проверить данные внутри тега «header», убедиться в корректности номера точки(тег «point») и ключа(тег «skey»).

Убедиться что баланс дилера положительный.

FA94

Ошибка в запросе - не корректный XML()

Проверить целостность XML-документа.

FA95

Исключение при обработке запроса

Проверить корректность запроса. Обратиться к ответственному.

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

Применение сертификатов для API точки

Для API точки сертификаты можно получить в формате p12 или через CSR запрос.

Если Вы получили сертификат в формате p12, то преобразовать для использования в ПО можно следующим образом:

openssl pkcs12 -in cert.p12 -nodes > cert.pem

При этом файл cert.pem будет содержать и сертификат, и приватный ключ в себе.

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

Пример класса для использования сертификатов с cURL на PHP:

QuickpayClient.php:

<?php
// Если ключ и сертификат в одном файле:
define('CERT', '/path/cert.pem');
define('KEY', '/path/cert.pem');

// Если ключ и сертификат в разных файлах:
define('CERT', '/path/cert.pem');
define('KEY', '/path/cert.key');
define('PASSWORD', '');//Пароль, если ключ зашифрован

class QuickpayClient {

   public $url;
   public $ch;
   public $post;
   function sendHTTP($req) {
       $url = $this->url;
       // Если отправляем данные методом POST
       if ($this->post) {
           curl_setopt($this->ch,CURLOPT_POSTFIELDS,$req);
        } else {
           $url .= $req;
        }
       $this->ch = curl_init($url);
       $opts = array(
            CURLOPT_HEADER => 0,
            CURLOPT_RETURNTRANSFER => 1,
            CURLOPT_SSLVERSION => 3,
           //CURLOPT_SSLCERTPASSWD => PASSWORD, // Если ключ зашифрован паролем
           CURLOPT_SSLKEY => KEY,
            CURLOPT_SSLCERT => CERT,
            CURLOPT_SSL_VERIFYPEER => false,
            CURLOPT_SSL_VERIFYHOST => false,
            CURLOPT_TIMEOUT => 60,
        );
       foreach($opts as $key=>$value) curl_setopt($this->ch, $key, $value);
       $res = curl_exec($this->ch);
       $err = curl_error($this->ch);
       $info = curl_getinfo($this->ch);
       if ( $err !== '') {
           $msg = 'HTTP status code ' . $info['http_code'] .'. Connection error. Cause: '.$err;
           echo "ERROR: ".$msg."\n";
           curl_close($this->ch);
           throw new Exception($msg);
        }
       if ($info['http_code'] != 200) {
           $msg = 'HTTP status code ' . $info['http_code'];
           echo "ERROR: ".$msg;
           throw new Exception($msg);
        }
       echo "RESPONSE: ".$res."\n";
       curl_close($this->ch);
       return $res;
    }
}

Информация о балансе

Пример запроса баланса с использованием класса "QuickpayClient".

<?php
require_once ('./QuickpayClient.php');
function balans($point, $skey, $id_operation) {
   $xml = '<root>'.
           '<header>'.
               '<point>'. $point .'</point>'.
               '<skey>'.  $skey .'</skey>'.
           '</header>'.
           '<operation id="'.$id_operation.'">'.
               '<service>balance</service>'.
           '</operation>'.
       '</root>';
   $request_parameters = array(
       'srv' => 'balance',
       'act' => 'get',
       'xml' => $xml,
    );
   $request = '?' . http_build_query($request_parameters);
   return $request;
}
$point = 'POINT';// Номер точки
$skey = 'SKEY';// Пароль
$id_operation = 'ID';// Уникальный идентификатор запроса
$request_balance = balans($point, $skey, $id_operation);
$q = new QuickpayClient();
$q->url = 'https://XXX.XXX.XXX.XXX:AAAA';
$q->post = false;
echo "RESULT: ".$q->sendHTTP($request_balance)."\n";

Проверка платежа

Пример запроса проверки платежа с использованием класса "QuickpayClient".

<?php
require_once ('./QuickpayClient.php');
function verifyPayment($oper, $point, $skey) {
   $xml = '<root>'.
           '<header>'.
               '<time>'.$oper['time_app'].'</time>'.
               '<point>'.$point.'</point>'.
               '<skey>'.$skey.'</skey>'.
           '</header>'.
           '<operation id="'.$oper['id'].'">'.
               '<service>'.$oper['id_service'].'</service>'.
               '<account>'.
                   '<value>'.$oper['identifier'].'</value>'.
               '</account>'.
           '</operation>'.
       '</root>';
   $req = array(
       'act' => 'verify',
       'srv' => $oper['id_service'],
       'rnd' => '0.322031983174384',
       'xml' => $xml,
    );
   return '?' . http_build_query($req);
}
$point = 'POINT';// Номер точки
$skey = 'SKEY';// Пароль
$oper = array(
  'time_app'     => 'X', // Местное время проведения платежа (формат "Y-m-d H:i:s" ,2012-10-03 17:14:10)
  'id'           => 'X', // Уникальный идентификатор платежа
  'id_service'   => 'X', // Уникальный идентификатор сервиса в системе Quickpay
  'identifier'   => 'X', // Номер, характеризующий платеж (например, номер телефона)
);
$request_verify_payment = verifyPayment($oper,$point,$skey);
$q = new QuickpayClient();
$q->url = 'https://XXX.XXX.XXX.XXX:AAAA';
$q->post = false;
echo "RESULT: ".$q->sendHTTP($request_verify_payment)."\n";

Добавление платежа

Пример добавления платежа с использованием класса "QuickpayClient".

<?php
require_once ('./QuickpayClient.php');
function addPayment($oper, $point, $skey) {
   $xml = '<root>'.
           '<header>'.
               '<time>'.$oper['time_app'].'</time>'.
               '<point>'.$point.'</point>'.
               '<skey>'.$skey.'</skey>'.
           '</header>'.
           '<operation id="'.$oper['id'].'">'.
               '<service>'.$oper['id_service'].'</service>'.
               '<account>'.
                   '<value>'.$oper['identifier'].'</value>'.
               '</account>'.
               '<total>'.$oper['total_sum'].'</total>'.
           '</operation>'.
       '</root>';
   $req = array(
       'act' => 'add',
       'srv' => $oper['id_service'],
       'rnd' => '0.322031983174384',
       'xml' => $xml,
    );
   return '?' . http_build_query($req);
}
$point = 'POINT';// Номер точки
$skey = 'SKEY';// Пароль
$oper = array(
   'time_app'     => 'X', // Местное время проведения платежа (формат "Y-m-d H:i:s" ,2012-10-03 17:14:10)
   'id'           => 'X', // Уникальный идентификатор платежа
   'id_service'   => 'X', // Уникальный идентификатор сервиса в системе Quickpay
   'identifier'   => 'X', // Номер, характеризующий платеж (например, номер телефона)
   'total_sum'    => 'X', // Cумма, внесенная плательщиком
);
$request_add_payment = addPayment($oper,$point,$skey);
$q = new QuickpayClient();
$q->url = 'https://XXX.XXX.XXX.XXX:AAAA';
$q->post = false;
echo "RESULT: ".$q->sendHTTP($request_add_payment)."\n";

Статус платежа

Пример запроса статуса платежа с использованием класса "QuickpayClient".

<?php
require_once ('./QuickpayClient.php');
function statusPayment($oper, $point, $skey) {
   $xml = '<root>'.
           '<header>'.
               '<time>'.$oper['time_app'].'</time>'.
               '<point>'.$point.'</point>'.
               '<skey>'.$skey.'</skey>'.
           '</header>'.
           '<operation id="'.$oper['id'].'">'.
               '<service>'.$oper['id_service'].'</service>'.
           '</operation>'.
       '</root>';
   $req = array(
       'act' => 'status',
       'srv' => $oper['id_service'],
       'rnd' => '0.322031983174384',
       'xml' => $xml,
    );
   return '?' . http_build_query($req);
}
$point = 'POINT';// Номер точки
$skey = 'SKEY';// Пароль
$oper = array(
   'time_app'     => 'X', // Местное время проведения платежа (формат "Y-m-d H:i:s" ,2012-10-03 17:14:10)
   'id'           => 'X', // Уникальный идентификатор платежа
   'id_service'   => 'X', // Уникальный идентификатор сервиса в системе Quickpay
);
$request_status_payment = statusPayment($oper,$point,$skey);
$q = new QuickpayClient();
$q->url = 'https://XXX.XXX.XXX.XXX:AAAA';
$q->post = false;
echo "RESULT: ".$q->sendHTTP($request_status_payment)."\n";

Часто задаваемые вопросы (Frequently Asked Question)

Что нужно сделать перед тестированием протокола

Вопросы ответы

  • Как использовать тестовый режим протокола?

Для использования тестового режима протокола необходимо в тег "operation" добавить аттрибут "mode" со значением "TEST".  Подробное описание находится в запросе добавления платежа в систему.

  • Тестовый режим протокола необходимо использовать для всех типов запросов?

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

  • Гарантирует ли запрос проверки реквизитов существование номера(счета)?

Нет, запрос проверки реквизитов простого платежа не дает гарантии существования номер телефона(счета).

  • Почему при запросе проверки реквизитов простого платежа появляется ошибка вида: <operation id="1"><err mmenu="1" delay="2">1</err><msg>Сумма меньше минимальной</msg></operation>?

Для проверки реквизитов простого платежа в US  системе необходимо добавить тег "ls" со значением суммы платежа.

Пример: http://SERVER:PORT/index.php?act=verify&srv=SERVICE&xml=<root><header><time>TIME</time><point>POINT</point><skey>SKEY</skey></header><operation id="OPERATION_ID"><service>SERVICE</service><account><value>PHONE</value><ls>SUM</ls></account></operation></root>

  • При проведении платежей через API точку не отправляются СМС, как настроить СМС при отправке через API точку? 

Стандартный механизм отправки СМС сообщений не работает для API точек. Для отправки СМС есть сервис SMS Sender(ID:100) в API протоколе.  Описание работы с сервисом находится в запросе добавления платежа в US системе

  • Как можно получить ПИН код для сервисов с покупкой ПИН кодов через 10 минут после оплаты?

ПИН код можно получить в любое время после совершения платежа при условии что платеж был проведен,  запросом проверки статуса платежа в US системе

  • Как можно получить список доступных для оплаты сервисов?
  • Установлена ли маска ввода по сервису и как ее получить?
  • Как получить минимальную и максимальную сумму платежа по сервису?

Ответы на эти вопросы можно получить выполнив запрос получения информации по сервисам.

  • Почему при запросе на добавление платежа в ответе ошибка: " Аппарат находится на сервисном обслуживании #FA92 ", хотя до этого платежи принимались без ошибок?

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

Тэги: XML API ошибки
Создал Administrator 2012/10/19 12:24

This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 4.1-milestone-1 - Documentation