WM-API

Библиотека для работы с XML-интерфейсами WebMoney для .Net платформы (WM-API)

Данная статья предназначена для разработчиков, желающих использовать интерфейсы WebMoney Transfer в Microsoft .Net приложениях.

Цель статьи: предоставить краткую информацию о библиотеке WebMoney.XmlInterfaces (кодовое название WM-API), достаточную для использования библиотеки в своих проектах.

Библиотека WebMoney.XmlInterfaces создана для упрощения работы с XML-интерфейсами системы WMTransfer. Она написана на управляемом (Managed) языке C# и распространяется с открытым кодом по лицензии MIT. Для своей работы библиотека использует модуль генерации цифровой подписи WMSignerFX.

Последняя версия библиотеки 1.0 от 16 декабря 2010 года.

Базовые сведения об архитектуре библиотеки

Содержание

1. Список модулей.
2. Специальные типы.
3. Классы запросов и ответов.
4. Специальные типы для исключений бизнес-процесса.
5. Инициализация библиотеки в коде программы.
6. Инициализация библиотеки с помощью файла конфигурации.
7. Общий сценарий использования библиотеки.
8. Порядок логирования исключительных ситуаций.
9. Примеры использования.

Список модулей

Подробная информация о каждом из модулей приведена ниже.

Специальные типы

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

Наиболее общие типы определены в библиотеке Finance.Entities (напрямую не связаны с системой WebMoney).

Эти типы можно сериализовать/десериализовать. Ниже приведена диаграмма классов (ClassDiagram) данных типов:

Типы, связанные исключительно с системой WebMoney определены в библиотеке WebMoney.BasicObjects.

Эти типы можно сериализовать/десериализовать. Ниже приведена диаграмма классов (ClassDiagram) данных типов:

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

Для каждого запроса и ответа интерфейса, создан специальный тип, инкапсулирующий данные соответствующего запроса/ответа:

Типы ответов для входящих/исходящих счетов и для переводов, наследуются от одного базового класса Operation. Для наглядности приведена диаграмма классов:

Специальные типы исключений

Для всех исключительных ситуаций бизнес-процесса, генерируемых сервером WebMoney, определены специальные типы. В общем случае таким типом является WmException (номер ошибки записан в свойстве ErrorNumber). Для некоторых интерфейсов этот тип расширен.

Расшифровать ошибку по ее номеру, можно вызвав метод TranslateDescription.

Типы исключений можно сериализовать/десериализовать. Ниже приведена диаграмма классов (ClassDiagram) данных типов:

Инициализация библиотеки в коде

Перед использованием библиотеки, ее необходимо инициализировать. Сделать это можно двумя путями: (1) прямо в коде программы, (2) в конфигурационном файле приложения.

Пример конфигурации в коде программы ключом Keeper Classic:

var masterWmId = (WmId) 111111111111; // альтернативно можно записать WmId.Parse("111111111111")
KeeperKey keeperKey = new KeeperKey("Здесь вписать XML-ключ, полученный из файла .kwm с помощью программы Key Extractor");

var initializer = new Initializer(masterWmId, keeperKey);
initializer.StartDate = new DateTime(1983, 1, 1).ToUniversalTime(); // для формирования ReqN
initializer.Apply();

Здесь primaryWmId — объект типа WmId, хранящий идентификатор владельца приватного ключа, а keeperKey — объект класса KeeperKey из сборки WebMoney.Cryptography.dll (см. WMSignerFX).

Пример конфигурации в коде программы ключом Keeper Light:

var initializer = new Initializer(certificate);
initializer.StartDate = new DateTime(1983, 1, 1).ToUniversalTime(); // для формирования ReqN
initializer.Apply();

Здесь certificate — объект стандартного класса .Net X509Certificate.

После установки параметров, необходимо вызвать метод Apply. Конфигурация будет применена глобально (это можно выполнить 1 раз перед началом вызова интерфейсов). В некоторых случаях это может привести к проблемам (к примеру, если используется кластерная архитектура), поэтому предусмотрена возможность не использовать глобальных статических объектов. Для этого передайте локальный объект класса Initializer в конструктор типа-запроса.

Инициализация библиотеки с помощью файла конфигурации

Второй способ инициализации библиотеки: задание параметров в файле конфигурации.

Для аутентификации ключом WM Keeper Classic, требуется указать:

1. Управляющий WMID.
2. Строковое представление ключа WM Keeper, полученное с помощью утилиты Key Extractor.
3. Данные для генерации номера запроса: дата отсчета и период обновления в миллисекундах.

Для аутентификации ключом WM Keeper Light, требуется указать:

1. Расположение X.509-ключа WM Keeper Light: название хранилища и тип хранилища. Альтернативный вариант: указать Base-64 представление сертификата и закрытого ключа, полученное с помощью утилиты Key Extractor.
2. Отпечаток (Thumbprint) сертификата закрытого ключа WMKeeper Light. Если указано Base-64 представление сертификата и закрытого ключа, то отпечаток сертификата указывать не нужно.
3. Данные для генерации номера запроса: дата отсчета и период обновления в миллисекундах.

Примечание: для использования библиотеки с ключом WM Keeper Light, код должен иметь полномочия FullTrust.

Пример конфигурационного файла для аутентификации ключом WM Keeper Classic:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <sectionGroup name="webMoneyConfiguration">
        <section name="applicationInterfaces" type="WebMoney.XmlInterfaces.Configuration.ConfigurationHandler, WebMoney.XmlInterfaces.Configuration" />
      </sectionGroup>
  </configSections>


  <webMoneyConfiguration>
    <applicationInterfaces>
      <authorizationMode>Classic</authorizationMode>
      <keeperClassic>
        <wmId>712300479010</wmId>
        <wmKey>&lt;RSAKeyValue&gt;&lt;Modulus&gt;ccqACxc2qzE3t+zJntCBGrw/qZTmrmJEPhmkVGUwhc+ZhDiIr4qwAvhnNwIme9r5YjWEdi7wm/XDnsp096aNjlkI&lt;/Modulus&gt;&lt;D&gt;FW1RaQMqZ6zHl6+wx+16uDB4zAmRr9sbBP7xVxzIg4vuIG4/w5b5XzFNv2sfSsmu+I3roO7E7qYmoeIn8otCeHgD&lt;/D&gt;&lt;/RSAKeyValue&gt;</wmKey>
      </keeperClassic>
      <requestNumber>
        <startTime>01.01.2009 00:00:00</startTime>
        <period>1000</period>
      </requestNumber>
    </applicationInterfaces>
  </webMoneyConfiguration>

</configuration>

Здесь wmKey — значение приватного ключа в XML-формате, полученное с помощью программы
Key Extractor. Обратите внимание! К значению ключа применен XML-Encoding (замена символов ‘<’ и ‘>’).

Пример конфигурационного файла для аутентификации ключом WM Keeper Light, с указанием хранилища:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <sectionGroup name="webMoneyConfiguration">
        <section name="applicationInterfaces" type="WebMoney.XmlInterfaces.Configuration.ConfigurationHandler, WebMoney.XmlInterfaces.Configuration" />
      </sectionGroup>
  </configSections>

  <webMoneyConfiguration>
    <applicationInterfaces>
      <authorizationMode>Light</authorizationMode>
      <keeperLight>
        <containerInfo>
          <storeName>My</storeName>
          <storeLocation>CurrentUser</storeLocation>
          <thumbprint>65d4308da7fe18fe2788acee2ec48f453b4461d1</thumbprint>
        </containerInfo>
      </keeperLight>
      <requestNumber>
        <startTime>01.01.2009 00:00:00</startTime>
        <period>1000</period>
      </requestNumber>
    </applicationInterfaces>
  </webMoneyConfiguration>

</configuration>

Пример конфигурационного файла для аутентификации ключом WM Keeper Light, с указанием Base-64 представления закрытого ключа и сертификата:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <sectionGroup name="webMoneyConfiguration">
        <section name="applicationInterfaces" type="WebMoney.XmlInterfaces.Configuration.ConfigurationHandler, WebMoney.XmlInterfaces.Configuration" />
      </sectionGroup>
  </configSections>

  <webMoneyConfiguration>
    <applicationInterfaces>
      <authorizationMode>Light</authorizationMode>
      <keeperLight>
        <rawData>MIIE+gIBAzCCBLoGCSqGSIb3DQEHAaCCBKsEggSnMIIEozCCBJ8GCSqGSIb3DQEHBqCCBJAwggSMAgEAMIIEhQYJKoZIhvcNAQcBMBwGCiqGSIb3DQEMAQYwDgQIR0XXduV1U7YCAgfQgIIEWLbDls7e99zCoPINitqYT1xaz4GQsU/5UwaBXc6Ux+dTdAB2ZVLdWRJ7XDDisQx0I4TIbm/OEPTHSRHcqasLn9/nqEps0qikST4PVVoHeFgYFWP7LZkmhrZnbNNhU+yDe4IGdZgDq+owLn2ZnnxFKQwJhk3yUC6cLoPGK/b+2FeiObAa1rKk3+xMcBy+AdGvSOLpY0hpHEWI3vRJ12mpWzQdhcc+eyrxYArBWa0tUEkFjqQPZk8+yaOfn+mB20pPuVgSJAOVACYA46nB2IY0UiQDVAiC2+SOKdUqQEK5XDDTIInHyG/y4wHAR1B1RORS4IPEdKySaaae5Mi8/8FXYb6kGI57XjdOMXR8gSgohinTLiKXbvL02FgwHHPKnIh7N2k+siwxND/eKVgQ6fElbm3XLTsjhraWICbr2zJBmE6pI/w9M1UGnNNrG8b4THmr0HIguw7V3D0kZI9BbG51+RiHb58pFkiSdGSt9PFYUwoix/wNmuzs9LM9itrVCV6HqWkxi82bIynsaPU8SDCz7BAbYlO+F35JROQR07FypMCl4LXdsLdWPeW7htZnvB7iUExs+WfMITrbSFvL+DatJ5euFuJu9mNpmM/rYuidGHgXmHN1bteMDXq1PWnfeOnnGJoXEp2zRBHk3ETwQtdKxYMzqfFNuCxrnx3mH9PBV/DWUwMAnZgb2autq+EJrLEXxpJPqWIcJNKwzx49Lx1gvqB6vv4I1u3VK+nFWOcv59m4KCbRPy7t1JbGVKCXXPstmhm2jq1byT3G3a/EKmG56BdyrzUZ2d7b6IgnSA+0E8X56UIYVgAr7rg3ciZYCFNupLwz0eqlOuDzehLnXzS+17TyEPF+sqKqJP16PwFCQaGlDd5kycvOk1i0tnM0EvHON1maZjfB/C4Wqzp+bqPjezfRiNo1VS6e8vryWb4DIy7Xgfe/C8Xxf4DzDlq+hyWcux+ewDj7qqZvc5geysjV6iYCK3JZ/IB2FNhYW+J2Os/WbK8jUFvfTO/Ha0IyO8rcQJwwliacky5LOo8Ib9Dero19S78sz39GfPmS918HLktl8fMR7ZqLnCVnvOgo0cg7IgoqfDOrBm3WGt7WQYGBaam00apf3YDtIuLsVgQT/8ZKv3WotAiyI/8vk8uc7pjC9cZdzL+aEo/e0PkETYei76QxQDJbGxp2jzTuy980AN3Mv/gZF7rYkVxVKNWOwv56npRyAyHd45th+2o2H/TIaaSOq2gwlGSQ58kO09viU1NlccNJApD4G3DaKnTm1n1e3QwiZkwQm9VyJ4IVWGYarR/0HcTXewV3a5hG4k+zhfZdrydT8UN2ViHm+vMD2Fggtz8EuXZKu6kwtt+LmsRW/6BwcL8hNAPyQp4QrUzK41O0cBuEuv2mgqspDcjNNpNJpjpRC/5Qgrzz2siwCfUyquie8A3xPqCZ2KhKVU1suGVpeGdg2ikkM6K+5SMM3WiErX3ER8uY/8vrMDcwHzAHBgUrDgMCGgQUqXXnEeizaXIhJeucy/eUUMITrakEFIfBnx2/Q82NU4rCl21Ny863Lnha</rawData>
      </keeperLight>
      <requestNumber>
        <startTime>01.01.2009 00:00:00</startTime>
        <period>1000</period>
      </requestNumber>
    </applicationInterfaces>
  </webMoneyConfiguration>

</configuration>

Примечание: для ASP.Net-приложений, файл конфигурации имеет название “Web.config” и располагается в корневой директории сайта. Для Win32-приложений, файл конфигурации называется также, как исполняемый файл приложения, с добавлением расширения “.config” (пример: MyApplication.exe.config) и располагается в одной папке с исполняемым файлом.

Начиная с версии 1.0, чтобы использовать параметры из конфигурационного файла, перед обращением к интерфейсам следует это явно указать (один раз перед первым вызовом интерфейса):

Initializer initializer = new Configurator();
initializer.Apply();

Класс Configurator расположен в сборке WebMoney.XmlInterfaces.Configuration.dll.

Использование библиотеки

После инициализации библиотеки ее можно использовать. Использование с ключами WM Keeper Classic и WM Keeper Light абсолютно идентично.

Сценарий использования:

1. Инициализировать библиотеку (см. 2 способа выше).
2. Создать объект запроса. Для использования локальной инициализации, передайте объекту запроса объект класса Initializer в конструктор.
3. Вызвать метод Submit. Этот метод вернет объект ответа (см. таблицу классов запросов и ответов выше).

Вызов метода может привести к возникновению бизнес-исключения, наследника WmException.

Логирование исключительных ситуаций

Если при обработке запроса возникает непредвиденное исключение, библиотека автоматически создает лог-файл с деталями возникшей ошибки. Файл создается в корневой директории.

Важно! Бизнес-исключения (наследники WmException) имеют уровень Debug. Остальные исключения имеют уровень Error.

Управлять процессом логирования можно с помощью конфигурационного файла NLog. По умолчанию записываются все типы исключений: и бизнес-исключения и прочие исключения.

Примеры использования

Примеры приведены на языке C#:

Общие тестовые данные (используются многими примерами одновременно).

// Тестовые данные
var primaryWmId = WmId.Parse("111111111111"); // парсинг строки
var secondaryWmId = (WmId) 222222222222; // тип ulong явно приводим к WMID
var primaryPurse = Purse.Parse("R111111111111"); // кошелек с деньгами
var secondaryPurse = new Purse(WmCurrency.R, 222222222222); // альтернативная запись
var amount = (Amount)0.01M; // можно использовать парсинг строки: Amount.Parse("0.01");

// Номер заказа в системе магазина. По нему можно искать операцию. Не уникальный.
uint orderId = 1;

// Номер перевода. Используется для предотвращения дублирования платежа или сообщения.
int transferId = 1;

X1. Выписка счета

var originalInvoice = new OriginalInvoice(orderId, primaryWmId, secondaryPurse, amount);
originalInvoice.Description = (Description)("Проверка выписки счета");
originalInvoice.Address = (Description)"Адрес магазина";
originalInvoice.Expiration = 3; // срок оплаты дней (по умолчанию 180 дней)
originalInvoice.Period = 1; // срок протекции, если разрешена оплата с протекцией

try
{
   var recentInvoice = originalInvoice.Submit();

   Console.WriteLine("Успешно. Номер счета: " + recentInvoice.Id);
}
catch (WmException wmException)
{
   Console.WriteLine("Ошибка: " + wmException.Message);
}

Примечание. При вызове метода Submit может возникнуть бизнес-исключение WmException. Это касается всех интерфейсов. Так-же может возникнуть исключение WebException (нужно вызывать метод Submit повторно).

X2. Перевод средств

var originalTransfer = new OriginalTransfer(2, new Purse(WmCurrency.Z, 1), Purse.Parse("Z123456789012"), Amount.Parse(1));
originalTransfer.Description = (Description) "Тестовый перевод";
originalTransfer.InvoiceId = recentInvoice.Id; // если перевод по счету

var recentTransfer = originalTransfer.Submit();

X3. История операций

var transferFilter = new TransferFilter(primaryPurse, DateTime.Now.AddMinutes(-5), DateTime.Now);
var transferRegister = transferFilter.Submit();

foreach (var transfer in transferRegister.TransferList)
{
   Console.WriteLine(transfer.Id + " " + transfer.Amount);
}

X4. История выписанных счетов (поиск по номеру счета)

var outgoingInvoiceFilter = new OutgoingInvoiceFilter(primaryPurse, DateTime.Now.AddMinutes(-5), DateTime.Now);
//outgoingInvoiceFilter.InvoiceId = recentInvoice.Id; поиск по номеру счета

var outgoingInvoiceRegister = outgoingInvoiceFilter.Submit();

foreach (var outgoingInvoice in outgoingInvoiceRegister.OutgoingInvoiceList)
{
   Console.WriteLine(outgoingInvoice.Id + " " + outgoingInvoice.InvoiceState);
}

X5. Завершение операции с протекцией

var protectionFinisher = new ProtectionFinisher(recentTransfer.Id, code);
var protectionReport = protectionFinisher.Submit();

X6. Отправка сообщения

var subject = (Description)"Проверка";
var content = (Message)"Текст сообщения (не более 1024 символов).";

var originalMessage = new OriginalMessage(secondaryWmId, subject, content);
var recentMessage = originalMessage.Submit();

X7. Проверка подписи

var signer = new Signer();
signer.Initialize(
                "<RSAKeyValue><Modulus>ccqACxc2qzE3t+zJntCBGrw/qZTmrmJEPhmkVGUwhc+ZhDiIr4qwAvhnNwIme9r5YjWEdi7wm/XDnsp096aNjlkI</Modulus><D>FW1RaQMqZ6zHl6+wx+16uDB4zAmRr9sbBP7xVxzIg4vuIG4/w5b5XzFNv2sfSsmu+I3roO7E7qYmoeIn8otCeHgD</D></RSAKeyValue>");

string message1 = "Сообщение1";
string message2 = "Сообщение2";
string signature = signer.Sign(message1);

var signatureInspector1 = new SignatureInspector(WmId.Parse("712300479010"), (Message)message1,
                                                             (Description)signature);
var signatureEvidence1 = signatureInspector1.Submit();

var signatureInspector2 = new SignatureInspector(WmId.Parse("712300479010"), (Message)message2,
                                                             (Description)signature);
var signatureEvidence2 = signatureInspector2.Submit();

if (!signatureEvidence1.VerificationResult)
   Console.WriteLine("!signatureEvidence1.VerificationResult");

if (signatureEvidence2.VerificationResult)
   Console.WriteLine("signatureEvidence2.VerificationResult");

X8. Поиск по идентификатору или кошельку

var wmIdFinder = new WmIdFinder(WmId.Parse("712300479010"));
var wmIdReport = wmIdFinder.Submit();

Console.WriteLine(wmIdReport.Success);

X9. Баланс на кошельках

var purseInfoFilter = new PurseInfoFilter(primaryWmId);
var purseInfoRegister = purseInfoFilter.Submit();

foreach (var purseInfo in purseInfoRegister.PurseInfoList)
{
   Console.WriteLine(purseInfo.Purse + " " + purseInfo.Amount);
}

X10. Список счетов на оплату

var incomingInvoiceFilter = new IncomingInvoiceFilter(primaryWmId, DateTime.Now.AddDays(-1), DateTime.Now);
var incomingInvoiceRegister = incomingInvoiceFilter.Submit();

foreach (var incomingInvoice in incomingInvoiceRegister.IncomingInvoiceList)
{
   Console.WriteLine(incomingInvoice.TargetWmId + " " incomingInvoice.InvoiceState);
}

X11. Информация из аттестата

var passportFinder = new PassportFinder(secondaryWmId);
var passport = passportFinder.Submit();

Console.WriteLine(passport.PassportDegreeToLocalString()); // тип аттестата на английском или русском языке, в зависимости от текущей культуры

X13. Возврат платежа с протекцией

var protectionRejector = new ProtectionRejector(transferId);
var protectionReport = protectionRejector.Submit();

X14. Бескомиссионный возврат средств

var transferRejector = new TransferRejector(transferId, amount);
var moneybackReport = transferRejector.Submit();

X15.1 Список моих доверенностей

	

var outgoingTrustFilter = new OutgoingTrustFilter(primaryWmId);

var trustRegister = outgoingTrustFilter.Submit();

foreach (var trust in trustRegister.TrustList)

{

   Console.WriteLine(trust.Master + " " + trust.TransferAllowed);

}

X15.2 Список доверяющих мне

var incomingTrustFilter = new IncomingTrustFilter(primaryWmId);

var trustRegister = incomingTrustFilter.Submit();

foreach (var trust in trustRegister.TrustList)

{

  Console.WriteLine(trust.Purse + " " + trust.DayAmount);

}

X15.3 Создание или изменение доверенности

 
var originalTrust = new OriginalTrust(secondaryWmId, primaryPurse);
originalTrust.InvoiceAllowed = true;
var trustRegister = originalTrust.Submit();

X16. Создание кошелька

var originalPurse = new OriginalPurse(_primaryWmId, WmCurrency.G, (Description)"Temp");
var recentPurse = originalPurse.Submit();

X17.1 Создание контракта

var originalContract = new OriginalContract((Description)"Тестовый контракт", ContractType.Private,
 "Контракт создан в целях тестирования библиотеки WM-API.");

originalContract.AcceptorList = new List<WmId>();
originalContract.AcceptorList.Add(primaryWmId);
originalContract.AcceptorList.Add(secondaryWmId);

X17.2 Информация об акцептантах

var acceptorFilter = new AcceptorFilter(recentContract.ContractId);
var acceptorRegister = acceptorFilter.Submit();

foreach (var acceptor in acceptorRegister.AcceptorList)
{
   if (null != acceptor.AcceptTime) // если не подписан, то дата установлена в null
      Console.WriteLine(acceptor.WmId);
}

X18. Детали операции через merchant

 
var merchantOperationFilter = new MerchantOperationFilter(primaryPurse, 200000);
var merchantOperation = merchantOperationFilter.Submit();

X19. Проверка данных WMID

var amount = Amount.Parse("0.01");

// Ввод/вывод WM наличными в одном из обменных пунктов
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, (Description)"AA000001", (Description)"Пупкин", (Description)"Василий");
//clientInspector.Output = false;
var clientEvidence = clientInspector.Submit();

// Ввод/вывод WM наличными через системы денежных переводов
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, (Description)"Петров", (Description)"Иван");
//clientInspector.Output = false;
var clientEvidence = clientInspector.Submit();

// Ввод/вывод WM на банковский счет
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, (Description)"Пупкин", (Description)"Василий", (Description)"АльфаБанк", BankAccount.Parse("111222"));
//clientInspector.Output = false;
var clientEvidence = clientInspector.Submit();

// Ввод/вывод WM на банковскую карту
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, (Description)"Петров", (Description)"Иван", (Description)"ПриватБанк", BankCard.Parse("4246667766776677"));
//clientInspector.Output = false;
var clientEvidence = clientInspector.Submit();

// Обмен WM на электронную валюту других систем
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, PaymentSystem.MoneyYandex, (Description)"41001231231231");
//clientInspector.Output = false;
string s = clientInspector.Compile();

// Ввод WM за SMS (только operation/direction=2)
var clientInspector = new ClientInspector(WmCurrency.U, amount, secondaryWmId, Phone.Parse("+380440000001"));
clientInspector.Output = false;
var clientEvidence = clientInspector.Submit();

Ссылки на ресурсы:

• Сборка для Windows
• Исходный код
• Зеркало
• SVN-репозиторий Текущая версия в папке trunk. Последняя версия в папке tags/1.0.0.

Зеркала на CodePlex и Google Code более не поддерживаются.

Категория: XML-интерфейсы

This article in other languages: English