Skip to main content

Configuration

Complete configuration reference for the Lightning Enable Kentico Commerce integration.

Configuration Options​

Full appsettings.json​

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

Configuration Reference​

LightningEnableOptions has exactly five settings:

PropertyTypeRequiredDefaultDescription
ApiBaseUrlstringYes-Lightning Enable API base URL
ApiKeystringYes-Your merchant API key (X-API-Key header)
WebhookSecretstringYes-HMAC secret for webhook signature verification
CheckoutBaseUrlstringNoFalls back to ApiBaseUrlBase URL for the checkout page where customers complete Lightning payments
TimeoutSecondsintNo30HTTP client timeout in seconds for API requests

Configuration is validated at application startup (fail-fast): missing ApiBaseUrl, ApiKey, or WebhookSecret — or a non-absolute URL in ApiBaseUrl/CheckoutBaseUrl — prevents the application from starting, with an error message identifying the invalid option.

Environment Variables​

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

# Required
LightningEnable__ApiKey=le_merchant_your-production-key
LightningEnable__WebhookSecret=your-production-secret

# Optional
LightningEnable__ApiBaseUrl=https://api.lightningenable.com
LightningEnable__CheckoutBaseUrl=https://yoursite.com
LightningEnable__TimeoutSeconds=30

Azure App Service​

In Azure Portal > App Service > Configuration:

NameValue
LightningEnable__ApiKeyle_merchant_...
LightningEnable__WebhookSecretyour-webhook-secret

Development vs Production​

Development Configuration​

{
  "LightningEnable": {
    "ApiBaseUrl": "http://localhost:5096",
    "ApiKey": "le_merchant_dev_key",
    "WebhookSecret": "dev-webhook-secret"
  }
}

Use your provider's test environment for development (Strike sandbox or OpenNode dev environment).

Production Configuration​

Keep non-sensitive settings in appsettings.json and let environment variables supply the secrets (environment variables override file values):

{
  "LightningEnable": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "CheckoutBaseUrl": "https://yoursite.com"
  }
}
LightningEnable__ApiKey=le_merchant_your-production-key
LightningEnable__WebhookSecret=your-production-secret

Code Configuration​

Configure via code instead of appsettings:

builder.Services.AddLightningPaymentGateway(options =>
{
    options.ApiBaseUrl = "https://api.lightningenable.com";
    options.ApiKey = Environment.GetEnvironmentVariable("LIGHTNING_API_KEY");
    options.WebhookSecret = Environment.GetEnvironmentVariable("WEBHOOK_SECRET");
    options.CheckoutBaseUrl = "https://yoursite.com"; // Optional
    options.TimeoutSeconds = 30; // Optional
});

Webhook Configuration​

Webhook URL​

Set in the Lightning Enable dashboard (the package ships a built-in receiver at this route):

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

Signature Verification​

The webhook secret is used to verify webhook signatures. IPaymentGateway.HandleWebhookAsync verifies the signature internally and returns a WebhookResult with two properties: Handled and OrderNumber:

// Signature verification happens inside HandleWebhookAsync
public async Task<IActionResult> HandleWebhook()
{
    var result = await _paymentGateway.HandleWebhookAsync(
        Request,
        HttpContext.RequestAborted);

    if (result.Handled)
    {
        // Order status was updated for result.OrderNumber
        return Ok();
    }

    // Invalid signature or malformed payload
    return BadRequest();
}

The built-in LightningWebhookController already does this for you (it always returns 200 OK to prevent webhook retries for bad data). You only need your own controller for custom handling — see the Installation guide.

Logging Configuration​

Serilog Integration​

builder.Host.UseSerilog((context, config) => config
    .ReadFrom.Configuration(context.Configuration)
    .MinimumLevel.Override("LightningEnable.Kentico", LogEventLevel.Debug)
    .WriteTo.Console()
    .WriteTo.File("logs/lightning-.txt", rollingInterval: RollingInterval.Day));

Log Categories​

Log categories follow the package's namespaces and type names, for example:

CategoryDescription
LightningEnable.Kentico.Services.LightningPaymentGatewayPayment session creation, webhook processing
LightningEnable.Kentico.Services.PaymentStatusPollingServiceStatus polling against the Lightning Enable API
LightningEnable.Kentico.Controllers.LightningWebhookControllerIncoming webhook requests

Override LightningEnable.Kentico to control the whole package.

Status Endpoint​

The package exposes a public status endpoint used by the embedded checkout UI:

GET /api/lightning/status/public/{invoiceId}

Status responses are cached server-side briefly to reduce load on the Lightning Enable API. The bundled lightning-payment-poller.js polls this endpoint (default: every 3 seconds) and invokes onPaid / onExpired / onFailed callbacks.

Troubleshooting​

Configuration Not Loading​

// Debug configuration
var section = builder.Configuration.GetSection("LightningEnable");
foreach (var child in section.GetChildren())
{
    Console.WriteLine($"{child.Key}: {(child.Key.Contains("Key") ? "***" : child.Value)}");
}

Environment Variables Not Reading​

Ensure double underscore separator:

# Correct
LightningEnable__ApiKey=value

# Incorrect
LightningEnable:ApiKey=value
LIGHTNING_ENABLE_API_KEY=value

SSL/HTTPS Issues​

For local development with HTTPS:

builder.Services.AddHttpClient("LightningEnable")
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
    {
        ServerCertificateCustomValidationCallback =
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    });
warning

Only use certificate bypass in development!

Next Steps​