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

статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке C\# на платформе .NET

## Общая информация {#section_ow3_yll_g5b .section}

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

В состав SDK для C\# на платформе .NET входят программный код библиотеки и служебные файлы.

SDK для C\# на платформе .NET совместим с .NET версии 6.0 или выше и доступен для загрузки по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-net](https://github.com/ITECOMMPAY/paymentpage-sdk-net).

## Подготовка к работе {#section_iyq_yll_g5b .section}

Для использования SDK для C\# на платформе .NET необходимо:

1.  Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой Ecommpay:
    -   Если у компании нет идентификатора проекта и ключа для взаимодействия с платёжной платформой Ecommpay — отправить [заявку на подключение](https://ecommpay.com/apply-now/).
    -   Если у компании есть идентификатор и ключ для взаимодействия с платёжной платформой Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для C\# на платформе .NET и согласовать с ними порядок запуска.
2.  Установить библиотеку, входящую в состав SDK для C\# на платформе .NET, и подключить её в коде.

    ```language-csharp
    using ECommPay.PaymentPage.SDK;
    ```

3.  Доработать код для использования необходимой функциональности.
4.  Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции и запуска решения в работу.

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

## Открытие платёжной формы {#section_dmq_dml_g5b .section}

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

1.  Убедиться, что библиотека, входящая в состав SDK для C\# на платформе .NET, подключена в исходном коде веб-сервиса.
2.  Создать объект класса `Payment` и указать значения параметров платежа.

    ```language-csharp
    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. Их необходимо указывать следующим образом.

    ```language-csharp
    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 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом.

    ```language-csharp
    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 \(подробнее — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md)\).

3.  Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Это необходимо для автоматического подписывания параметров.

    ```language-csharp
    var gate = new Gate('<secret_key>');
    // Секретный ключ, полученный от Ecommpay
    ```

4.  Сформировать адрес для вызова платёжной формы.

    ```language-csharp
    var paymentUrl = gate.GetPurchasePaymentPageUrl(payment);
    ```

    Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа:

    ```language-xml
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM
    36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555
    943554067...
    ```

5.  Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\).

```language-csharp
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.customer_id = "customer_112"; 
        // Идентификатор пользователя
        payment.payment_description = "Тестовый платёж"; 
        // Описание платежа
 
        var gate = new Gate(SecretKey); // Создание объекта Gate
 
        return gate.GetPurchasePaymentPageUrl(payment);
        // Возврат ссылки для открытия платёжной формы
    }
}
```

## Обработка оповещений {#section_vcn_3ml_g5b .section}

Оповещение представляет собой HTTP-POST-запрос, содержащий информацию о платеже в формате JSON-строки. При работе с SDK для C\# на платформе .NET получать информацию из оповещений можно с использованием следующих методов:

-   `getPaymentId()` — возвращает идентификатор платежа;
-   `getPaymentStatus()` — возвращает текущий статус платежа;
-   `getPayment()` — возвращает всю информацию о платеже, полученную в оповещении.

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

1.  Убедиться, что библиотека, входящая в состав SDK для C\# на платформе .NET, подключена в исходном коде веб-сервиса.
2.  Если объект класса `Gate` не был создан при формировании запроса для вызова Payment Page — создать этот объект и указать значение секретного ключа, полученное от Ecommpay.

    ```language-csharp
    var gate = new Gate('<secret_key>');
    ```

3.  Создать объект класса `Сallback`, используя JSON-строку с информацией о платеже, полученную в оповещении от платёжной платформы Ecommpay.

    ```language-csharp
    try
    {
        var callback = gate.HandleCallback(data); // Получение результата проверки данных
    }
    catch (ValidationException e) // Обработка возможных исключений
    {
        Console.WriteLine(e); // Вывод сообщения об ошибке
    }
    ```

4.  Использовать требуемый метод.

    ```language-csharp
    callback.get_payment_id()             // Получение идентификатора платежа
    callback.get_payment_status()         // Получение текущего статуса платежа
    callback.get_payment()                // Получение всей информации о платеже
    ```


При использовании SDK для C\# на платформе .NET проверка подписи в оповещении выполняется автоматически.

```language-csharp
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;
    }
}
```

## Дополнительные материалы {#section_kyl_ymw_g5b .section}

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

-   [Работа с оповещениями](ru_platform_callbacks.md)
-   [Проведение платежей](ru_platform_payment_model.md)

**На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md)