Skip to main content

Installation

This guide walks you through installing the Lightning Enable checkout integration in your Xperience by Kentico e-commerce site.

Prerequisites​

Before installing:

  • Xperience by Kentico 31.0.1 or later
  • .NET 8 SDK or later (the package targets net8.0 and runs in .NET 8 or .NET 9 host applications)
  • Lightning Enable subscription with API key
  • Payment provider account with API key — Strike (recommended) or OpenNode

No additional commerce packages are required — the integration has no dependency on XperienceCommunity.Commerce.

Step 1: Get the Package​

Package Availability

The LightningEnable.Kentico package (v1.0.0) is currently distributed during onboarding — contact support@lightningenable.com to receive it. A public NuGet listing is pending, so dotnet add package LightningEnable.Kentico will not find it on nuget.org yet.

Once you have the .nupkg, add it from a local package source:

cd YourKenticoProject
dotnet nuget add source ./packages --name local   # folder containing the .nupkg
dotnet add package LightningEnable.Kentico --source local

This package is a Razor Class Library that includes:

  • IPaymentGateway implementation
  • Checkout UI components and Razor pages (served from the package — nothing is copied into your project)
  • JavaScript for payment polling
  • A built-in webhook receiver at /api/webhooks/lightning

Step 2: Configure Services​

Register the Lightning Enable services in Program.cs:

using LightningEnable.Kentico.Extensions;

var builder = WebApplication.CreateBuilder(args);

// ... existing Kentico services

// Register Lightning Enable from configuration
builder.Services.AddLightningPaymentGatewayFromConfiguration(
    builder.Configuration,
    configurationSectionPath: "LightningEnable" // Optional, defaults to "LightningEnable"
);

var app = builder.Build();
// ... rest of application setup

Alternative: Configure via code:

using LightningEnable.Kentico.Extensions;

builder.Services.AddLightningPaymentGateway(options =>
{
    options.ApiBaseUrl = "https://api.lightningenable.com";
    options.ApiKey = "le_merchant_your-api-key-here";
    options.WebhookSecret = "your-webhook-secret";
    options.CheckoutBaseUrl = "https://yoursite.com"; // Optional
    options.TimeoutSeconds = 30; // Optional, defaults to 30
});

Step 3: Add Configuration​

Create the configuration section in appsettings.json:

{
  "LightningEnable": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "ApiKey": "le_merchant_your-api-key-here",
    "WebhookSecret": "your-webhook-secret-from-lightning-enable",
    "CheckoutBaseUrl": "https://yoursite.com",
    "TimeoutSeconds": 30
  }
}

Configuration Properties​

PropertyRequiredDefaultDescription
ApiBaseUrlYes-Lightning Enable API URL
ApiKeyYes-Your merchant API key
WebhookSecretRecommended-HMAC secret for webhook verification
CheckoutBaseUrlNoAuto-detectedBase URL for checkout redirects
TimeoutSecondsNo30HTTP client timeout

Step 4: Configure Environment Variables (Production)​

For production, keep sensitive values out of appsettings.json and supply them via environment variables. The .NET configuration system automatically maps environment variables to configuration keys using __ (double underscore) as the section separator:

# Azure App Service / Environment Variables
# LightningEnable__ApiKey -> LightningEnable:ApiKey
# LightningEnable__WebhookSecret -> LightningEnable:WebhookSecret
LightningEnable__ApiKey=le_merchant_your-api-key-here
LightningEnable__WebhookSecret=your-webhook-secret

Environment variables override values from appsettings.json, so you can keep non-sensitive settings in the file and let the environment supply the secrets:

{
  "LightningEnable": {
    "ApiBaseUrl": "https://api.lightningenable.com"
  }
}

Step 5: Webhook Receiver​

The package ships a built-in webhook controller at POST /api/webhooks/lightning — it verifies the HMAC signature, updates the Kentico order, and always returns 200 OK (to prevent webhook retries for bad data). For most installations no extra code is needed; skip to Step 6.

If you want custom handling, you can write your own receiver using IPaymentGateway.HandleWebhookAsync, which returns a WebhookResult with two properties: Handled (whether the webhook was successfully processed) and OrderNumber:

using LightningEnable.Kentico.Interfaces;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/webhooks/lightning-custom")]
public class CustomLightningWebhookController : ControllerBase
{
    private readonly IPaymentGateway _paymentGateway;
    private readonly ILogger<CustomLightningWebhookController> _logger;

    public CustomLightningWebhookController(
        IPaymentGateway paymentGateway,
        ILogger<CustomLightningWebhookController> logger)
    {
        _paymentGateway = paymentGateway;
        _logger = logger;
    }

    [HttpPost]
    public async Task<IActionResult> HandleWebhook()
    {
        try
        {
            var result = await _paymentGateway.HandleWebhookAsync(
                Request,
                HttpContext.RequestAborted);

            if (result.Handled)
            {
                _logger.LogInformation(
                    "Webhook processed successfully for order {OrderNumber}",
                    result.OrderNumber);
                return Ok();
            }

            _logger.LogWarning(
                "Webhook was not handled for order {OrderNumber} " +
                "(invalid signature or malformed payload)",
                result.OrderNumber);
            return BadRequest("Webhook validation failed");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error processing Lightning webhook");
            return StatusCode(500, "Internal server error");
        }
    }
}

Step 6: Configure Webhook URL​

In the Lightning Enable dashboard, set your webhook URL:

https://yoursite.com/api/webhooks/lightning

Or configure via the merchant self-service API:

curl -X PUT https://api.lightningenable.com/api/merchant/webhook-url \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl": "https://yoursite.com/api/webhooks/lightning"}'

Step 7: Verify Installation​

Test the installation:

  1. Start your site

    dotnet run

  2. Create a test order in your Kentico admin

  3. Select Lightning payment at checkout

  4. Verify the checkout page loads with QR code

  5. Test payment using your provider's testnet (Strike sandbox or OpenNode dev environment)

Troubleshooting​

"Service not registered" Error​

Ensure AddLightningPaymentGatewayFromConfiguration is called before app.Build():

// Correct order
builder.Services.AddLightningPaymentGatewayFromConfiguration(builder.Configuration);
var app = builder.Build();

"API key not configured" Error​

Check your configuration:

// Debug configuration loading
var config = builder.Configuration.GetSection("LightningEnable");
Console.WriteLine($"ApiKey present: {!string.IsNullOrEmpty(config["ApiKey"])}");

Webhook Not Receiving Events​

  1. Verify webhook URL is publicly accessible (not localhost)
  2. Check HTTPS is configured
  3. Review firewall rules
  4. Test with ngrok during development

IPaymentGateway Not Registered​

AddLightningPaymentGateway / AddLightningPaymentGatewayFromConfiguration registers IPaymentGateway for you. Verify the registration ran before builder.Build():

// Registered automatically by AddLightningPaymentGateway(...):
// services.AddScoped<IPaymentGateway, LightningPaymentGateway>();

What Ships in the Package​

The package is a Razor Class Library — no files are copied into your project. The pages, controllers, and static assets below are served directly from the package:

LightningEnable.Kentico (RCL)
  ├── Pages/Checkout/
  │   ├── Lightning.cshtml           →  /checkout/lightning/{invoiceId}
  │   ├── LightningSuccess.cshtml    →  /checkout/lightning/success
  │   └── LightningCancel.cshtml     →  /checkout/lightning/cancel
  ├── Controllers/
  │   └── LightningWebhookController →  POST /api/webhooks/lightning
  └── wwwroot/js/
      ├── lightning-checkout.js         (express checkout button)
      └── lightning-payment-poller.js   (payment status polling)

The only file you edit is your own appsettings.json (Step 3).

Next Steps​