SDK для C# на платформе .NET

Общая информация

SDK для C# на платформе .NET — это набор средств разработки для взаимодействия веб-сервисов, разработанных на C#, с платёжной платформой ecommpay при проведении оплат через Payment Page. SDK для C# на платформе .NET позволяет подписывать набор параметров и формировать запрос на открытие Payment Page, а также проверять подлинность полученных от ecommpay оповещений и получать из них информацию о платеже.

В состав SDK для C# на платформе .NET входят:

  • src — программный код библиотеки;
  • 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 порядок и сроки интеграции и запуска решения в работу.

При возникновении вопросов о работе с 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 = "Тестовый платёж";
// Описание платежа (необязательный параметр)

    Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом.

    payment.customer_phone = "The customer's phone number. Must have from 4 to 24 digits";
payment.customer_email = "The customer's email";

    Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 (подробнее), индекс, названия города и улицы. Эти сведения указываются следующим образом.

    payment.billing_postal = "The postal code of the customer's billing address";
payment.billing_country = "The country of the customer's billing address, in ISO 3166-1 alpha-2";
payment.billing_city = "The city of the customer's billing address";
payment.billing_address = "The street of the customer's billing address";

    Дополнительно можно использовать любые другие параметры из числа доступных для работы с 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. Использовать сформированный адрес для вызова платёжной формы (подробнее).
Рис. 1. Пример исходного кода веб-сервиса
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 проверка подписи в оповещении выполняется автоматически.

Рис. 2. Пример исходного кода веб-сервиса
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;
    }
}

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

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