SDK для C# на платформе .NET
Общая информация
SDK для C# на платформе .NET — это набор средств разработки для взаимодействия веб-сервисов, разработанных на C#, с платёжной платформой ecommpay при проведении оплат через Payment Page. SDK для C# на платформе .NET позволяет подписывать набор параметров и формировать запрос на открытие Payment Page, а также проверять подлинность полученных от ecommpay оповещений и получать из них информацию о платеже.
В состав SDK для C# на платформе .NET входят:
src
— программный код библиотеки;tests
— код автоматизированного тестирования;composer.json
— краткая справка по использованию библиотеки;- дополнительные служебные файлы.
SDK для C# на платформе .NET совместим с .NET версии 6.0 или выше и доступен для загрузки по следующей ссылке: https://github.com/ITECOMMPAY/paymentpage-sdk-net.
Подготовка к работе
Для использования SDK для C# на платформе .NET необходимо:
- Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой ecommpay:
- Если у компании нет идентификатора проекта и ключа для взаимодействия с платёжной платформой ecommpay — отправить заявку на подключение.
- Если у компании есть идентификатор и ключ для взаимодействия с платёжной платформой ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для C# на платформе .NET и согласовать с ними порядок тестирования и запуска.
- Установить библиотеку, входящую в состав SDK для C# на платформе .NET, и подключить её в коде.
using ECommPay.PaymentPage.SDK;
- Доработать код для использования необходимой функциональности.
- Согласовать со специалистами технической поддержки ecommpay порядок и сроки интеграции, тестирования и запуска решения в работу.
- Для тестирования следует использовать идентификатор тестового проекта и данные тестовых карт.
- Для перевода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от ecommpay.
При возникновении вопросов о работе с SDK для C# на платформе .NET следует обращаться в службу технической поддержки ecommpay.
Открытие платёжной формы
Для открытия платёжной формы с помощью SDK для C# на платформе .NET следует:
- Убедиться, что библиотека, входящая в состав SDK для C# на платформе .NET, подключена в исходном коде веб-сервиса.
- Создать объект класса
Payment
и указать значения параметров платежа.dynamic payment = new Payment(<project_id>, "<payment_id_in_your_service>"); // Идентификаторы проекта и платежа, уникальные в рамках проекта payment.payment_amount = 1001; // Сумма платежа в дробных единицах валюты payment.payment_currency = "EUR"; // Код валюты в формате ISO-4217 alpha-3 payment.customer_id = "customer_112"; // Идентификатор пользователя payment.payment_description = "Тестовый платёж"; // Описание платежа (необязательный параметр)
Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page (подробнее — в разделе Параметры вызова платёжной формы).
- Создать объект класса
Gate
и указать значение секретного ключа, полученное от ecommpay. Это необходимо для автоматического подписывания параметров.var gate = new Gate('<secret_key>'); // Секретный ключ, полученный от ecommpay
- Сформировать запрос на открытие платёжной формы.
var paymentUrl = gate.GetPurchasePaymentPageUrl(payment);
Корректный запрос на открытие платёжной формы содержит подпись и параметры платежа.https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM 36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555 943554067...
- Использовать полученный запрос для открытия платёжной формы.
<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script> <script type="text/javascript"> EPayWidget.run({ baseUrl: '<URL, полученный на предыдущем шаге>'}, 'get'); </script>
Информация о способах открытия платёжной формы представлена в разделе Способы открытия платёжной формы.
Рис.: Пример исходного кода веб-сервиса
namespace MyProject; using ECommPay.PaymentPage.SDK; public class Example { /// <summary> /// Идентификатор проекта, полученный от ecommpay /// </summary> private const int ProjectId = 0; /// <summary> /// Секретный ключ, полученный от ecommpay /// </summary> private const string SecretKey = "secret"; /// <summary> /// Возврат URL для открытия платёжной формы /// </summary> /// <returns></returns> public static string GetUrl() { var paymentId = "test_payment"; // Идентификатор платежа, уникальный в рамках проекта dynamic payment = new Payment(ProjectId, paymentId); // Создание объекта Payment payment.payment_amount = 1001; // Сумма платежа в дробных единицах валюты payment.payment_currency = "EUR"; // Код валюты платежа в формате ISO-4217 alpha-3 payment.payment_description = "Тестовый платёж"; // Описание платежа var gate = new Gate(SecretKey); // Создание объекта Gate return gate.GetPurchasePaymentPageUrl(payment); // Возврат ссылки для открытия платёжной формы } }
Обработка оповещений
Оповещение представляет собой HTTP-POST-запрос, содержащий информацию о платеже в формате JSON-строки. При работе с SDK для C# на платформе .NET получать информацию из оповещений можно с использованием следующих методов:
getPaymentId()
— возвращает идентификатор платежа;getPaymentStatus()
— возвращает текущий статус платежа;getPayment()
— возвращает всю информацию о платеже, полученную в оповещении.
Чтобы получить информацию о платеже с использованием этих методов, необходимо:
- Убедиться, что библиотека, входящая в состав SDK для C# на платформе .NET, подключена в исходном коде веб-сервиса.
- Если объект класса
Gate
не был создан при формировании запроса для вызова Payment Page — создать этот объект и указать значение секретного ключа, полученное от ecommpay.var gate = new Gate('<secret_key>');
- Создать объект класса
Сallback
, используя JSON-строку с информацией о платеже, полученную в оповещении от платёжной платформы ecommpay.try { var callback = gate.HandleCallback(data); // Получение результата проверки данных } catch (ValidationException e) // Обработка возможных исключений { Console.WriteLine(e); // Вывод сообщения об ошибке }
- Использовать требуемый метод.
callback.get_payment_id() // Получение идентификатора платежа callback.get_payment_status() // Получение текущего статуса платежа callback.get_payment() // Получение всей информации о платеже
При использовании SDK для C# на платформе .NET проверка подписи в оповещении выполняется автоматически.
Рис.: Пример исходного кода веб-сервиса
namespace MyProject; using ECommPay.PaymentPage.SDK; public class Example { /// <summary> /// Секретный ключ, полученный от ecommpay /// </summary> private const string SecretKey = "secret"; /// <summary> /// Обработка оповещения /// </summary> /// <param name="data">JSON-строка, полученная из оповещения.</param> /// <returns>true при успешной обработке оповещения и false в других случаях</returns> public bool Handler(string data) { var gate = new Gate(SecretKey); // Создание объекта Gate ICallback callback; // Попытка получения обработанных данных try { // Получение результата проверки в виде объекта Callback callback = gate.HandleCallback(data); } // Обработка возможных исключений catch (SdkException e) { Console.WriteLine(e); // Вывод сообщения об ошибке return false; } // Получение объекта Payment по его идентификатору // var order = OrderRepository.Get(callback.GetPaymentId()); // Изменение статуса платежа в соответствии с полученным в оповещении // order.SetStatus(callback.GetPaymentStatus()); // Сохранение изменений // order.Save(); return true; } }
Тестирование
При работе с SDK для C# на платформе .NET платёжную форму можно открывать с использованием тестового проекта (для тестирования проведения платежей) и режима отладки (для выявления ошибок в запросах на открытие платёжной формы).
Тестовый проект позволяет открывать платёжную форму в тестовом режиме, с надписью Test mode в верхней части и возможностью указывать произвольные данные. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде ecommpay, через сайт компании или с помощью специалистов технической поддержки ecommpay. Чтобы перейти в тестовый режим, необходимо открыть платёжную форму с указанием полученных тестовых данных.
Режим отладки позволяет получать информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок — открывать платёжную форму в тестовом режиме, с надписью Test mode в верхней части и возможностью указывать произвольные данные.
Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу sdk.ecommpay.com. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы (как тестовые, так и реальные) и анализировать информацию об ошибках. Для этого используется код следующего вида:
dynamic payment = new Payment(<project_id>, '<payment_id_in_your_service>'); payment.payment_amount = 1001; payment.payment_currency = "EUR"; payment.payment_description = "Тестовый платёж"; payment.customer_id = "customer_112"; payment.testMode = true; // Включение режима отладки var gate = new Gate(SecretKey); try { return gate.GetPurchasePaymentPageUrl(payment); // Получение ссылки на открытие платёжной формы } catch (ValidationException e) // Обработка возможных исключений { Console.WriteLine(e); // Вывод сообщения об ошибке в консоль } return null;
Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом:
One or more parameters is not valid:
Customer_id:
Must be not null // Не указан идентификатор пользователя, обязательный для запроса
Account_token:
Invalid account token // Указан некорректный токен
Дополнительные материалы
При работе с SDK для C# на платформе .NET также могут быть полезны следующие материалы:
- Модель проведения платежей — раздел с общей информацией о типах поддерживаемых платежей и операций, а также об их возможных статусах.
- Параметры вызова платёжной формы — раздел с информацией о параметрах, доступных для указания при открытии платёжной формы.
- Тестовые карты — раздел с информацией о данных платёжных карт, которые могут использоваться при тестировании.
- Оповещения — раздел с информацией об оповещениях и работе с ними.
- Информация о выполнении операций — раздел с информацией о кодах ошибок, используемых в платёжной платформе.