Skip to main content

Installation

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

Prerequisites​

Before installing:

  • Xperience by Kentico 31.0.1 or later
  • XperienceCommunity.Commerce package installed
  • .NET 9 SDK
  • Lightning Enable subscription with API key
  • OpenNode account with API key

Step 1: Install NuGet Package​

Add the Lightning Enable Kentico package:

cd YourKenticoProject
dotnet add package LightningEnable.Kentico

This package includes:

  • IPaymentGateway implementation
  • Checkout UI components and Razor pages
  • JavaScript for payment polling
  • All required dependencies

Step 2: Configure Services​

Add Lightning payment gateway services in Program.cs:

using LightningEnable.Kentico.Extensions;

var builder = WebApplication.CreateBuilder(args);

// ... existing Kentico services

// Add Lightning payment gateway from configuration
builder.Services.AddLightningPaymentGatewayFromConfiguration(
    builder.Configuration,
    configurationSectionPath: "LightningGateway" // Optional, defaults to "LightningGateway"
);

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:

{
  "LightningGateway": {
    "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, use environment variables for sensitive values:

# Azure App Service / Environment Variables
LIGHTNING_GATEWAY__API_KEY=le_merchant_your-api-key-here
LIGHTNING_GATEWAY__WEBHOOK_SECRET=your-webhook-secret

Update appsettings.json to reference environment variables:

{
  "LightningGateway": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "ApiKey": "${LIGHTNING_GATEWAY__API_KEY}",
    "WebhookSecret": "${LIGHTNING_GATEWAY__WEBHOOK_SECRET}"
  }
}

Or use the .NET configuration system which automatically reads environment variables with __ as section separator:

// Configuration is automatically populated from:
// LIGHTNING_GATEWAY__API_KEY -> LightningGateway:ApiKey

Step 5: Add Webhook Controller​

Create a webhook receiver for payment notifications:

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

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

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

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

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

            _logger.LogWarning(
                "Webhook processing failed for order {OrderNumber}",
                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 API:

curl -X PUT https://api.lightningenable.com/api/admin/merchants/{id} \
  -H "X-API-Key: admin-key" \
  -d '{"callbackUrl": "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 OpenNode testnet

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("LightningGateway");
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

Payment Gateway Not Appearing​

Ensure the gateway is registered with XperienceCommunity.Commerce:

// The package auto-registers, but you can verify:
builder.Services.AddTransient<IPaymentGateway, LightningPaymentGateway>();

File Structure​

After installation, these files are added:

YourKenticoProject/
  ├── Pages/
  │   └── Checkout/
  │       ├── Lightning.cshtml
  │       ├── LightningSuccess.cshtml
  │       └── LightningCancel.cshtml
  ├── wwwroot/
  │   └── js/
  │       └── lightning-checkout.js
  └── appsettings.json (updated)

Next Steps​