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.

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

Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для таких случаев становится обязательным передавать номер телефона пользователя или адрес его электронной почты. По крайней мере один из этих параметров необходимо указывать при создании объекта класса Payment.

Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения.

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