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 необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой ecommpay:
    • Если у компании нет идентификатора проекта и ключа для взаимодействия с платёжной платформой ecommpay — отправить заявку на подключение.
    • Если у компании есть идентификатор и ключ для взаимодействия с платёжной платформой ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для C# на платформе .NET и согласовать с ними порядок тестирования и запуска.
  2. Установить библиотеку, входящую в состав SDK для C# на платформе .NET, и подключить её в коде.
    using ECommPay.PaymentPage.SDK;
  3. Доработать код для использования необходимой функциональности.
  4. Согласовать со специалистами технической поддержки ecommpay порядок и сроки интеграции, тестирования и запуска решения в работу.
    • Для тестирования следует использовать идентификатор тестового проекта и данные тестовых карт.
    • Для перевода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от ecommpay.

При возникновении вопросов о работе с SDK для C# на платформе .NET следует обращаться в службу технической поддержки ecommpay.

Открытие платёжной формы

Для открытия платёжной формы с помощью SDK для C# на платформе .NET следует:

  1. Убедиться, что библиотека, входящая в состав SDK для C# на платформе .NET, подключена в исходном коде веб-сервиса.
  2. Создать объект класса 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 (подробнее — в разделе Параметры вызова платёжной формы).

  3. Создать объект класса Gate и указать значение секретного ключа, полученное от ecommpay. Это необходимо для автоматического подписывания параметров.
    var gate = new Gate('<secret_key>');
// Секретный ключ, полученный от ecommpay
  4. Сформировать запрос на открытие платёжной формы.
    var paymentUrl = gate.GetPurchasePaymentPageUrl(payment);
    Корректный запрос на открытие платёжной формы содержит подпись и параметры платежа.
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM
36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555
943554067...
  5. Использовать полученный запрос для открытия платёжной формы.
    <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() — возвращает всю информацию о платеже, полученную в оповещении.

Чтобы получить информацию о платеже с использованием этих методов, необходимо:

  1. Убедиться, что библиотека, входящая в состав SDK для C# на платформе .NET, подключена в исходном коде веб-сервиса.
  2. Если объект класса Gate не был создан при формировании запроса для вызова Payment Page — создать этот объект и указать значение секретного ключа, полученное от ecommpay.
    var gate = new Gate('<secret_key>');
  3. Создать объект класса Сallback, используя JSON-строку с информацией о платеже, полученную в оповещении от платёжной платформы ecommpay.
    try
{
    var callback = gate.HandleCallback(data); // Получение результата проверки данных
}
catch (ValidationException e) // Обработка возможных исключений
{
    Console.WriteLine(e); // Вывод сообщения об ошибке
}
  4. Использовать требуемый метод.
    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 также могут быть полезны следующие материалы: