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;
tests—automated testing 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:

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 testing and launching the functionality.
Install the library that is included in SDK for C# on the .NET platform and link it into the code.
```
using ECommPay.PaymentPage.SDK;
```
Modify the code for using the necessary functionality.
Coordinate with the ecommpay technical support specialists the procedures and dates of integrating, testing, and launching the solution.
- For testing, the test project identifier and the test cards details should be used.
- For switching to the production mode, the value of the test project identifier should be changed to the value of the production project identifier received from ecommpay.

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

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

Ensure that the library included in SDK for C# on the .NET platform is linked into the web service source code.

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. Additionally, any other parameters available for the work with Payment Page can be used (for more information, see Parameters for opening payment form).

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
```

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...

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:

Ensure that the library included in SDK for C# on the .NET platform is linked into the web service source code.
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>');
```

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
}

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

Testing

During the work with SDK for C# on the .NET platform, the payment form can be opened by using the test project (for testing payment processing) and the debugging mode (for detecting errors in requests for opening the payment form).

The test project allows opening the payment form in the test mode, with the Test mode text at the top of the form and the capability to specify random data. You can obtain the test project identifier and the secret key for this project when accessing the ecommpay test environment via the company's website or with the help of the ecommpay technical support specialists. For switching to the test mode, the payment form should be opened by way of specifying the received test data.

The debugging mode allows receiving information about the errors made when the payment parameters were specified. If no errors were detected in this mode, the payment form can be opened in the test mode, with the Test mode text at the top of the form and the capability to specify random data.

Before debugging, the capability of sending HTTP requests from the server side of the web service to the sdk.ecommpay.com resource should be enabled. After that, you can specify various parameters (both test and real ones) for payment form opening during debugging and analyse error information. For this, use the code of the following format:

dynamic payment = new Payment(<project_id>, '<payment_id_in_your_service>');
payment.payment_amount = 1001;
payment.payment_currency = "EUR";
payment.payment_description = "Test payment";
payment.customer_id = "customer_112";
payment.testMode = true; // Enabling the debugging mode
 
var gate = new Gate(SecretKey);
 
try
{
    return gate.GetPurchasePaymentPageUrl(payment);
    // Receiving the URL for payment form opening
}
catch (ValidationException e) // Processing possible exceptions
{
    Console.WriteLine(e); // Displaying the error message in the console
}
 
return null;

The information about the detected errors, which is received as a result of these actions, can have the following text format:

One or more parameters is not valid:
 
Customer_id:
    Must be not null  // Customer identifier mandatory for the request is not specified
Account_token:
    Invalid account token  // Incorrect token is specified

Overview

Setup

Payment form opening

Callback processing

Testing

Related topics