Skip to main content

Admin API

The Admin API provides administrative control over merchants and subscriptions. All endpoints require the admin API key.

Internal Use Only

These endpoints are for administrative use only. They should never be exposed to merchants or end users.

Authentication​

All admin endpoints require the X-API-Key header with your admin API key:

curl https://api.lightningenable.com/api/admin/merchants \
  -H "X-API-Key: your-admin-api-key"

Rate Limiting​

Admin endpoints are limited to 30 requests per minute.

Merchant Management​

List All Merchants​

Get a summary list of all merchants.

GET /api/admin/merchants

Response​

[
  {
    "merchantId": 1,
    "name": "Acme Corp",
    "email": "api@acme.com",
    "planTier": "standaloneapi",
    "subscriptionStatus": "active",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "merchantId": 2,
    "name": "TechStartup Inc",
    "email": "billing@techstartup.io",
    "planTier": "l402microtransactions",
    "subscriptionStatus": "active",
    "isActive": true,
    "createdAt": "2024-02-20T14:15:00Z"
  }
]

Get Merchant Details​

Get detailed information about a specific merchant.

GET /api/admin/merchants/{merchantId}

Response​

{
  "merchantId": 1,
  "name": "Acme Corp",
  "email": "api@acme.com",
  "planTier": "standaloneapi",
  "subscriptionStatus": "active",
  "isActive": true,
  "hasOpenNodeKey": true,
  "hasWebhookUrl": true,
  "stripeCustomerId": "cus_abc123",
  "stripeSubscriptionId": "sub_xyz789",
  "createdAt": "2024-01-15T10:30:00Z",
  "features": {
    "refundsEnabled": true,
    "multiCurrencyEnabled": true,
    "analyticsEnabled": true,
    "prioritySupport": false,
    "customBrandingEnabled": false,
    "maxWebhookEndpoints": 3,
    "slaUptimePercentage": 99.5
  }
}

Register New Merchant​

Create a new merchant account manually (bypasses Stripe checkout).

POST /api/admin/merchants

Request Body​

FieldTypeRequiredDescription
namestringYesMerchant display name
emailstringYesMerchant email (must be unique)
openNodeApiKeystringNoOpenNode API key
callbackUrlstringNoWebhook callback URL

Request​

{
  "name": "New Merchant",
  "email": "merchant@example.com",
  "openNodeApiKey": "optional-opennode-key",
  "callbackUrl": "https://example.com/webhooks/lightning"
}

Response​

{
  "merchantId": 3,
  "name": "New Merchant",
  "email": "merchant@example.com",
  "apiKey": "le_merchant_abc123def456...",
  "createdAt": "2024-12-29T15:30:00Z"
}
warning

The apiKey is only returned once during creation. Store it securely - it cannot be retrieved later, only regenerated.

Update Merchant​

Update merchant settings.

PUT /api/admin/merchants/{merchantId}

Request Body​

FieldTypeDescription
namestringMerchant display name
emailstringMerchant email
openNodeApiKeystringOpenNode API key
callbackUrlstringWebhook callback URL
webhookSecretstringWebhook signing secret
planTierstringPlan tier (standaloneapi, kenticocommerce, l402microtransactions)
isActivebooleanAccount active status

Request​

{
  "name": "Updated Name",
  "planTier": "l402microtransactions"
}

Response​

Returns the updated merchant summary.

Regenerate API Key​

Generate a new API key for a merchant. The old key is immediately invalidated.

POST /api/admin/merchants/{merchantId}/regenerate-key

Response​

{
  "merchantId": 1,
  "apiKey": "le_merchant_new_key_xyz...",
  "regeneratedAt": "2024-12-29T15:45:00Z"
}
warning

Regenerating an API key immediately invalidates the old key. The merchant must update their integration with the new key.

Deactivate Merchant​

Disable a merchant account. Their API key will stop working.

POST /api/admin/merchants/{merchantId}/deactivate

Response​

HTTP/1.1 204 No Content

Reactivate Merchant​

Re-enable a previously deactivated merchant account.

POST /api/admin/merchants/{merchantId}/reactivate

Response​

HTTP/1.1 204 No Content

Pending Subscription Management​

When customers subscribe via Stripe, a pending subscription is created. These endpoints manage the approval workflow.

List Pending Subscriptions​

Get all pending subscriptions awaiting review.

GET /api/admin/pending-subscriptions

Query Parameters​

ParameterTypeDefaultDescription
includeProcessedbooleanfalseInclude approved/rejected subscriptions

Response​

[
  {
    "id": 1,
    "email": "new-customer@example.com",
    "customerName": "John Doe",
    "stripeCustomerId": "cus_abc123",
    "stripeSubscriptionId": "sub_xyz789",
    "planTier": "standaloneapi",
    "subscriptionStatus": "active",
    "createdAt": "2024-12-29T12:00:00Z",
    "isApproved": false,
    "isRejected": false,
    "reviewedAt": null,
    "rejectionReason": null,
    "linkedMerchantId": null
  }
]

Get Pending Subscription​

Get details of a specific pending subscription.

GET /api/admin/pending-subscriptions/{id}

Response​

Same format as list item above.

Approve Pending Subscription​

Approve a subscription and create (or link to) a merchant account.

POST /api/admin/pending-subscriptions/{id}/approve

Request Body​

FieldTypeRequiredDescription
merchantNamestringNoOverride merchant name (defaults to customer name or email)
openNodeApiKeystringNoPre-configure OpenNode API key
callbackUrlstringNoPre-configure webhook URL

Request​

{
  "merchantName": "Acme Corporation",
  "openNodeApiKey": "optional-key"
}

Response (New Merchant Created)​

{
  "merchantId": 5,
  "name": "Acme Corporation",
  "email": "new-customer@example.com",
  "apiKey": "le_merchant_abc123...",
  "createdAt": "2024-12-29T15:00:00Z"
}

Response (Linked to Existing Merchant)​

{
  "merchantId": 2,
  "name": "Existing Merchant",
  "email": "new-customer@example.com",
  "linked": true,
  "message": "Subscription linked to existing merchant: Existing Merchant"
}

Reject Pending Subscription​

Reject a pending subscription.

POST /api/admin/pending-subscriptions/{id}/reject

Request Body​

FieldTypeRequiredDescription
reasonstringNoReason for rejection (recommended)

Request​

{
  "reason": "Suspected fraudulent account"
}

Response​

HTTP/1.1 204 No Content

Error Responses​

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing admin API key"
}

404 Not Found​

{
  "error": "Merchant not found"
}

409 Conflict​

{
  "error": "A merchant with email 'example@email.com' already exists"
}

400 Bad Request​

{
  "error": "Subscription has already been processed"
}

Hangfire Dashboard​

The Hangfire dashboard for background job monitoring is available at:

https://api.lightningenable.com/hangfire

Access requires the admin API key in the X-Admin-Key header or as a query parameter.

Best Practices​

Security​

  • Store the admin API key securely (environment variable, secrets manager)
  • Never expose admin endpoints to the public internet
  • Rotate admin API key periodically
  • Use IP allowlisting if possible

Monitoring​

  • Regularly review pending subscriptions
  • Monitor for unusual merchant creation patterns
  • Set up alerts for failed subscription approvals

Automation​

Consider automating subscription approval for trusted email domains:

// Example: Auto-approve @company.com emails
const subscription = await getPendingSubscription(id);
if (subscription.email.endsWith('@company.com')) {
  await approveSubscription(id);
}

Next Steps​