Configuration

Complete configuration reference for the Lightning Enable Kentico Commerce integration.

Configuration Options

Full appsettings.json

{
  "LightningGateway": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "ApiKey": "le_merchant_your-api-key",
    "WebhookSecret": "your-webhook-secret",
    "CheckoutBaseUrl": "https://yoursite.com",
    "TimeoutSeconds": 30,
    "Environment": "production",
    "EnableLogging": true,
    "CacheStatusSeconds": 5
  }
}

Configuration Reference

Property	Type	Required	Default	Description
ApiBaseUrl	string	Yes	-	Lightning Enable API base URL
ApiKey	string	Yes	-	Your merchant API key
WebhookSecret	string	Recommended	-	HMAC secret for webhook verification
CheckoutBaseUrl	string	No	Auto-detected	Base URL for checkout redirects
TimeoutSeconds	int	No	30	HTTP client timeout in seconds
Environment	string	No	production	production or development
EnableLogging	bool	No	true	Enable detailed logging
CacheStatusSeconds	int	No	5	Status endpoint cache duration

Environment Variables

For production, use environment variables:

# Required
LIGHTNING_GATEWAY__API_KEY=le_merchant_your-production-key
LIGHTNING_GATEWAY__WEBHOOK_SECRET=your-production-secret

# Optional
LIGHTNING_GATEWAY__API_BASE_URL=https://api.lightningenable.com
LIGHTNING_GATEWAY__CHECKOUT_BASE_URL=https://yoursite.com
LIGHTNING_GATEWAY__TIMEOUT_SECONDS=30

Azure App Service

In Azure Portal > App Service > Configuration:

Name	Value
LIGHTNING_GATEWAY__API_KEY	le_merchant_...
LIGHTNING_GATEWAY__WEBHOOK_SECRET	whsec_...

Development vs Production

Development Configuration

{
  "LightningGateway": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "ApiKey": "le_merchant_dev_key",
    "Environment": "development",
    "EnableLogging": true,
    "CacheStatusSeconds": 1
  }
}

Use OpenNode testnet for development.

Production Configuration

{
  "LightningGateway": {
    "ApiBaseUrl": "https://api.lightningenable.com",
    "ApiKey": "${LIGHTNING_GATEWAY__API_KEY}",
    "WebhookSecret": "${LIGHTNING_GATEWAY__WEBHOOK_SECRET}",
    "Environment": "production",
    "EnableLogging": false,
    "CacheStatusSeconds": 5
  }
}

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.TimeoutSeconds = 30;
    options.EnableLogging = builder.Environment.IsDevelopment();
});

Payment Gateway Options

Invoice Expiration

Configure how long invoices remain valid:

builder.Services.AddLightningPaymentGateway(options =>
{
    // Invoice expires after 15 minutes (default)
    options.InvoiceExpiryMinutes = 15;

    // Shorter expiry for time-sensitive items
    // options.InvoiceExpiryMinutes = 5;
});

Currency Settings

Configure default currency:

builder.Services.AddLightningPaymentGateway(options =>
{
    options.DefaultCurrency = "USD";
    options.SupportedCurrencies = new[] { "USD", "EUR", "GBP", "BTC" };
});

Success/Cancel URLs

Configure redirect URLs:

builder.Services.AddLightningPaymentGateway(options =>
{
    options.SuccessUrlTemplate = "/checkout/lightning/success?order={orderId}";
    options.CancelUrlTemplate = "/checkout/lightning/cancel?order={orderId}";
});

Webhook Configuration

Webhook URL

Set in Lightning Enable dashboard:

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

Signature Verification

The webhook secret is used to verify webhook signatures:

// Automatically verified by the package
public async Task<IActionResult> HandleWebhook()
{
    var result = await _paymentGateway.HandleWebhookAsync(
        Request,
        HttpContext.RequestAborted);

    // Signature verification happens internally
    return result.Success ? Ok() : BadRequest();
}

Custom Webhook Handler

For custom webhook processing:

public class CustomWebhookHandler : IWebhookHandler
{
    public async Task HandleAsync(WebhookPayload payload)
    {
        switch (payload.Status)
        {
            case "paid":
                await ProcessPaidOrder(payload);
                await SendConfirmationEmail(payload);
                await UpdateInventory(payload);
                break;

            case "expired":
                await HandleExpiredPayment(payload);
                break;

            case "refunded":
                await ProcessRefund(payload);
                break;
        }
    }
}

// Register custom handler
builder.Services.AddScoped<IWebhookHandler, CustomWebhookHandler>();

Logging Configuration

Serilog Integration

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

Log Categories

Category	Level	Description
LightningEnable.Gateway	Information	Payment creation, status changes
LightningEnable.Webhook	Debug	Webhook processing details
LightningEnable.Http	Warning	HTTP client errors

Status Endpoint

The package exposes a public status endpoint:

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

Response

{
  "invoiceId": "inv_abc123",
  "status": "unpaid",
  "expiresAt": "2024-12-29T12:15:00Z"
}

Caching

Status responses are cached to reduce API load:

builder.Services.AddLightningPaymentGateway(options =>
{
    // Cache status for 5 seconds
    options.CacheStatusSeconds = 5;

    // Disable caching (development only)
    // options.CacheStatusSeconds = 0;
});

Health Checks

Add health checks for monitoring:

builder.Services.AddHealthChecks()
    .AddCheck<LightningGatewayHealthCheck>("lightning-gateway");

// In endpoint configuration
app.MapHealthChecks("/health");

public class LightningGatewayHealthCheck : IHealthCheck
{
    private readonly IPaymentGateway _gateway;

    public LightningGatewayHealthCheck(IPaymentGateway gateway)
    {
        _gateway = gateway;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken)
    {
        try
        {
            var isHealthy = await _gateway.CheckHealthAsync(cancellationToken);
            return isHealthy
                ? HealthCheckResult.Healthy("Lightning Gateway is healthy")
                : HealthCheckResult.Unhealthy("Lightning Gateway is unhealthy");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Lightning Gateway check failed", ex);
        }
    }
}

Troubleshooting

Configuration Not Loading

// Debug configuration
var section = builder.Configuration.GetSection("LightningGateway");
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
LIGHTNING_GATEWAY__API_KEY=value

# Incorrect
LIGHTNING_GATEWAY:API_KEY=value
LIGHTNING_GATEWAY_API_KEY=value

SSL/HTTPS Issues

For local development with HTTPS:

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

warning

Only use certificate bypass in development!

Next Steps

• Checkout Flow - Customize checkout
• Webhooks - Webhook implementation
• Testing - Test your integration