SDK for C# on the .NET platform

Overview

SDK for C# on the .NET platform is a software development kit for ensuring the interaction of the web services developed in C# with the ecommpay payment platform during the processing of purchases via Payment Page. SDK for C# on the .NET platform is used for signing the parameter set, generating the request for opening Payment Page, verifying callbacks received from ecommpay, and obtaining payment information from the callbacks.

SDK for C# on the .NET platform platform includes:

  • src—library program code;
  • composer.json—quick information about the library usage;
  • other auxiliary files.

SDK for C# on the .NET platform is compatible with .NET version 6.0 or later and can be downloaded at the following URL: https://github.com/ITECOMMPAY/paymentpage-sdk-net.

Setup

To use SDK for C# on the .NET platform, proceed as follows:

  1. Address the following organisational issues of interaction with ecommpay:

    1. If the company has not obtained a project identifier and a secret key for interacting with the ecommpay payment platform, submit the application for connecting to the payment platform.
    2. If the company has obtained a project identifier and a secret key for interacting with the ecommpay payment platform, inform the technical support specialists about the company's intention to integrate by using SDK for C# on the .NET platform and coordinate the procedure of launching the functionality.

  2. Install the library that is included in SDK for C# on the .NET platform and link it into the code.

    using ECommPay.PaymentPage.SDK;
  3. Modify the code for using the necessary functionality.
  4. Coordinate with the ecommpay technical support specialists the procedures and dates of integrating and launching the solution.

The questions about working with SDK for C# on the .NET platform, if any, should be directed to the ecommpay technical support specialists.

Payment form opening

Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. In such cases it will be required to specify the customer's phone number or email. At least one of these parameters must be specified when creating an object of the Payment class.

However, it is also recommended that these and a number of other parameters (with the billing address information) are specified for payments made with cards of other card schemes. According to Visa, rigorous use of these parameters can significantly increase payment acceptance rates (up to 6 %) and drastically decrease the number of operations flagged as fraudulent after they have been processed (up to 65 %).

To open the payment form with the help of SDK for C# on the .NET platform, proceed as follows:

  1. Ensure that the library included in SDK for C# on the .NET platform is linked into the web service source code.
  2. Create an object of the Payment class and specify the values of the payment parameters.
    dynamic payment = new Payment(<project_id>, "<payment_id_in_your_service>");
// Project and payment identifiers unique within the project
payment.payment_amount = 1001;
// Payment amount in minor currency units
payment.payment_currency = "EUR";
// Currency code in the format of ISO-4217 alpha-3
payment.customer_id = "customer_112";
// Customer identifier
payment.payment_description = "Test payment";
// Payment description (optional parameter)

    All parameters in this example, except for the payment description, are mandatory for any purchase. You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

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

    In addition, for card purchases you are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 (details), the postal code, the city, and the street address. Such parameters are specified as follows.

    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";

    You can also use any other optional parameters available for working with Payment Page (for more information, see Parameters for opening payment form).

  3. Create an object of the Gate class and specify the secret key value received from ecommpay. This is necessary for automatic signature generation.
    var gate = new Gate('<secret_key>');
// Secret key received from ecommpay
  4. Generate the request for opening the payment form.
    var paymentUrl = gate.GetPurchasePaymentPageUrl(payment);
    A correct request for opening the payment form contains the signature and the payment parameters.
    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM
36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555
943554067...
  5. Use the generated request for opening the payment form.
    <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 generated at the previous step>'}, 'get');
</script>

    The information about the options for the Payment Page opening is provided in the section Options for opening Payment Page.

Figure: Example of the web service source code

namespace MyProject;
 
using ECommPay.PaymentPage.SDK;

public class Example
{
    /// <summary>
    /// Project identifier received from ecommpay
    /// </summary>
    private const int ProjectId = 0;
 
    /// <summary>
    /// Secret key received from ecommpay
    /// </summary>
    private const string SecretKey = "secret";
 
    /// <summary>
    /// Return of the URL for payment form opening
    /// </summary>
    /// <returns></returns>
    public static string GetUrl()
    {
        var paymentId = "test_payment"; 
        // Payment identifier unique within the project
        dynamic payment = new Payment(ProjectId, paymentId); 
        // Creation of the Payment object
        payment.payment_amount = 1001;  
        // Payment amount in minor currency units
        payment.payment_currency = "EUR"; 
        // Payment currency code in the format of ISO-4217 alpha-3
        payment.payment_description = "Test payment"; 
        // Payment description
 
        var gate = new Gate(SecretKey); // Creation of the Gate object
 
        return gate.GetPurchasePaymentPageUrl(payment);
        // Return of the URL for payment form opening
    }
}

Callback processing

A callback is an HTTP-POST request that contains payment information in the format of a JSON string. During the work with SDK for C# on the .NET platform, the information from the callbacks can be obtained with the help of the following methods:

  • getPaymentId()—returns the payment identifier.
  • getPaymentStatus()—returns the current payment status.
  • getPayment()—returns all payment information received in the callback.

To obtain payment information via these methods, proceed as follows:

  1. Ensure that the library included in SDK for C# on the .NET platform is linked into the web service source code.
  2. If an object of the Gate class was not created during the generation of the request for Payment Page opening—create this object and specify the secret key value received from ecommpay.
    var gate = new Gate('<secret_key>');
  3. Create an object of the Callback class by using the JSON string that contains the payment information and was received in the callback from the ecommpay payment platform.
    try
{
    var callback = gate.HandleCallback(data); // Receiving the data verification result
}
catch (ValidationException e) // Processing possible exceptions
{
    Console.WriteLine(e); // Displaying the error message
}
  4. Use the necessary method.
    callback.get_payment_id()             // Receiving the payment identifier
callback.get_payment_status()         // Receiving the current payment status
callback.get_payment()                // Receiving all payment information

If SDK for C# on the .NET platform is used, the verification of the signature from the callback is performed automatically.

Figure: Example of the web service source code

namespace MyProject;
 
using ECommPay.PaymentPage.SDK;
 
public class Example
{
    /// <summary>
    /// Secret key received from ecommpay
    /// </summary>
    private const string SecretKey = "secret";
 
    /// <summary>
    /// Callback processing
    /// </summary>
    /// <param name="data">JSON string received in the notification.</param>
    /// <returns>true in case of successful callback processing and false in other cases</returns>
    public bool Handler(string data)
    {
        var gate = new Gate(SecretKey); // Creation of the Gate object
        ICallback callback;
 
        // Attempt to receive the processed data
        try
        {
            // Receiving the verification result in the form of the Callback object
            callback = gate.HandleCallback(data);
        }
        // Processing possible exceptions
        catch (SdkException e)
        {
            Console.WriteLine(e); // Displaying the error message
            return false;
        }
 
        // Receiving the Payment object using its identifier
        // var order = OrderRepository.Get(callback.GetPaymentId());
        // Changing the payment status according to the one received in the callback
        // order.SetStatus(callback.GetPaymentStatus());       
        // Saving the changes
        // order.Save();
 
        return true;
    }
}

Related topics

During the work with SDK for C# on the .NET platform, the following information can come in handy: