DevSkill.SSLCommerz 4.0.0

DevSkill.SSLCommerz

A .NET library for integrating with the SSLCommerz payment gateway: payment session requests, order validation, IPN verify_sign verification, and transaction search — fully async, typed, and testable.

Branch	Status
main
develop

Requirements

• .NET 10 SDK or later (the package targets net10.0)

Installation

dotnet add package DevSkill.SSLCommerz

Configuration

Bind SslCommerzSettings from configuration — this is the single credential source; the client stamps store_id/store_passwd onto every call at send time (credentials never appear on request models).

{
  "SSLCommerz": {
    "StoreId": "your_store_id",
    "StorePassword": "your_store_password",
    "Environment": "Sandbox",
    "SandboxBaseUrl": null,
    "LiveBaseUrl": null
  }
}

Registration

using DevSkill.SSLCommerz;
using DevSkill.SSLCommerz.Models;

builder.Services.Configure<SslCommerzSettings>(
    builder.Configuration.GetSection("SSLCommerz"));

builder.Services.AddSingleton<IGatewayClient, GatewayClient>();

To configure the underlying HttpClient (timeouts, proxies, resilience), register via the factory instead — the client accepts an injected HttpClient:

builder.Services.AddHttpClient<IGatewayClient, GatewayClient>();

Results and error handling

API calls never throw for transport, HTTP, or provider failures — they return SslCommerzResult<T>:

Caller errors (null requests, models failing data-annotation validation) throw synchronously before any I/O.

Request a payment session

using DevSkill.SSLCommerz;
using DevSkill.SSLCommerz.Models;

public sealed class CheckoutService(IGatewayClient gateway)
{
    public async Task<string?> StartPaymentAsync(string transactionId, CancellationToken ct = default)
    {
        var request = new TransactionSessionRequestBuilder()
            .AddIntegrationRequiredParameter(new IntegrationRequiredParameter(
                totalAmount: 1750.50m,
                currency: "BDT",
                transactionId: transactionId,
                successUrl: "https://yourapp.com/payment/success",
                failUrl: "https://yourapp.com/payment/fail",
                cancelUrl: "https://yourapp.com/payment/cancel"))
            .AddCustomerInformation(new CustomerInformation(
                customerName: "Rahim Uddin",
                customerEmail: "rahim@example.com",
                customerAddress1: "12 Uttara Sector 4",
                customerCity: "Dhaka",
                customerPostcode: "1230",
                customerCountry: "Bangladesh",
                customerPhone: "+8801700000000"))
            .AddShipmentInformation(new ShipmentInformation(shippingMethod: "NO"))
            .AddProductInformation(new ProductInformation(
                productName: "Dev Skill Course",
                productCategory: "Education",
                productProfile: "general"))
            .Build();

        var result = await gateway.RequestSessionAsync(request, ct);

        return result.Success ? result.Value!.GatewayPageUrl : null;
    }
}

On success, redirect the customer to result.Value.GatewayPageUrl. Money fields serialize with invariant culture (1750.50), and optional numeric fields left unset (Vat, DiscountAmount, NumberOfItem, …) are simply not sent.

Validate a transaction (Order Validation)

The authoritative money-state check — run it on your success/cancel/IPN callbacks before fulfilling anything:

var result = await gateway.ValidateTransactionAsync(
    new ValidationRequest { ValidationId = valId }, ct);

if (result.Success
    && result.Value!.Status == "VALID"
    && result.Value.TransactionId == expectedTransactionId
    && result.Value.CurrencyType == "BDT"
    && result.Value.Amount == expectedAmount)
{
    // The payment is real and belongs to this order — fulfil it
}

Handle an IPN

Verify the verify_sign checksum over the raw posted fields (never over a re-serialized model), then parse:

using DevSkill.SSLCommerz;
using DevSkill.SSLCommerz.Models;
using Microsoft.Extensions.Options;

[ApiController]
public sealed class IpnController(
    IOptions<SslCommerzSettings> settings,
    IGatewayClient gateway) : ControllerBase
{
    [HttpPost("/ipn")]
    public async Task<IActionResult> Receive(CancellationToken ct)
    {
        var form = await Request.ReadFormAsync(ct);
        var fields = form.ToDictionary(kv => kv.Key, kv => kv.Value.ToString());

        // 1. Verify the checksum over the raw field dictionary (fail-closed)
        var verifier = new VerifySignVerifier(settings.Value);
        if (!verifier.Verify(fields))
        {
            return Unauthorized();
        }

        // 2. Parse the notification into a typed model
        var notification = PaymentNotificationParser.Parse(fields);

        // 3. A valid signature is necessary, NOT sufficient — re-check money
        //    state via Order Validation before acting on it
        var validation = await gateway.ValidateTransactionAsync(
            new ValidationRequest { ValidationId = notification.ValidationId! }, ct);

        return Ok();
    }
}

JSON-body notifications are also supported: PaymentNotificationParser.ParseJson(body).

Query transactions

Search by session key or transaction id — for pending-payment sweeps and late-completion hunts:

var result = await gateway.QueryTransactionAsync(
    new TransactionQuery { TransactionId = "DSAB12CD" }, ct);

if (result.Success)
{
    foreach (var element in result.Value!)
    {
        // element.Status (VALID / PENDING / CANCELLED / FAILED, ...) is
        // transaction data for your reconciliation logic to decide on
    }
}

Upgrading from 3.x

v4 is a breaking overhaul:

• GatewayClient is now async behind IGatewayClient (RequestSessionAsync / ValidateTransactionAsync / QueryTransactionAsync) and returns SslCommerzResult<T> instead of tuples.
• Credentials come from SslCommerzSettings only — the Credential type and the builder's credential argument are gone.
• Environments.Development → SslCommerzEnvironment.Sandbox.
• Optional numeric request fields are nullable; unset fields are no longer sent as 0.
• Transport/HTTP/provider failures return error results instead of throwing during deserialization.

License

See License.txt.