Для развёртывания в качестве Axis2 скомпонованного микросервиса в среде WSO2 EI

Этот автономный микросервис на фреймворке Axis2 предоставляет возможность полной интеграции с QIWI по средством терминального протокола. Сервис позволяет развернуть его даже в чистой среде WSO2 EI (начиная с версии 6.1.0).

Основной класс сервиса в котором содержится список методов для работы с ним является ru.kubankredit.qiwi.Qiwi. Все операции поддерживают как SOAP 1.1, так и SOAP 1.2 конвенции вызова в рамках заголовков SOAPAction указанных в элементах "actionMapping".

Для настройки сервиса, после сборки проекта в *.aar файл, необходимо открыть его (файл является архивом) и открыть файл настроек settings.yml, в нём содержится список настроек сервиса для работы с протоколом Киви, а также url до Киви сервиса, взаимодействия с базой данных и другими сервисами платёжного центра, содержит список внутренних параметров.

Из основных блоков, изменению подлежат параметры:

• Oracle база данных - настройки:

  Oracle:
    url: "jdbc:oracle:thin:@ip:port/db" # Адрес соединения с базой данных Oracle (платёжный центр)
    username: "username" # Пользователь (владелец схемы)
    password: "password" # Пароль пользователя

• GateContract сервис - настройки:

  GateContract:
    url: "http://localhost:9008/soap/IGateContract" # Адрес сервиса договоров
    connectionTimeout: 10 # Таймаут соединения с сервисом (в секундах)
    readTimeout: 30 # Таймаут ожидания ответа от сервиса (в секундах)

• GatePayments сервис - настройки:

  GatePayments:
    url: "http://localhost:9010/soap/IGatePayments" # Адрес сервиса платежей
    connectionTimeout: 10 # Таймаут соединения с сервисом (в секундах)
    readTimeout: 30 # Таймаут ожидания ответа от сервиса (в секундах)

• ActiveMQ брокер сообщений - настройки:

  ActiveMQ:
    url: "tcp://localhost:61616" # Адрес на котором брокер сообщений ActiveMQ работает
    username: "admin" # Имя пользователя
    password: "admin" # Пароль
    consumeMessagesPerCall: 5 # Количество сообщений, которое за одну итерацию будет вычитано из брокера
    consumeInterval: 5 - # Интервал в секундах между запросами вычитки сообщений от брокера
    consumeActive: true # Признак активности потребителя сообщений от брокера
    paymentStatusQueueName: "QiwiGetPaymentStatus" # Название очереди для получения статуса платежа

• АО "Киви" взаимодействие и интеграция - настройки:

  Qiwi:
    url: "http://servicet.osmp.ru/xmlgate/xml.jsp" # Адрес взаимодействия с АО "Киви" (текущий тестовый)
    connectionTimeout: 10 # Таймаут соединения с сервисом (в секундах)
    readTimeout: 30 # Таймаут ожидания ответа от сервиса (в секундах)
    login: "dev0000" # Логин пользователя в АО "Киви"
    privateKeyPath: "/private.key" # Путь до приватного ключа (для подписания запросов в АО "Киви")
    keyIsResource: true # Признак того, что приватный ключ лежит в архиве сервиса (является ресурсом)
    publicKeyStoreType: "1" # Тип хранилища публичного ключа в АО "Киви" (константа)
    signAlgorithm: "MD5" # Алгоритм используемый для подписания пароля пользователя
    software: "Dealer v0" # Алиас программного средства используемого в АО "Киви" (константа)
    terminalId: "0000000" # Идентификатор терминала (если не был передан в запросе)
    userAgent: "KKBank" # Агентское имя отправителя запросов в АО "Киви"
    digitalSignAlgorithm: "SHA1withRSA" # Алгоритм подписания цифровой подписью запросов в АО "Киви"
    fixedAmount: "10.00" # Фиксированная сумма денег отправляемая в запросе проверке возможности добавления платежа

Примечания:

• Можно хранить приватный ключ вне сервиса, но тогда нужно в параметре PrivateKeyPath указать адрес до ключа и в параметре KeyIsResource поставить значение false
• Параметр TerminalId будет браться из настроек только если он не был передан в виде Query параметров в запросах GetCharges, PossPayment, и AddPayment от платёжного центра
• Если взаимодействие с АО "Киви" промышленными или тестовыми сервисами происходит не напрямую из этого сервиса, то необходимо путь до прокси-сервиса в параметре QiwiUrl
• Если необходимо временно отключить считывание сообщений от брокера ActiveMQ, то следует переключить параметр consumeActive в значение false

Для настройки доступа до АО "Киви" необходимо предпринять несколько шагов. Основная инструкция в файле agt_cabinet_ru.

1. В личном кабинете агента (https://agt.qiwi.com - промышленный, https://agt-test.qiwi.com - тестовый) на сайте АО "Киви" добавить персону и указать ей логин и добавить терминал c типом "XML протокол". Для доступа к личному кабинету потребуется сертификат безопасности от АО "Киви".

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

3. Создать для персоны одноразовый пароль в разделе "Персоны", в профиле добавленной персоны или во вкладке " Персоны" профиля терминала. В тестовой среде его можно получить по адресу https://agt-test.qiwi.com/system/person-messages , а в промышленной среде на номер телефона.

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

5. Ключи формата PCKS#1 следует запросить у отдела безопасности, который должен предоставить их в файлах private.key и public.key по примеру заголовков:

   • Публичный ключ:

     -----BEGIN PUBLIC KEY-----
     -----END PUBLIC KEY-----

   • Приватный ключ RSA:

     -----BEGIN RSA PRIVATE KEY-----
     -----END RSA PRIVATE KEY-----

6. Первый запрос SetPublicKey в сервис должен содержать в себе одноразовый пароль и публичный ключ, после чего можно будет отправлять запросы, которые будут подписываться с помощью закрытого ключа и отправляться в АО "Киви".

7. В запросе SetPublicKey в элемент PublicKey необходимо вставить текст из публичного ключа заключенный между BEGIN и END секциям ключа, а в элемент UserPassword необходимо вставить одноразовый пароль персоны.

8. Для настройки услуг платёжного центра и контроля состояния корректности настройки услуг по провайдерам предоставленным АО "Киви" необходимо делать запрос GetUIProviders, к примеру в метод ProxyToQiwi в сервисе, который вернёт XML список провайдеров с настройками (пример запроса и ответа есть в src\main\resources\Examples).

<operation name="GetCharges">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    <actionMapping>http://ProxyService/IProxyService/GetCharges</actionMapping>
</operation>

Пример запроса и ответа есть в src\main\resources\Examples с префиксом GetCharges

Пример (без данных) запроса обёрнутый в SOAP-Envelope версии SOAP 1.1:

curl -X POST -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: \"http://ProxyService/IProxyService/GetCharges\"" -d '<?xml version='"'1.0'"' encoding='"'utf-8'"'?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Body><GetCharges xmlns="http://ProxyService"/></SOAP-ENV:Body></SOAP-ENV:Envelope>' "http://localhost:8280/services/QiwiService?id=1243&terminal=97605235"

<operation name="PossPayment">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    <actionMapping>http://ProxyService/IProxyService/PossPayment</actionMapping>
</operation>

Пример запроса и ответа есть в src\main\resources\Examples с префиксом PossPayment

Пример (без данных) запроса обёрнутый в SOAP-Envelope версии SOAP 1.1:

curl -X POST -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: \"http://ProxyService/IProxyService/PossPayment\"" -d '<?xml version='"'1.0'"' encoding='"'utf-8'"'?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Body><PossPayment xmlns="http://ProxyService"/></SOAP-ENV:Body></SOAP-ENV:Envelope>' "http://localhost:8280/services/QiwiService?id=1243&terminal=97605235"

<operation name="AddPayment">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    <actionMapping>http://ProxyService/IProxyService/AddPayment</actionMapping>
</operation>

Пример запроса и ответа есть в src\main\resources\Examples с префиксом AddPayment

Пример (без данных) запроса обёрнутый в SOAP-Envelope версии SOAP 1.1:

curl -X POST -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: \"http://ProxyService/IProxyService/AddPayment\"" -d '<?xml version='"'1.0'"' encoding='"'utf-8'"'?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Body><AddPayment xmlns="http://ProxyService"/></SOAP-ENV:Body></SOAP-ENV:Envelope>' "http://localhost:8280/services/QiwiService?id=1243&terminal=97605235"

Если не передавать "terminal" параметр в запросе, то сервис попытается взять его из настроек сервиса в файле "settings.properties" из параметра "TerminalId"

В реализации метода AddPayment прописан функционал авторизации платежа и следом подтверждения платежа в рамках одной интерации по запросу из ПЦ.

<operation name="ProxyToQiwi">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
</operation>

Пример запроса обёрнутый в SOAP-Envelope версии SOAP 1.2:

curl -X POST -H "Content-Type: application/soap+xml; charset=UTF-8; action=\"urn:ProxyToQiwi\"" -d '<?xml version='"'1.0'"' encoding='"'UTF-8'"'?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body><request><client software="Dealer v0" terminal="10788430"/><agents><getBalance/></agents></request></soapenv:Body></soapenv:Envelope>' http://localhost:8280/services/QiwiService

<operation name="SetPublicKey">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
</operation>

Пример запроса обёрнутый в SOAP-Envelope версии SOAP 1.2:

curl -X POST -H "Content-Type: application/soap+xml; charset=UTF-8; action=\"urn:SetPublicKey\"" -d '<?xml version='"'1.0'"' encoding='"'UTF-8'"'?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body>SetPublicKey><UserPassword/><PublicKey/></SetPublicKey></soapenv:Body></soapenv:Envelope>' http://localhost:8280/services/QiwiService

<operation name="GetBalance">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
</operation>

Пример вызова:

curl -X GET "http://localhost:8280/services/QiwiService/GetBalance?terminal=[id]"

<operation name="GetUIProviders">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
</operation>

Пример вызова:

curl -X GET "http://localhost:8280/services/QiwiService/GetUIProviders?terminal=[id]"

<operation name="GetVersion">
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
</operation>

Пример вызова:

curl -X GET "http://localhost:8280/services/QiwiService/Version"

Внутри сервиса в модуле Core есть параметр DeveloperMode который определяет режим работы сервиса. В положении true запросы будут лететь в эмулятор внутри сервиса, а положении false будут лететь напрямую по адресу конечных точек указанных в настройках.

Из этой директории запустите команду:

mvn clean install

Проследуйте в директорию <EI_HOME>/repository/deployment/server/axis2services и скопируйте в неё *.aar файл скомпилированной версии микросервиса из директории /target. AAR сервис будет развёрнут внутри WSO2 EI после запуска.

Пример имени сервиса: QiwiService-1.0.0.aar

Можно выполнить следующий запрос возвращающий версию сервиса

curl -X GET "http://localhost:8280/services/QiwiService/Version"

1. Пример успешного платежа:

   service="42" amount="10" account="1175689795"
   

2. Клиент выбрал не ту услугу для пополнения оператора сотовой связи (Номер не принадлежит оператору):

   service="42" amount="10" account="4748186694"
   

3. Клиент при пополнении услуги ввёл неверный номер договора/лс (Неверный формат счета/телефона):

   service="42" amount="10" account="11756897959"
   

4. Клиент при пополнении услуги не дописал цифру/букву номера договора/лс (Неверный формат счета/телефона):

   service="42" amount="10" account="175689795"
   

5. Пополнение услуги с фиксированной минимальной и максимальной суммой платежа (Сумма слишком велика):

   service="42" amount="15001" account="1175689795"
   

6. Пополнение услуги с фиксированной минимальной и максимальной суммой платежа (Сумма слишком мала):

   service="42" amount="0.55" account="1175689795"
   

7. Оплата игр по логину (Успех):

   service="8439" amount="10" account="[email protected]"
   

8. Оплата по номеру транспондера (Неверный формат счета/телефона):

   service="5743" amount="10" account="10123456789"
   

1. Управление персонами (ЛК);

2. Управление терминалами (ЛК);

3. Авторизация по цифровой подписи;

4. Получение структуры интерфейса оплаты;

5. Получение баланса;

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

7. Проверка запроса getRequiredPersonalData