Вы находитесь на странице: 1из 20

API ukrbuy.com

v.1.2 от 18.10.2010 http://ukrbuy.com/partner/

Оглавление

1. Общее описание

 

2

1.1. Общее описание взаимодействия

2

1.2. Параметры взаимодействия

2

1.3. Аутентификация

 

3

1.4. Форматы параметров

3

1.5. Параметры ответа Системы на команду

4

2. Команды

 

4

2.1.

Команда

Availiable

4

2.3.

Команда

Validate

5

2.4.

Команда

Operation

6

Operation с ResultCode = 413 (команда OperationData НЕ нужна)

7

Operation с ResultCode = 422 (команда OperationData нужна)

8

2.5. Команда OperationData

12

2.6. Команда

Check

14

2.7. Команда Catalog

16

3. Коды ответа Системы (ReturnCode)

18

4. Результаты выполнения команд (ResultCode)

19

1. Общее описание

1.1. Общее описание взаимодействия

В данном документе применяются следующие термины:

– Контрактор с помощью данного API. Контрактор – агент, реализовавший взаимодействие с Системой на своем сайте. Транзакция – платеж в пользу провайдера и связанные с ним процессы обмена информацией. Каталог – перечень провайдеров, подключенных к Системе, в пользу которых осуществляется прием платежей Сервис – конкретная услуга из Каталога. Каждый провайдер может предоставлять несколько сервисов. Клиент – плательщик, инициирующий оплату в пользу провайдера с сайта Контрактора. Реквизиты клиента – набор сведений о счете клиента у провайдера, которые клиент указывает на сайте Контрактора перед совершением платежа (номер телефона, номер договора и т.п.).

Система

взаимодействует

программная

система

на

сервере

ukrbuy.com,

с

которой

С помощью данного API Контрактор на своем сайте организует прием платежей в пользу провайдеров, подключенных к Системе.

В процессе технического взаимодействия Контрактор получает от Системы html-форму для

перенаправления клиента на WebMoney Merchant для оплаты. Клиент делает платеж (в WMU) в пользу выбранного провайдера через WebMoney Merchant со своего кошелька напрямую на кошелек Системы. Кошелек Контрактора в этом финансовом потоке не участвует, таким образом, Контрактор может не заботиться о внесении гарантийного фонда, наличии WMU на собственном кошельке и т.п.

Статистика

Контрактор получает агентское вознаграждение от каждого платежа согласно тарифам,

.

продаж

отображается

в

кабинете

Контрактора

на

опубликованным на http://ukrbuy.com/partner/.

В процессе взаимодействия по данному API Контрактор передаѐт в Систему XML-команды и

получает от Системы ответы на эти команды. Контрактор может передавать такие команды:

Получение Каталога доступных Сервисов (Catalog); Проверка доступности Сервиса (Availiable); Проверка валидности введенных параметров Транзакции (Validate); Создание и проведение Транзакции (Operation); Передача дополнительных параметров Транзакции (OperationData ); Проверка состояния Транзакции в Системе (Check);

Avaliable Validate Operation Check OperationData
Avaliable
Validate
Operation
Check
OperationData

1.2. Параметры взаимодействия

Контрактор и Система производят обмен сообщениями по протоколу HTTP методом POST в формате text/xml (XML-формат). Используемая кодировка - "UTF-8". При отправке запроса Контрактор сообщает об используемом формате сообщения и кодировке в HTTP-заголовке "Content-type":

Content-Type: text/xml; charset=utf-8

Все запросы должны отправляться на адрес http://ukrbuy.com/api.php

В случае если обработка запроса Системой завершилась успешно, ответ Системы содержит стандартный код успешной обработки HTTP-запроса "200 OK", а в теле XML-ответа содержится:

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage>

Внимание! Ситуацию, в которой ответ Системы не получен или HTTP-код ответа Системы принимает значение, отличное от "200 OK", нельзя интерпретировать как отказ Системы выполнить запрос (команду). После разрешения проблем требуется повторить запрос.

Если в процессе приема или обработки запроса возникли ошибки, тело XML-сообщения содержит ReturnCode со значением, отличным от 0, а в ReturnMessage содержится описание ошибки. Описание кодов ошибок приведено в разделе 3.

1.3. Аутентификация

При передаче любой команды в Систему Контрактор должен пройти аутентификацию путем передачи следующих HTTP-заголовков:

X-GC-Auth-Point – содержит номер точки Контрактора ( его можно посмотреть на – содержит номер точки Контрактора (его можно посмотреть на странице http://ukrbuy.com/partner/interfaces/description);

X-GC-Auth-Pass – содержит пароль Контрактора в кодировке Base64 ( пароль можно – содержит пароль Контрактора в кодировке Base64 (пароль можно посмотреть на странице http://ukrbuy.com/partner/interfaces/description).

Пример заголовка для аутентификации:

X-GC-Auth-Point: 1 X-GC-Auth-Pass: cGFzc3dvc9Q=

Ответ Системы всегда содержит HTTP-заголовок X-GC-Auth-Sign с ЭЦП ответа в кодировке Base64. Цифровая подпись формируется с помощью алгоритма SHA1 по строке конкатенации (склейки) значения тела HTTP-запроса и пароля. Пример на языке PHP:

sha1($response . $password);

Пример заголовка с ЭЦП Системы:

X-GC-Auth-Sign: F4kH/V7rVJu/BubysUe7iNsFNU+qSndmPecJfSZw/LrfJYxraigvsXUxHbts0jqYtbAahm

8s4rFjNZF5Wu35k0/XxyFs5jCLKAvbXcZiJf8pWnauuM3hyw7mmOb6Qn/w+DVxf2fiLL3v

d3eXN6NdBEZDk/FnYv5ItJ2+N9T0bO8=

Проверять или нет ЭЦП в ответах Системы – Контрактор решает самостоятельно.

1.4. Форматы параметров

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

INT - строка цифр, содержащая целое неотрицательное число, не большее строка цифр, содержащая целое неотрицательное число, не большее 2^16, например, "12345";
не большее 2^16, например, "12345"; VARCHAR(n) - строка произвольных VARCHAR(n) - строка произвольных символов, длиной не более n, например, "qwerty"; MONEY - строка, содержащая неотрицательное число фиксированной точности от 0 до 4 знаков в дробной части с разделителем точка, например, "1.0000", "0.01";

VOLUME - строка, содержащая значение типа MONEY с постфиксом “V” или “A”, строка, содержащая значение типа MONEY с постфиксом “V” или “A”, например, "12345.012V", "24A";

PARAMS – строка, содержащая значения реквизитов клиента , разделенных – строка, содержащая значения реквизитов клиента, разделенных символом “;”. Реквизиты в PARAMS всегда должны быть перечислены точно в той последовательности, в которой они представлены в описании Сервиса в Каталоге (команда Catalog).

1.5. Параметры ответа Системы на команду

При запросе всех команд, кроме команды получения Каталога (Catalog) в теле ответа содержатся следующие параметры:

ResultCode – Код результата выполнения команды; ResultCode ResultMessage – Описание результата выполнения команды; ResultData – ResultMessage – Описание результата выполнения команды; ResultData – Данные ответа, если таковые есть.

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

2. Команды

2.1. Команда Availiable

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

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

Название

Тип

Значение

Пример

ServiceId

INT

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

1

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

<AvailableRequest> <Commands> <AvailableRequestCommand>

<ServiceId>1</ServiceId>

</AvailableRequestCommand>

</Commands>

</AvailableRequest>

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

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <AvailableResponseCommand>

<ResultCode>0</ResultCode>

<ResultMessage>Команда выполнена успешно</ResultMessage> </AvailableResponseCommand> </Commands> </Response>

2.3. Команда Validate

Данная команда предназначена для проверки корректности введенных параметров платежа (реквизитов клиента у провайдера – номер телефона, номер договора и т.п., а также суммы платежа) БЕЗ создания Транзакции и проведения платежа.

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

Название

Тип

Значение

Пример

ServiceId

INT

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

1

Volume

VOLUME

Объем платежа в гривнах или единицах провайдера

1, 1V, 1A

Params

PARAMS

Реквизиты счета клиента

380913016166

Параметры данных ответа:

Название

Тип

Значение

Пример

Calculate\Amount

MONEY

Объем платежа в единицах провайдера

1

Calculate\Value

MONEY

Объем платежа в гривнах

1

Calculate\AgentFee

MONEY

Агентское вознаграждение, которое получит Контрактор от платежа (в WMU)

0.012

Calculate\Price

MONEY

Общая сумма платежа в гривнах (WMU) с учетом «внешней» комиссии

1.02

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

<ValidateRequest> <Commands> <ValidateRequestCommand>

<ServiceId>1</ServiceId>

<Volume>10A</Volume>

<Params>380913016166</Params>

</ValidateRequestCommand>

</Commands>

</ValidateRequest>

В Volume может передаваться объем платежа в единицах провайдера (тогда нужно добавлять постфикс “A”, например: 100A), либо в гривнах (тогда нужно добавлять постфикс “V”, например: 100V, либо вообще не добавлять постфикс, например: 100).

Предположим, пополнение лицевого счета у провайдера «Одуванчик» производится в «юнитах» при стоимости одного «юнита» 8 гривен. В таком случае, если клиент желает пополнить счет на 10 «юнитов», нужно передать в Volume 10A, либо 80V, либо 80.

Реквизиты клиента указываются в соответствии с требованиями, которые предъявляются по данному Сервису (получить можно командой Catalog). Реквизиты должны быть перечислены

в Params через разделитель (“;”) точно в той последовательности, в которой они представлены

в описании Сервиса в Каталоге (команда Catalog).

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

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <ValidateResponseCommand>

<ResultCode>0</ResultCode>

<ResultMessage>Команда выполнена успешно</ResultMessage> <ResultData> <Calculate>

<Amount>10</Amount>

<Value>80</Value>

<AgentFee>0.98</AgentFee>

<Price>81.6</Price>

</Calculate>

</ResultData>

</ValidateResponseCommand>

</Commands>

</Response>

В примере, который мы привели выше (у провайдера «юниты» стоимостью 10 гривен каждый и передано в запросе Volume=10A), Система вернет: Amount=10 («юнитов»), Value=80 (гривен).

Значение Price Система рассчитывает в гривнах, в зависимости от того, есть ли внешняя комиссия по данному Сервису (внешняя комиссия – это комиссия, взимаемая с клиента сверх его суммы платежа). Предположим, по провайдеру «Одуванчик» установлена внешняя комиссия 2%. В таком случае при объеме платежа 10 юнитов (80 гривен), клиент должен будет заплатить 81.6 WMU.

На практике всѐ не так сложно. Почти все провайдеры ведут лицевые счета в гривнах (а не в условных единицах). Внешняя комиссия тоже почти всегда отсутствует. Таким образом, значения Amount, Value и Price почти всегда будут одинаковыми.

2.4. Команда Operation

Данная команда предназначена для создания Транзакции в Системе с последующим перенаправлением клиента на WebMoney Merchant для оплаты.

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

Название

Тип

Значение

Пример

OperationId

VARCHAR(64)

Идентификатор Транзакции, назначается Контрактором

123_250509

ServiceId

INT

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

1

Volume

VOLUME

Объем платежа в гривнах или единицах провайдера

1, 1V, 1A

Params

PARAMS

Реквизиты счета клиента

380913016166

TerminalId

INT

Номер терминала Контрактора

122

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

<OperationRequest>

<Commands>

<OperationRequestCommand>

<ServiceId>1</ServiceId>

<OperationId>125206188472552900</OperationId>

<Volume>1</Volume>

<Params>380913016166</Params>

<TerminalId>122</TerminalId>

</OperationRequestCommand>

</Commands>

</OperationRequest>

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

Обычно OperationId можно назначать, используя значение системного времени. Пример на PHP:

<?

function createOperationId()

{

list($usec, $sec) = explode(" ", substr(microtime(), 2)); return $sec . $usec;

?>

}

Формат OperationId - строка длиной до 64 символов (включительно). Примеры:

символов (включительно). Примеры: "1112" - простой счетчик.

"1112" - простой счетчик. "1113_1228" - простой счетчик с привязкой к дате. "1114_12282359" - простой счетчик с привязкой к дате и времени.

Реквизиты клиента указываются в соответствии с требованиями, которые предъявляются по данному Сервису (получить можно командой Catalog). Реквизиты должны быть перечислены

в Params через разделитель (“;”) точно в той последовательности, в которой они представлены

в описании Сервиса в Каталоге (команда Catalog).

Параметр TerminalId служит только для того, чтобы Контрактор имел возможность указать, от имени какого терминала (сайта) проводится платеж. Каждый платеж закрепляется за определенным терминалом (сайтом) Контрактора, что даѐт Контрактору возможность просматривать статистику (например, здесь - http://ukrbuy.com/partner/statistic/all) в привязке к разным терминалам. Каждый терминал – это сайт, добавленный Контрактором на странице http://ukrbuy.com/partner/site. Там же можно посмотреть номер терминала (TerminalId).

При получении от Контрактора команды Operation в Системе создается Транзакция. Если в ответе на Operation содержится ResultCode = 413, это означает, что ввод всех необходимых параметров платежа окончен и клиента можно отправлять на оплату. Если в ответе на Operation содержится ResultCode = 422, это означает, что необходимо ввести дополнительные параметры платежа и передать их с помощью команды OperationData.

Operation с ResultCode = 413 (команда OperationData НЕ нужна)

Пример ответа с ResultCode = 413:

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <OperationResponseCommand>

<ResultCode>413</ResultCode>

<ResultMessage>Ожидается оплата операции через мерчант</ResultMessage>

<ResultData> <Forms> <Webmoney> <Action>https://merchant.webmoney.ru/lmi/payment.asp</Action> <Method>POST</Method> <Fields>

<LMI_PAYEE_PURSE>U727440296579</LMI_PAYEE_PURSE>

<LMI_PAYMENT_AMOUNT>5.00</LMI_PAYMENT_AMOUNT>

<LMI_PAYMENT_DESC>Оплата за услуги Vega: Телефония 2450298; (Id:711246) </LMI_PAYMENT_DESC>

<LMI_PAYMENT_NO>711246</LMI_PAYMENT_NO>

</Fields> </Webmoney> </Forms> </ResultData>

<OperationId>1282200481000</OperationId>

</OperationResponseCommand>

</Commands>

</Response>

Как видно из примера, в ответе на команду Operation c ResultCode = 413 Система передает тег Forms с описанием html-формы для перенаправления клиента на WebMoney Merchant для оплаты. Необходимо:

1. обработать содержимое Forms;

2. отобразить клиенту html-форму;

3. перенаправить клиента на WebMoney Merchant для совершения оплаты.

Пример того, как должна быть составлена html-форма для перенаправления клиента на WebMoney Merchant по ответу на Operation, который приведен выше:

<form method="POST" action="https://merchant.webmoney.ru/lmi/payment.asp"> <input type="hidden" name="LMI_PAYMENT_NO" value="711246"> <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="5.00"> <input type="hidden" name="LMI_PAYEE_PURSE" value="U727440290579"> <input type="hidden" name="LMI_SUCCESS_URL" value="http://SITENAME/payment/gc?action=yes"> <input type="hidden" name="LMI_FAIL_URL" value="http://SITENAME/payment/gc/no"> <input type="hidden" name="LMI_PAYMENT_DESC" value="Оплата за услуги Vega: Телефония 2450298; (Id:711246)"> <input type="submit" value="Перейти к оплате" > </form>

Параметры LMI_SUCCESS_URL и LMI_FAIL_URL должны содержать адреса страниц на сайте Контрактора, на которые клиент будет возвращаться с WebMoney Merchant соответственно после успешной, либо неуспешной оплаты. Если эти параметры не будут переданы в html-форме, клиент будет возвращаться на сайт ukrbuy.com.

Если кодировка сайта Котрактора не Windows-1251, то в приведенной форме примечание платежа нужно передавать не в параметре LMI_PAYMENT_DESC, а в параметре LMI_PAYMENT_DESC_BASE64, представив текст примечания в кодировке Base64.

Пример для PHP:

<input type="hidden" name="LMI_PAYMENT_DESC" value="<?php=base64_encode(“Оплата за услуги Vega: Телефония 2450298; (Id:711246)”)?>">

Operation с ResultCode = 422 (команда OperationData нужна)

При оплате в пользу некоторых провайдеров, например, услуг ЖКХ, бывает необходимо заполнить дополнительные параметры (например, показатели счетчиков воды, газа, электричества, сумму долга за предыдущие месяцы и т.п.). В этом случае Operation вернет в ответе ResultCode = 422.

Пример ответа с ResultCode = 422:

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <OperationResponseCommand>

<ResultCode>422</ResultCode>

<ResultMessage>Ожидаются дополнительные параметры платежа</ResultMessage> <ResultData> <WaitData> <Data> <Name>Фамилия</Name> <Type>Info</Type>

<Readonly>1</Readonly>

<Value>КАРПIНА Г. В.</Value> </Data> <Data> <Name>Показания счетчика</Name> <Type>Counter</Type>

<Discount>0.11</Discount>

<PrevCounter>100</PrevCounter>

<Counter>200</Counter>

<Id>10</Id>

</Data> <Data> <Name>Долг</Name> <Type>Info</Type>

<Readonly>1</Readonly>

<Value>200</Value>

</Data> <Data> <Name>Из него оплатить</Name> <Type>FreePayment</Type>

<Readonly>0</Readonly>

<Value>200</Value>

</Data> </WaitData> </ResultData>

<OperationId>128594277776698100</OperationId>

</OperationResponseCommand>

</Commands>

</Response>

Как видно из примера, в ответе на команду Operation c ResultCode = 422 Система передает тег WaitData с описанием html-формы для заполнения дополнительных параметров платежа. Необходимо:

1. обработать содержимое WaitData;

2. отобразить клиенту html-форму;

3. дождаться заполнения клиентом html-формы;

4. передать введенные параметры в Систему командой OperationData.

Таким образом, задача заключается в том, чтобы принять из ответа на Operation XML-пакет, превратить его в HTML, затем заполненную клиентом HTML-форму превратить обратно в XML-пакет и отправить этот пакет в OperationData.

Каждый блок <Data>…</Data> внутри WaitData описывает один или несколько элементов формы. У каждого блока <Data>…</Data> есть поле Type, которое задаѐт порядок отображения этого(-их) элемента(-ов). Ниже представлены возможные значения Data/Type.

Data/Type = Info

Описательный элемент html-формы, который нужно отобразить в html-форме просто для информации, без возможности редактирования (можно в виде обычного текста).

Пример из ответа на Operation:

<Data> <Name>Долг</Name> <Type>Info</Type>

<Readonly>1</Readonly>

<Value>200</Value>

</Data>

Что нужно в данном случае отобразить в html-форме:

Долг: <b>200</b>

Либо так:

Долг <input type=text value="1" readonly>

Значение этого элемента в OperationData можно не передавать.

Data/Type = FreePayment

Этот элемент html-формы должен запрашивать у клиента заполнение произвольных цифр, например, какую сумму долга тот хочет включить в свой платеж.

Пример из ответа на Operation:

<Data> <Name>Из него оплатить</Name> <Type>FreePayment</Type>

<Readonly>0</Readonly>

<Value>200</Value>

</Data>

Что нужно в данном случае отобразить в html-форме:

<input name="Param2Name" value="Из него оплатить" type="hidden"> Из него оплатить: <input type="text" value="200" name="Param2Price">

Обратите внимание, что названия этих 2х полей (name) в html-форме Контрактор назначает на свое усмотрение, однако, рекомендуем делать их схожими, чтобы по этим названиям Контрактор мог автоматически определить, что эти поля относятся к одному и тому же элементу данных и мог передать значения этих полей в OperationData в привязке к одному и тому же элементу данных.

Предположим, клиент изменил в поле html-формы сумму долга, которую он хочет оплатить, с 200 на 150. В таком случае в OperationData нужно передать новое значение:

<Param> <Name>Из него оплатить</Name> <Discount></Discount> <Counter></Counter> <PrevCounter></PrevCounter>

<Price>150</Price>

<Difference></Difference>

</Param>

Data/Type = Counter

Эти элементы html-формы должны запрашивать у клиента заполнение показателей счетчика. При этом каждый счетчик должен содержать такие поля:

тариф ( значение по умолчанию может быть получено из Data/Type/Discount ); (значение по умолчанию может быть получено из Data/Type/Discount); предыдущий показатель счетчика (значение по умолчанию может быть получено из Data/Type/PrevCounter);

текущий показатель счетчика (значение по умолчанию может быть получено из Data/Type/Counter); Data/Type/Counter);

разница между текущим и предыдущим показателем счетчика (нужно рассчитать на стороне сайта Контрактора, например, с помощью javascript); );

стоимость (нужно рассчитать на стороне сайта Контрактора по формуле Тариф*Разница, например, с помощью javascript). ).

Все поля счетчика должны быть доступными к редактированию, кроме поля «Разница».

Пример из ответа на Operation:

<Data> <Type>Counter</Type> <Name>Показания счетчика</Name>

<Discount>0.11</Discount>

<PrevCounter>100</PrevCounter>

<Counter>200</Counter>

<Id>10</Id>

</Data>

Что нужно в данном случае отобразить в html-форме:

<b>Показания счетчика:</b><br>

Тариф <input name="Param0Discount" value="0.11" type="text"><br> Предыдущий показатель <input name="Param0PrevCounter" value="100" type="text"><br> Текущий показатель <input name="Param0Counter" value="200" type="text"><br> Разница <input name="Param0Difference" value="100" readonly type="text"><br> Стоимость <input name="Param0Price" value="11" type="text"><br>

Обратите внимание, что названия полей счетчика (name) в html-форме Контрактор назначает на свое усмотрение, однако рекомендуем делать их схожими, чтобы по этим названиям Контрактор мог автоматически определить, что эти поля относятся к одному и тому же счетчику и мог передать значения этих полей в OperationData в привязке к одному и тому же счетчику.

Предположим, клиент изменил в поле html-формы текущий показатель счетчика с 200 на 220, а также скорректировал тариф с 0.11 на 0.09 (это допускается). В таком случае в OperationData нужно передать новое значение:

<Param> <Name>Показания счетчика</Name>

<Discount>0.09</Discount>

<Counter>220</Counter>

<PrevCounter>100</PrevCounter>

<Difference>120</Difference>

<Price>10.8</Price>

<Id>10</Id>

</Param>

Таким образом, html-форма, составленная по результатам обработки тега WaitData из ответа на команду Operation с ResultCode = 422, будет выглядеть так:

<form method="POST" action="URL на сайте Контрактора"> Фамилия: <b>КАРПIНА Г. В.</b><br> <b>Показания счетчика:</b><br> Тариф <input name="Param0Discount" value="0.11" type="text"><br> Предыдущий показатель <input name="Param0PrevCounter" value="100" type="text"><br>

Текущий показатель <input name="Param0Counter" value="200" type="text"><br> Разница <input name="Param0Difference" value="100" readonly type="text"><br> Стоимость <input name="Param0Price" value="11" type="text"><br> Долг: <b>200</b><br> <input name="Param2Name" value="Из него оплатить" type="hidden"> Из него оплатить: <input type="text" value="200" name="Param2Price"> <input type=submit value="Далее"><br> </form>

2.5. Команда OperationData

Данная команда предназначена для отправки в Систему дополнительных параметров платежа (например, счетчик воды, газа и т.п.) с последующим перенаправлением клиента на WebMoney Merchant для оплаты.

Команду OperationData необходимо применять только в том случае, если в ответе на команду Operation получен ResultCode = 422. Для полного понимания команды OperationData прочтите описание команды Operation.

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

Название

Тип

Значение

Пример

OperationId

VARCHAR(64)

Идентификатор Транзакции, ранее назначенный Контрактором

123_250509

ServiceId

INT

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

1

Volume

VOLUME

Общий объем платежа в гривнах или единицах провайдера (необязателен)

1, 1V, 1A

Params

 

Дополнительные параметры платежа

 

Params/Param/Name

VARCHAR(255)

Название дополнительного параметра, например, счетчика.

 

Params/Param/Discount

MONEY

Тариф на счетчике

0.5

Params/Param/Counter

MONEY

Текущее значение счетчика

 

Params/Param/PrevCounter

MONEY

Предыдущее значение счетчика

 

Params/Param/Difference

MONEY

Оплачиваемое количество единиц счетчика Difference= Counter-PrevCounter

 

Params/Param/Price

MONEY

Сумма, оплачиваемая клиентом в дополнительном параметре, либо цена по счетчику (в большинстве случаев Price=Discount*Difference)

 

Params/Param/Id

INT

Идентификатор счетчика. Передается в случае, если Param/Id присутствовал в ответе на команду Operation для данного счетчика.

 

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

<OperationDataRequest> <Commands> <OperationDataRequestCommand>

<ServiceId>35</ServiceId>

<OperationId>128594277776698100</OperationId>

<Volume>160.8</Volume>

<Params> <Param> <Name>Показания счетчика</Name>

<Discount>0.09</Discount>

<Counter>220</Counter>

<PrevCounter>100</PrevCounter>

<Difference>120</Difference>

<Price>10.8</Price>

<Id>10</Id>

</Param> <Param> <Name>Из него оплатить</Name> <Discount></Discount> <Counter></Counter> <PrevCounter></PrevCounter> <Difference></Difference>

<Price>150</Price>

</Param>

</Params>

</OperationDataRequestCommand>

</Commands>

</OperationDataRequest>

Как именно Контрактор должен формировать блоки <Param>…</Param> в этом запросе – рассматривалось в описании команды Operation (случай с ResultCode = 422).

Если в ответе на OperationData содержится ResultCode = 413, это означает, что ввод всех необходимых параметров платежа окончен, и клиента можно отправлять на оплату. Если в ответе на OperationData содержится ResultCode = 422, это означает, что не все необходимые параметры введены, либо они введены с ошибками. В таком случае необходимо запросить у клиента заполнение необходимых параметров и повторить отправку команды OperationData, как это было описано выше.

Пример ответа с ResultCode = 413:

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <OperationDataResponseCommand>

<ResultCode>413</ResultCode>

<ResultMessage>Ожидается оплата операции через мерчант</ResultMessage> <ResultData> <Forms> <Webmoney> <Action>https://merchant.webmoney.ru/lmi/payment.asp</Action> <Method>POST</Method> <Fields>

<LMI_PAYEE_PURSE>U727440290579</LMI_PAYEE_PURSE>

<LMI_PAYMENT_AMOUNT>160.8</LMI_PAYMENT_AMOUNT>

<LMI_PAYMENT_DESC>Оплата за услуги Киевгаз 1000120161;09;2010;1; (Id:711462) </LMI_PAYMENT_DESC>

<LMI_PAYMENT_NO>711462</LMI_PAYMENT_NO>

</Fields>

</Webmoney>

</Forms>

<WaitData>

<Data>

<Name>Фамилия</Name>

<Type>Info</Type>

<Readonly>1</Readonly>

<Value>КАРПIНА Г. В.</Value> </Data> <Data> <Name>Показания счетчика</Name> <Type>Counter</Type>

<Discount>0.09</Discount>

<PrevCounter>100</PrevCounter>

<Counter>220</Counter>

</Data> <Data> <Name>Долг</Name> <Type>Info</Type>

<Readonly>1</Readonly>

<Value>200</Value>

</Data> <Data> <Name>Из него оплатить</Name> <Type>FreePayment</Type>

<Readonly>0</Readonly>

<Value>150</Value>

</Data> </WaitData> </ResultData>

<OperationId>1282200481000</OperationId>

</OperationDataResponseCommand>

</Commands>

</Response>

Как видно из примера, в ответе на команду OperationData с ResultCode = 413 Система передает тег Forms с описанием html-формы для перенаправления клиента на WebMoney Merchant для оплаты. Необходимо:

1. обработать содержимое Forms;

2. отобразить клиенту html-форму;

3. перенаправить клиенту на WebMoney Merchant для совершения оплаты.

В случае ResultCode = 413 в ответе на OperationData блок <WaitData>…</WaitData>, содержащий дополнительные параметры платежа, возвращается исключительно для справки. Это не должно вызвать повторное заполнение параметров платежа клиентом, как в случае с ResultCode = 422.

Пример того, как должна быть составлена html-форма для перенаправления клиента на WebMoney Merchant по ответу на OperationData, который приведен выше:

<form method="POST" action="https://merchant.webmoney.ru/lmi/payment.asp"> <input type="hidden" name="LMI_PAYMENT_NO" value="711462"> <input type="hidden" name="LMI_PAYMENT_AMOUNT" value="160.8"> <input type="hidden" name="LMI_PAYEE_PURSE" value="U727440290579"> <input type="hidden" name="LMI_SUCCESS_URL" value="http://SITENAME/payment/gc?action=yes"> <input type="hidden" name="LMI_FAIL_URL" value="http://SITENAME/payment/gc/no"> <input type="hidden" name="LMI_PAYMENT_DESC" value="Оплата за услуги Киевгаз 1000120161;09;2010;1; (Id:711462)"> <input type="submit" value="Перейти к оплате"> </form>

Параметры LMI_SUCCESS_URL и LMI_FAIL_URL должны содержать адреса страниц на сайте Контрактора, на которые клиент будет возвращаться с WebMoney Merchant соответственно после успешной, либо неуспешной оплаты. Если эти параметры не будут переданы в html-форме, клиент будет возвращаться на сайт ukrbuy.com.

2.6. Команда Check

Данная команда предназначена для проверки текущего статуса Транзакции в Системе.

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

Название

Тип

Значение

Пример

OperationId

VARCHAR(64)

Идентификатор Транзакции, ранее назначенный Контрактером

123_250509

Параметры данных ответа:

Название

Тип

Значение

Пример

Amount

MONEY

Сумма WMU, оплаченная клиентом

500.00

Created

DATETIME

Дата и время создания Транзакции в Системе

2010-10-

11T18:31:56

Executed

DATETIME

Дата и время выполнения Транзакции (проведения платежа провайдером)

2010-10-

11T18:32:23

Params

 

Дополнительные параметры платежа, полученные от провайдера

 

Params\Data

 

Параметр

 

Params\Data\Key

VARCHAR

Название параметра

Серийный

номер

Params\Data\Value

VARCHAR

Значение параметра

409970935

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

<CheckRequest> <Commands> <CheckRequestCommand>

<OperationId>125206188472552900</OperationId>

</CheckRequestCommand>

</Commands>

</CheckRequest>

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

<Response>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage> <Commands> <CheckResponseCommand>

<ResultCode>407</ResultCode>

<ResultMessage>Операция успешно обработана</ResultMessage> <ResultData>

<Amount>500.00</Amount>

<Created>2010-10-11T18:31:56</Created>

<Executed>2010-10-11T18:32:23</Executed>

<Params> <Data> <Key>Код пополнения счета</Key>

<Value>19592328905359</Value>

</Data> <Data> <Key>Серийный номер</Key>

<Value>409970935</Value>

</Data> </Params> </ResultData>

<OperationId>125206188472552900</OperationId>

</CheckResponseCommand>

</Commands>

</Response>

Судить о том, что Транзакция успешно выполнена (платеж успешно проведен провайдером), можно по состоянию ResultCode. Он должен принять значение 407.

Некоторые провайдеры при проведении платежа возвращают в Систему дополнительные параметры, а Система передает их Контрактору в ответе на команду Check (блоки <Data>…</Data>). Например, life :) передает здесь номер и код ваучера, которым клиент может пополнить свой телефон в случае, если платеж по каким-то причинам зачислен провайдером не будет. Некоторые провайдеры (в частности, ЖКХ) могут отдавать здесь текст чека (квитанции) об оплате для отображения на экране.

2.7. Команда Catalog

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

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

<CatalogRequest>

<ReturnCode>0</ReturnCode>

<ReturnMessage>OK</ReturnMessage>

<Commands>

<CatalogRequestCommand>

</CatalogRequestCommand>

</Commands>

</CatalogRequest>

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

<Response> <Commands> <CatalogResponseCommand> <Catalog> <Service>

<Id>1</Id>

<Name>Мобильная связь Укртелеком</Name> <Description /> <Created>2009-07-13 16:15:14</Created>

<Image>http://ukrbuy.com/images/logos/58.jpg</Image>

<ExampleImage />

<Order>8</Order>

<Provider>Утел</Provider> <Type>Пополнение</Type>

<CategoryId>1</CategoryId>

<Category>Сотовая связь</Category>

<WaitData>0</WaitData>

<Params> <Param> <name>Номер телефона или лицевой счет</name>

<regexp>^[0-9]+$</regexp>

<example1>0913016166</example1>

<example2 /> <example3 /> </Param> </Params>

<AmountMin>1.0000</AmountMin>

<AmountMax>10000.0000</AmountMax>

<AmountStep>0.0100</AmountStep>

<ValueDiscount>1.0000</ValueDiscount>

<ValueCurrency>грн</ValueCurrency>

<AgentFeeDiscount>0.0125</AgentFeeDiscount>

<FeeOutDiscount>0.0000</FeeOutDiscount>

<FeeOutMin>0.0000</FeeOutMin>

<FeeOutMax>0.0000</FeeOutMax>

</Service> </Catalog> <Catalog> <Service>

<Id>30</Id>

<Name>МТС-Коннект</Name>

<Description /> <Created>2009-12-08 19:00:00</Created>

<Image>http://ukrbuy.com/images/logos/9.gif</Image>

<ExampleImage />

<Order>12</Order>

<Provider>МТС</Provider> <Type>Пополнение</Type>

<CategoryId>2</CategoryId>

<Category>Интернет</Category>

<WaitData>0</WaitData>

<Params> <Param> <name>Номер лицевого счѐта</name>

<regexp>^[0-9][0-9\.]+$</regexp>

<example1>1.101385214</example1>

<example2 /> <example3 /> </Param> </Params>

<AmountMin>1.0000</AmountMin>

<AmountMax>2000.0000</AmountMax>

<AmountStep>0.0100</AmountStep>

<ValueDiscount>1.0000</ValueDiscount>

<ValueCurrency>грн</ValueCurrency>

<AgentFeeDiscount>0.006</AgentFeeDiscount>

<FeeOutDiscount>0.0000</FeeOutDiscount>

<FeeOutMin>0.0000</FeeOutMin>

<FeeOutMax>0.0000</FeeOutMax>

</Service>

</Catalog>

</CatalogResponseCommand>

</Commands>

</Response>

Каждый Сервис (блок <Service>…</Service>) описывается следующими полями:

Название

Тип

Значение

Пример

Id

INT

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

30

Name

VARCHAR

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

МТС-

Коннект

Description

VARCHAR

Описание сервиса

 

Created

DATE

Дата внесения сервиса в Систему

2009-12-08

19:00:00

Image

VARCHAR

URL картинки (логотип и т.п.)

 

Order

INT

Показатель популярности сервиса (рекомендуется отображать сервисы на сайте Контрактора с сортировкой именно по этому параметру)

12

Provider

VARCHAR

Наименование провайдера

МТС

Type

VARCHAR

Тип сервиса

Пополнение

CategoryID

INT

Идентификатор категории Каталога, к которой относится сервис

2

Category

VARCHAR

Наименование категории Каталога, к которой относится сервис

Интернет

WaitData

INT

Запрашиваются ли по данному сервису дополнительные параметры платежа (потребуется ли передача команды OperationData): 0 – нет, 1 – да

0

Params

 

Параметры платежа, передача которых в Систему необходима для создания Транзакции по данному сервису

 

Params\Param

 

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

 

Params\Param\name

VARCHAR

Название реквизита

Номер

лицевого

счета

Params\Param\regexp

VARCHAR

Регулярное выражение, описывающее, какие значения может принимать реквизит

^[0-9]{12}$

Params\Param\example1

VARCHAR

Пример значения этого реквизита

1.101385214

Params\Param\example1

VARCHAR

Пример значения этого реквизита

 

Params\Param\example1

VARCHAR

Пример значения этого реквизита

 

AmountMin

MONEY

Минимальная сумма платежа в единицах провайдера

1.0000

AmountMax

MONEY

Максимальная сумма платежа в единицах провайдера

2000.0000

AmountStep

MONEY

Допустимая дробность платежа в единицах провайдера

0.0100

ValueDiscount

MONEY

Коэффициент конвертации единиц провайдера в гривны

1.0000

ValueCurrency

VARCHAR(3)

Наименование единиц провайдера

грн, юнит

AgentFeeDiscount

MONEY

Коэффициент агентского вознаграждения (от суммы платежа)

0.006

FeeOutDiscount

MONEY

Коэффициент внешней комиссии (от суммы платежа)

0.0200

FeeOutMin

MONEY

Минимальная внешняя комиссия (в WMU)

0.0100

FeeOutMax

MONEY

Максимальная внешняя комиссия (в WMU)

5.0000

3. Коды ответа Системы (ReturnCode)

ReturnCode

ReturnMessage

0

Успешно

101

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

201

Неверный формат запроса или ошибки при попытке декомпрессии тела сообщения

202

Требуется метод POST

203

Требуется SSL

204

Тайм-аут на чтение запроса исчерпан, клиент передает данные слишком медленно

205

Требуется http-заголовок Content-Length

206

Размер запроса превышает максимально допустимый (Максимум - 1048576 байт (1 Мб))

207

Недопустимое значение http-заголовка Content-Type

208

Недопустимое значение http-заголовка Content-Encoding

209

Отсутствие или ошибки формата http-заголовков

210

Отказ сервера в авторизации запроса

301

Неверно указан идентификатор точки Контрактора

4. Результаты выполнения команд (ResultCode)

ResultCode

ResultMessage

0

Команда выполнена успешно

304

Неверно указан идентификатор сервиса (ServiceId)

302

Неверно указан идентификатор операции

305

Неверно указан объем операции

306

Неверно указаны реквизиты операции

307

Неверно указан режим подтверждения операции

308

Неверно указан таймаут операции

309

Неверно указан идентификатор чека

310

Неверно указана дата/время формирования операции

311

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

312

Неверно указан идентификатор терминала

313

Неверно указана дата

315

Сумма меньше допустимой

314

Сумма больше допустимой

401

Команда отклонена по техническим причинам

402

Команда выполнена Неуспешно

410

Команда находится на выполнении. Проверьте статус

418

Параметры не прошли валидацию на стороне провайдера

404

Операция находиться на обработке

405

Операция с таким идентификатором уже существует

406

Операция с таким идентификатором не существует

407

Операция успешно обработана

408

Операция отклонена системой

409

Сервис временно недоступен

411

Превышен лимит команд в очереди

412

Ожидается подтверждение или отмена операции

413

Ожидается оплата операции через мерчант

414

Запрос по операции принят

415

Операция отменена контрактором

416

Подтвержденную операцию не возможно отменить

417

В процессе выполнения

421

Средства возвращены клиенту

422

Ожидаются дополнительные параметры платежа

501

Абсолютно новый платеж

502

Получены данные от платежной системы

503

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

504

Была попытка вторичного получения данных платежа

512

Платеж уже существует

505

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

506

Валидация провалена при проверке достаточности данных

507

Валидация провалена при проверке подписи

508

Валидация провалена при проверке параметров платежа

509

Валидация провалена при проверке суммы платежа