Ecom Payments .NET SDK

Dependency-free .NET 8+ SDK for Ecom Payments E_API, E_LINKS, refunds, and webhook signatures. Use it only in server-side applications because it handles private merchant credentials.

Requirements

.NET 8 or later
Ecom API token and merchant ID

Installation

dotnet add package Ecom.Payments

Configuration

using Ecom.Payments;

var ecom = new EcomClient(new EcomOptions(
    ApiToken: Environment.GetEnvironmentVariable("ECOM_API_TOKEN")!,
    MerchantId: Environment.GetEnvironmentVariable("ECOM_MID")!,
    Environment: EcomEnvironment.Sandbox // change to Production when ready
));

You may pass an application-managed HttpClient as the second constructor argument.

E_API

var charge = await ecom.EApi.CreateChargeAsync(new CreateChargeRequest(
    Amount: new Amount(10.500m),
    Options: new ChargeOptions("INDIRECT"),
    Urls: new Urls(
        SuccessUrl: "https://example.com/payment/success",
        ErrorUrl: "https://example.com/payment/error"),
    Customer: new Customer(FullName: "Ahmed Ali", Email: "[email protected]"),
    Description: "Order #1001"
));

var status = await ecom.EApi.GetChargeAsync(charge.PaymentToken);

E_LINKS

var invoice = await ecom.ELinks.CreateInvoiceAsync(new CreateInvoiceRequest(
    Amount: new InvoiceAmount(25.000m),
    Customer: new InvoiceCustomer("Ahmed Ali", "+965", "99999999", "[email protected]"),
    Notification: new Notification(Email: true),
    Language: "en"
));

var invoices = await ecom.ELinks.ListInvoicesAsync(new PageQuery(Page: 1, Take: 20, Order: SortOrder.DESC));
await ecom.ELinks.SendInvoiceReminderAsync(invoice.Id, new InvoiceReminderRequest(Email: true));

Other methods: GetInvoiceAsync, GetInvoiceByPaymentTokenAsync, DeleteInvoiceAsync, and MarkInvoiceAsPaidAsync.

Refunds

var refund = await ecom.Refunds.CreateRefundAsync(new CreateRefundRequest(
    Amount: 5.000m,
    EcomId: "ECOM123",
    MerchantReference: "refund-1001"
));

var refunds = await ecom.Refunds.ListRefundsAsync(new PageQuery(Page: 1, Take: 20));

Webhooks

Use the parsed webhook data fields and your webhook secret:

var data = new Dictionary<string, object?>
{
    ["ecomId"] = "ECOM123",
    ["paymentStatus"] = "CAPTURED"
};

var valid = ecom.Webhooks.VerifySignature(data, signatureHeader, webhookSecret);
if (!valid) return Results.Unauthorized();

Signature generation removes null fields, sorts keys case-insensitively, builds key=value&key2=value2, and returns HMAC-SHA256 hex. Verification uses constant-time comparison.

Errors

try
{
    await ecom.EApi.GetChargeAsync("CHA_invalid");
}
catch (EcomApiException error)
{
    Console.WriteLine($"{(int)error.StatusCode}: {error.Message}");
    Console.WriteLine(error.ResponseBody);
}

Development

dotnet build src/Ecom.Payments/Ecom.Payments.csproj
dotnet run --project tests/Ecom.Payments.Checks/Ecom.Payments.Checks.csproj
dotnet pack src/Ecom.Payments/Ecom.Payments.csproj -c Release -o artifacts

License

MIT